# Pipeline de anotación

`lerobot-annotate` observa el video de cada episodio con un modelo de visión-lenguaje (VLM) y escribe anotaciones en lenguaje natural de vuelta en tu conjunto de datos. Rellena las dos columnas de lenguaje de la página [Language Columns and Recipes](./language_and_recipes) — `language_persistent` y `language_events` — directamente en `data/chunk-*/file-*.parquet`.

En resumen: dirígelo a un conjunto de datos de LeRobot y añade subtareas, planes, memoria, interjecciones, habla y preguntas y respuestas visuales sobre las que se puede entrenar una política.

## Cómo encaja todo

```text
  your dataset                  lerobot-annotate
  (LeRobotDataset v3.0)
        │
        ▼
  ┌─────────────────────────────────────────────────────┐
  │                    read episodes                     │
  └──────────────────────────┬──────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                     ▼
  ┌──────────┐      ┌───────────────┐        ┌──────────┐       one shared Qwen-VL
  │   plan   │      │ interjections │        │   vqa    │  ◀──   server (vLLM, OpenAI
  └────┬─────┘      └───────┬───────┘        └────┬─────┘        API) drives all three
       └────────────────────┼─────────────────────┘
                            │   each module stages raw JSONL
                            ▼   into .annotate_staging/
                  ┌─────────────────┐
                  │    validator    │  ◀──  checks everything
                  └────────┬────────┘
                           ▼
                  ┌─────────────────┐
                  │     writer      │
                  └────────┬────────┘
                           ▼
              data/chunk-*/file-*.parquet
              (+ meta/info.json tools)
```

Tres módulos (`plan`, `interjections`, `vqa`) se comunican con **un** VLM compartido. Cada módulo escribe su salida en disco, un validador la comprueba y un único escritor reescribe los fragmentos del conjunto de datos in situ.

## Lo que produce el pipeline

Cada módulo emite varios tipos de anotación ("estilos"), que se dirigen a una de las dos columnas de idioma:

| Estilo / átomo                                | Columna                | Módulo          |
| ------------------------------------------- | --------------------- | --------------- |
| `subtask` (estilo Pi0.7, "cómo, no qué")     | `language_persistent` | `plan`          |
| `plan` (inicial + actualización al interponerse)  | `language_persistent` | `plan`          |
| `memory` (compresión de estilo MEM)            | `language_persistent` | `plan`          |
| `task_aug` (reescrituras de la tarea)        | `language_persistent` | `plan`          |
| `interjection`                              | `language_events`     | `interjections` |
| átomo de llamada a herramienta de voz (`style=null`, `say`) | `language_events`     | `interjections` |
| `vqa` (par de usuario/asistente)               | `language_events`     | `vqa`           |

### Cómo se generan las subtareas

El módulo `plan` no le pide al VLM los subtareas de una sola vez. En su lugar, utiliza un flujo de dos pasos **describe → segment**:

1. **Describe** — el VLM narra solo lo que realmente ve en la cámara seleccionada (sin suposiciones sobre la tarea).
2. **Segment** — esa descripción se reintroduce y el VLM divide el episodio en subtareas atómicas consecutivas.

Ambos recorridos ven el episodio como **hojas de contacto con marcas de tiempo**: fotogramas muestreados a `frames_per_second` (0,5 s por defecto) y empaquetados en cuadrículas JPEG con el tiempo de cada fotograma grabado en su esquina, de modo que el VLM cite directamente los tiempos exactos de los límites. Esto es mucho más barato en tokens visuales que una imagen por fotograma, por lo que el muestreo puede mantenerse denso; los episodios más largos que `max_frames_per_prompt` se dividen en ventanas con la misma densidad y se fusionan. Ambos prompts también incluyen una definición causal de **límite de evento** (un nuevo evento comienza cuando un objeto es sostenido / se suelta / alcanza una nueva ubicación / una tapa cambia de estado / el contenido se mueve) para precisar dónde se colocan los cortes.

Opcionalmente, una tercera pasada de **seeded-relabel** (`--plan.subtask_seeded_relabel`) revisita cada span con sus hojas de contacto de segmento anterior/actual/siguiente y corrige mínimamente la etiqueta, utilizando la primera etiqueta como prior — mantiene los límites fijos y solo afina la redacción, a costa de una llamada extra por subtask.

A continuación, los tramos resultantes se unen para formar una cobertura completa del episodio, sin huecos, de modo que **cada fotograma tenga exactamente un subtarea activa**. Consulte [Running on Hugging Face Jobs](#running-on-hugging-face-jobs) para conocer la configuración de producción (cámara única, hojas de contacto con marcas de tiempo, generación automática de subtareas por ventanas).

### Herramientas

El escritor no **añade** una columna `tools` al parquet. El catálogo de herramientas se encuentra en `meta/info.json["tools"]` (ver [Herramientas](./tools)). Después de cada ejecución, el pipeline se asegura de que el esquema canónico `say` esté en esa lista, conservando las herramientas que hayas declarado previamente.

¿Quieres añadir tu propia herramienta? Edita directamente `meta/info.json["tools"]`: el pipeline conserva lo que ya esté presente. Esto hace que la herramienta sea visible para la plantilla de chat, de modo que el modelo pueda aprender a _generar_ la llamada. La capa de tiempo de ejecución que realmente _ejecuta_ una llamada generada (el protocolo `Tool` / `TOOL_REGISTRY` bajo `src/lerobot/tools/`) aún no está implementada: la documentación de [Tools](./tools) marca esas piezas como no implementadas.

## Ejecución en Hugging Face Jobs

Anotar un conjunto de datos real requiere una GPU lo suficientemente grande para servir el VLM, por lo que `lerobot-annotate` puede enviarse a [Hugging Face Jobs](https://huggingface.co/docs/hub/en/jobs), igual que `lerobot-train`. Añade `--job.target=<flavor>` al comando exacto que ejecutarías localmente y se ejecutará en ese hardware en su lugar:

```bash
hf auth login   # once

uv run lerobot-annotate \
    --repo_id=user/my_dataset \
    --new_repo_id=user/my_dataset_annotated \
    --push_to_hub=true \
    --vlm.model_id=Qwen/Qwen3.6-27B \
    --vlm.num_gpus=1 \
    --vlm.serve_command="vllm serve Qwen/Qwen3.6-27B --tensor-parallel-size 1 \
        --max-model-len 32768 --gpu-memory-utilization 0.8 \
        --uvicorn-log-level warning --port {port}" \
    --vlm.serve_ready_timeout_s=1800 \
    --vlm.chat_template_kwargs='{"enable_thinking": false}' \
    --job.target=h200
```

Eso envía un trabajo de GPU única `h200` que:

1. parte de la imagen `vllm/vllm-openai` e instala `lerobot` encima,
2. inicia un servidor vLLM por GPU y lo controla a través de la API compatible con OpenAI,
3. ejecuta los módulos `plan` / `interjections` / `vqa` en el conjunto de datos,
4. con `--push_to_hub=true`, sube el resultado a `--new_repo_id` (o de vuelta a `--repo_id` en su lugar si no lo configuras).

El comando transmite los registros del trabajo; `Ctrl-C` lo desconecta sin cancelarlo. Lista los sabores disponibles y su precio con `hf jobs hardware`.

Qwen3.6 se entrega con el modo de razonamiento activado, lo que consume el presupuesto de tokens que el anotador necesita para su respuesta en JSON — `--vlm.chat_template_kwargs='{"enable_thinking": false}'` lo desactiva. Sin `--push_to_hub=true`, el conjunto de datos anotado se descarta cuando el pod finaliza.

### Opciones de trabajo

| Flag                | Predeterminado                   | Qué hace                                                                    |
| ------------------- | ------------------------- | ------------------------------------------------------------------------------- |
| `--job.target`      | `local`                   | Sabor de HF Jobs en el que se ejecutará (p. ej. `h200`, `h200x4`). Omitido/`local` se ejecuta aquí.    |
| `--job.image`       | `vllm/vllm-openai:latest` | Imagen de runtime para el pod.                                                      |
| `--job.timeout`     | `2h`                      | Límite de tiempo real. Auméntelo para conjuntos de datos grandes.                                    |
| `--job.detach`      | `false`                   | Enviar y salir en lugar de transmitir registros.                                      |
| `--job.lerobot_ref` | `main`                    | Referencia de Git de lerobot instalada en el pod — apúntala a una rama para probar los cambios. |
| `--job.tags`        | `[]`                      | Etiquetas adicionales en el trabajo y en cualquier conjunto de datos que se suba (`lerobot` siempre se añade). |

Para un conjunto de datos más grande, escala a `h200x4` y aumenta `--vlm.parallel_servers` / `--vlm.num_gpus` en consecuencia, y otorga al trabajo más margen con, por ejemplo, `--job.timeout=8h`.

Las ejecuciones remotas requieren `--repo_id` (el pod descarga el conjunto de datos desde el Hub; `--root` designa un directorio que solo existe en tu máquina). Un conjunto de datos que solo existe en tu caché local se sube primero a un repositorio **privado**.

## Opciones principales

Estas son las opciones que más utilizarás. Ejecuta `lerobot-annotate --help` para ver el resto; los valores predeterminados están ajustados para episodios de manipulación cortos.

### Entrada / salida de datos

| Flag              | Predeterminado | Qué hace                                                            |
| ----------------- | ------- | ----------------------------------------------------------------------- |
| `--repo_id`       | —       | Conjunto de datos de Hub para anotar (se descarga si `--root` no está definido).                 |
| `--root`          | —       | Anote en su lugar un directorio de datos local.                             |
| `--new_repo_id`   | —       | Sube el resultado a un nuevo repositorio (deja el repositorio de origen intacto).       |
| `--push_to_hub`   | `false` | Subir después de anotar (a `--new_repo_id`, si no, de vuelta a `--repo_id`). |
| `--only_episodes` | todos     | Anote solo estos índices de episodios (útil para una ejecución de prueba).             |
| `--seed`          | `1729`  | Inicializa los generadores de números aleatorios (RNG) que seleccionan las marcas de tiempo de las intervenciones y los tipos de preguntas de VQA.  |

### Qué módulos se ejecutan

Cada módulo está activado de forma predeterminada y se puede alternar de manera independiente (establecerlo en `false` para omitirlo, por ejemplo, para trabajar en un módulo a la vez):

| Flag                      | Predeterminado | Desactiva                           |
| ------------------------- | ------- | ----------------------------------- |
| `--plan.enabled`          | `true`  | subtasks + plan + memory + task_aug |
| `--interjections.enabled` | `true`  | interjecciones + átomos del habla        |
| `--vqa.enabled`           | `true`  | los pares VQA                       |

### El VLM (`--vlm.*`)

| Flag                       | Predeterminado            | Qué hace                                                                         |
| -------------------------- | ------------------ | ------------------------------------------------------------------------------------ |
| `--vlm.model_id`           | `Qwen/Qwen3.6-27B` | El modelo a servir y el prompt.                                                       |
| `--vlm.camera_key`         | primero `images.*`   | En qué cámara se basa cada indicación.                                            |
| `--vlm.serve_command`      | auto               | El comando exacto `vllm serve …` (establece aquí el tamaño de TP, la memoria de GPU y `--max-model-len`).  |
| `--vlm.parallel_servers`   | `1`                | Servidores independientes para enrutamiento round-robin (uno por GPU).                           |
| `--vlm.num_gpus`           | `0`                | GPUs por servidor (`0` = una por cada uno).                                                    |
| `--vlm.client_concurrency` | `16`               | Solicitudes en curso en todos los servidores.                                               |
| `--vlm.max_new_tokens`     | `512`              | Límite de generación por llamada.                                                             |
| `--vlm.temperature`        | `0.2`              | Temperatura de muestreo.                                                                |
| `--vlm.reasoning_effort`   | `null`             | Pista de presupuesto de razonamiento (`low`/`medium`/`high`) reenviada a servidores compatibles con OpenAI. |

### Subtareas / plan / memoria (`--plan.*`)

| Flag                            | Predeterminado    | Qué hace                                                                                                                 |
| ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--plan.frames_per_second`      | `2.0`      | Tasa de muestreo de fotogramas para las hojas de contacto (`2.0` = un fotograma cada 0,5 s).                                                   |
| `--plan.max_frames_per_prompt`  | `60`       | Presupuesto de fotogramas por llamada a VLM. Los episodios cuya muestreación exceda este valor se enventanan automáticamente a la misma densidad y luego se unen.        |
| `--plan.contact_sheet_columns`  | `5`        | Columnas por cuadrícula de hoja de contactos (`contact_sheet_frames_per_sheet` mosaicos, fila de tiempo principal).                                     |
| `--plan.plan_max_steps`         | `8`        | Límite superior de subtareas por episodio.                                                                                         |
| `--plan.subtask_describe_first` | `true`     | Ejecuta el paso de anclaje describe→segment (mejor calidad de subtarea; +1 llamada/episodio).                                             |
| `--plan.subtask_seeded_relabel` | `false`    | Segunda pasada: reetiquetar cada subtarea a partir de sus hojas de contacto previas/actuales/siguientes, inicializada con la primera etiqueta (+1 llamada/subtarea). |
| `--plan.subtask_relabel_frames` | `5`        | Marcos muestreados uniformemente por hoja de segmento en el paso de reetiquetado (solo se usa cuando `subtask_seeded_relabel=true`).               |
| `--plan.emit_plan`              | `true`     | Emite las filas numeradas de `plan` (`false` = solo subtasks + memoria).                                                            |
| `--plan.emit_memory`            | `true`     | Emite las filas de `memory` (`false` = solo subtasks + plan); simétrico a `emit_plan`.                                           |
| `--plan.n_task_rephrasings`     | `10`       | Cuántas reformulaciones de `task_aug` emitir (`0` las desactiva).                                                                      |
| `--plan.derive_task_from_video` | `if_short` | Use la tarea del conjunto de datos tal como está (`off`), solo cuando falta o es corta (`if_short`), o derive siempre desde el vídeo (`always`).    |

### Interjecciones + VQA

| Flag                                            | Predeterminado | Qué hace                                               |
| ----------------------------------------------- | ------- | ---------------------------------------------------------- |
| `--interjections.max_interjections_per_episode` | `3`     | Límite de pares de interjección/discurso por episodio.              |
| `--vqa.vqa_emission_hz`                         | `1.0`   | Con qué frecuencia se emiten los pares VQA.                           |
| `--vqa.restrict_to_default_camera`              | `false` | Funde la VQA solo en `--vlm.camera_key` (de lo contrario, en todas las cámaras). |
| `--vqa.coordinate_scale`                        | `1000`  | Cuadrícula de bbox/keypoint de VLM, almacenada como [0, 1] (`none` = px).    |
| `--executor.episode_parallelism`                | `16`    | Episodios procesados de forma concurrente dentro de cada fase.         |

## Contribuir con nuevos módulos

The pipeline is built to grow, and **contributions are very welcome** — a brand-new module (say, trajectory traces or affordances), a new prompt template, a smarter grounding flow, or quality fixes to the existing `plan` / `interjections` / `vqa` modules.

Cada módulo se encuentra bajo `src/lerobot/annotations/steerable_pipeline/modules/`, comparte el cliente VLM y la caché de fotogramas clave, escribe su salida cruda en el árbol de staging y se integra en el executor como su propia fase. ¿Tienes una idea? Abre un issue o PR en [el repositorio](https://github.com/huggingface/lerobot).

## Cómo las recetas consumen la salida

Las anotaciones están destinadas a ser leídas por las recetas (consulte [Columnas de idioma y recetas](./language_and_recipes)). Típicamente:

- Las ramas de bajo nivel / alto nivel / actualización de memoria leen `subtask` / `plan` / `memory` desde `language_persistent`.
- una rama de interjección-respuesta lee eventos de `interjection` junto con el átomo de habla emparejado (fusionado en un solo turno del asistente mediante `tool_calls_from`) y la actualización correspondiente de `plan` en el mismo timestamp.
- Una rama de VQA lee las parejas `(vqa, user)` y `(vqa, assistant)` de `language_events`.

## Por qué se separan el estado y los eventos

Dos ideas dan forma al diseño:

1. **Estado persistente frente a eventos exactos.** Las filas persistentes (`subtask`, `plan`, `memory`) se aplican a todo el episodio y responden a la pregunta «¿qué es cierto ahora mismo?». Las filas de eventos (`interjection`, `vqa`, habla) aparecen solo en el fotograma cuyo timestamp coincide. Los timestamps se copian directamente del parquet de origen: nunca se recalculan en coma flotante.
2. **Un solo paso de VLM.** Los tres módulos comparten un único cliente de VLM (el cliente compatible con OpenAI que se comunica con el servidor vLLM del trabajo), por lo que se paga por una sola carga de modelo por conjunto de datos, no por tres.

## Volver a ejecutar un solo módulo

Cada módulo almacena su salida cruda en `<root>/.annotate_staging/episode_{N:06d}/<module>.jsonl`. Esto hace que la iteración de prompts sea económica: volver a ejecutar un módulo solo sobrescribe su propio JSONL y luego el escritor recompones el parquet final. Deshabilita los módulos que no quieras con `--plan.enabled=false` (y de forma similar `--interjections.enabled` / `--vqa.enabled`) para probarlos uno a la vez.

## Lo que comprueba el validador

Antes de que el escritor se ejecute, `StagingValidator` confirma:

- cada fila de eventos coincide exactamente con una marca de tiempo real de un fotograma;
- no quedan pares de habla / interjección huérfanos;
- `plan` se actualiza en cada marca de tiempo de interrupción;
- Las filas de `memory` caen en los límites de los subtareas (una advertencia, no un error);
- cada `content` del asistente de VQA es un JSON válido en una de las formas bbox / keypoint / count / attribute / spatial;
- cada fila va a la columna elegida por `column_for_style(style)`.

Cualquier error interrumpe el escritor. Pasa `--skip_validation=true` para anularlo durante la depuración.

## De dónde provienen las ideas de cada módulo

- **`plan` — subtareas.** Hi Robot ([Shi 2025](https://arxiv.org/abs/2502.19417)) para granularidad atómica ("recoger una hoja de lechuga", "colocar el cuenco en la caja"); Pi0.7 ([Physical Intelligence 2025](https://pi.website/pi07)) para el detalle de "cómo, no qué".
- **`plan` — memoria.** MEM ([Torne 2026](https://arxiv.org/abs/2603.03596)): conserva solo la información mínima relevante: preserva los resultados y descarta los atributos específicos.
- **`interjections`.** Taxonomía de escenarios de Hi Robot: tarea negativa, corrección situada, restricción específica, preferencia. El habla es un átomo solo de llamada a herramienta (`tool_calls=[{type:function, function:{name:"say", arguments:{text:...}}}]`).
- **`vqa`.** ECoT ([Zawalski 2024](https://arxiv.org/abs/2407.08693)) para características con anclaje (bounding boxes `[x_min, y_min, x_max, y_max]` y keypoints, almacenados como fracciones de imagen en [0, 1]) y Steerable VLA Policies ([Zhao 2025](https://arxiv.org/abs/2509.07626)) para anclaje multi-nivel de abstracción. Pi0.7 también ancla las respuestas a través de niveles de abstracción.

Al mejorar un módulo, ajusta su plantilla de prompt en `src/lerobot/annotations/steerable_pipeline/prompts/` en lugar de reescribirla desde cero.

## Aproximadamente cuánto cuesta

Por episodio, el pipeline realiza aproximadamente `plan_max_steps` llamadas de plan, `max_interjections_per_episode` llamadas de interrupción y `vqa_emission_hz × episode_seconds` llamadas de VQA. Con los valores predeterminados (8 subtareas, 3 interrupciones, 1 Hz × 3 pares) en un episodio de 30 segundos, eso son unas 50 llamadas de VLM.

El almacenamiento se mantiene pequeño: `language_persistent` ocupa como máximo decenas de KB por episodio (parquet codifica con diccionario la única entrada que se repite entre fotogramas) y `language_events` está vacío en la mayoría de los fotogramas: su tamaño escala con el número de emisiones, no con `num_frames × num_emissions`.

