アノテーションパイプライン

lerobot-annotate は、ビジョン言語モデル (VLM) を用いて各エピソードの動画を監視し、自然言語によるアノテーションをデータセットに書き戻します。Language Columns and Recipes ページで定義されている 2 つの言語カラム、language_persistent と language_events に値を埋め込み、data/chunk-*/file-*.parquet に直接反映します。

要するに、LeRobotデータセットを指定するだけで、ポリシーの学習に使用できるサブタスク、計画、メモリ、割り込み、音声、視覚Q&Aが追加されます。

全体像

  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)

3つのモジュール（plan、interjections、vqa）はすべて、1つの共有VLMと通信します。各モジュールは出力をディスクにステージングし、バリデータがそれを検証し、単一のライターがデータセットのシャードをその場で書き換えます。

パイプラインが生成するもの

各モジュールは、いくつかの種類のアノテーション（「スタイル」）を出力し、それらは2つの言語カラムのいずれかにルーティングされます。

サブタスクの生成方法

planモジュールは、VLMにサブタスクを一度に要求しません。代わりに、describe → segmentの2段階のフローを使用します。

1. Describe — VLMは選択したカメラで実際に確認できる内容のみを説明します（タスクに関する推測は行いません）。
2. Segment — その説明がフィードバックされ、VLM がエピソードを連続するアトミックなサブタスクに分割します。

両方のパスは、エピソードをタイムスタンプ付きのコンタクトシートとして認識します。これはframes_per_second（デフォルトは0.5秒）でサンプリングされたフレームをJPEGグリッドにパックし、各フレームの隅にその時刻を焼き込んだものです。これにより、VLMは境界の正確な時刻を直接引用できます。1フレーム1画像に比べ、ビジョントークンの消費が大幅に少なくなるため、サンプリングを高密度に保つことができます。max_frames_per_promptを超える長さのエピソードは、同じ密度でウィンドウに分割され、マージされます。また、両方のプロンプトには、カットの位置を明確にするための因果的なイベント境界の定義（オブジェクトが保持される/解放される/新しい位置に到達する/蓋の状態が変わる/内容物が移動するときに新しいイベントが始まる）が含まれています。

任意で、3番目のseeded-relabelパス（--plan.subtask_seeded_relabel）を実行すると、各スパンについて、その前/現在/次のセグメントのコンタクトシートを参照しながら、最初のラベルを事前情報として用いてラベルを最小限に修正します。この処理では境界は固定され、表現の明確化のみが行われますが、サブタスクごとに1回の追加呼び出しが発生します。

生成されたスパンは、ギャップのないエピソード全体のカバーに縫い合わされ、すべてのフレームにちょうど1つのアクティブなサブタスクが割り当てられます。本番環境の設定（単一カメラ、タイムスタンプ付きコンタクトシート、自動ウィンドウ化されたサブタスク生成）については、Hugging Face Jobsでの実行を参照してください。

ツール

writer は parquet に tools 列を追加しません。ツールカタログは代わりに meta/info.json["tools"] に格納されています（Tools を参照）。各実行のたびに、パイプラインは正規の say スキーマがそのリストに含まれていることを確認し、事前に宣言したツールを保持します。

独自のツールを追加したい場合は、meta/info.json["tools"]を直接編集してください。パイプラインは、すでに存在する内容を保持します。これによりツールがチャットテンプレートに公開され、モデルが呼び出しを生成することを学習できます。生成された呼び出しを実際に実行するランタイムレイヤー（src/lerobot/tools/配下のToolプロトコル / TOOL_REGISTRY）はまだ実装されていません。Toolsドキュメントでは、これらの部分が未実装と明記されています。

Hugging Face Jobsでの実行

実際のデータセットのアノテーションには、VLMをサーブするのに十分な大きさのGPUが必要です。そのため、lerobot-annotateはlerobot-trainと同様に、Hugging Face Jobsに自身をディスパッチできます。ローカルで実行する予定の正確なコマンドに--job.target=<flavor>を追加すると、代わりにそのハードウェア上で実行されます:

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

単一GPUのh200ジョブを送信します。このジョブは以下を実行します:

1. vllm/vllm-openaiイメージを起点として、その上にlerobotをインストールします。
2. GPUごとに1つのvLLMサーバーを起動し、OpenAI互換APIを介して操作します。
3. データセット全体でplan / interjections / vqaモジュールを実行します。
4. --push_to_hub=true を指定すると、結果を --new_repo_id にアップロードします（--repo_id を設定しない場合、元の --repo_id に上書きしてアップロードします）。

このコマンドはジョブのログをストリーミング表示します。Ctrl-Cでキャンセルせずにデタッチできます。hf jobs hardwareで利用可能なフレーバーとその価格一覧を表示できます。

Qwen3.6はデフォルトでthinkingが有効になっていますが、これによりアノテーターがJSONの回答に必要とするトークン予算を消費してしまいます。--vlm.chat_template_kwargs='{"enable_thinking": false}'を指定することでこれを無効にできます。--push_to_hub=trueを指定しないと、podが終了した際にアノテーション済みデータセットが破棄されます。

ジョブのオプション

より大きなデータセットを使用する場合は、h200x4 にスケールアップし、--vlm.parallel_servers / --vlm.num_gpus をそれに合わせて引き上げ、例えば --job.timeout=8h のようにしてジョブに余裕を持たせてください。

リモート実行には--repo_idが必要です（ポッドはHubからデータセットを取得します。--rootは、あなたのマシンにのみ存在するディレクトリを指定します）。ローカルキャッシュにのみ存在するデータセットは、まずprivateリポジトリにプッシュされます。

主要なオプション

これらは最も頻繁に使用するフラグです。その他のオプションについてはlerobot-annotate --helpを実行してください。デフォルト値は、短い操作エピソード用に調整されています。

入出力用データセット

どのモジュールが実行されるか

すべてのモジュールはデフォルトで有効になっており、独立して切り替えることができます（falseに設定するとスキップされます。例えば、モジュールを1つずつ反復処理する場合など）：

VLM（--vlm.*）

サブタスク / プラン / メモリ ( --plan.* )

間投詞 + VQA

新しいモジュールの貢献

このパイプラインは拡張を前提として構築されており、貢献を大歓迎しています。例えば、トラジェクトリー・トレースやアフォーダンスといった全く新しいモジュール、新しいプロンプト・テンプレート、より賢いグラウンディング・フロー、あるいは既存のplan / interjections / vqaモジュールの品質改善などです。

すべてのモジュールはsrc/lerobot/annotations/steerable_pipeline/modules/の下に配置され、VLMクライアントとキーフレームキャッシュを共有し、生出力をステージングツリーに書き込み、独自のフェーズとしてエグゼキュータに組み込まれます。アイデアがあれば、リポジトリでissueまたはPRを作成してください。

レシピが出力を消費する方法

アノテーションはレシピによって読み取られることを想定しています（言語カラムとレシピを参照）。一般的には、以下のようになります。

• low-level / high-level / memory-update ブランチは、language_persistent から subtask / plan / memory を読み取ります。
• 中断応答ブランチは、interjectionイベントと、対応する発話アトム（tool_calls_fromを介して1つのアシスタントターンにマージされる）および、同じタイムスタンプの対応するplanリフレッシュを読み取ります。
• VQAブランチはlanguage_eventsから(vqa, user)および(vqa, assistant)のペアを読み取ります。

ステートとイベントが分離されている理由

設計を形作る2つの考え:

1. 永続状態と正確なイベント。 永続行（subtask、plan、memory）はエピソード全体に適用され、「今まさに真実であることは何か？」という問いに答えます。イベント行（interjection、vqa、発話）は、タイムスタンプが一致する1フレームのみに表示されます。タイムスタンプはソースの parquet からそのままコピーされ、浮動小数点で再計算されることはありません。
2. VLMパスは1回のみ。 3つのモジュールはすべて単一のVLMクライアント（ジョブのvLLMサーバーと通信するOpenAI互換クライアント）を共有するため、データセットごとにモデルの読み込みコストは1回分のみで済みます。

単一モジュールの再実行

各モジュールは、生の出力を<root>/.annotate_staging/episode_{N:06d}/<module>.jsonlにステージングします。これにより、プロンプトの反復が低コストになります。1つのモジュールを再実行すると、そのモジュール自身のJSONLのみが上書きされ、その後、ライターが最終的なparquetを再構成します。テストを1つずつ行うには、不要なモジュールを--plan.enabled=false（同様に--interjections.enabled / --vqa.enabled）で無効にしてください。

バリデータがチェックする内容

ライターの実行前に、StagingValidatorが以下を確認します:

• すべてのイベント行が実際のフレームのタイムスタンプに正確に一致します。
• 孤立した発話/間投詞のペアが残っていないこと;
• plan は、各割り込みタイムスタンプで更新されます。
• memory の行がサブタスクの境界に位置する場合（警告であり、エラーではありません）;
• 各VQAアシスタントのcontentは、bbox / keypoint / count / attribute / spatial のいずれかの形式で、有効なJSONです。
• 各行はcolumn_for_style(style)によって選択された列に格納されます。

エラーが発生すると、ライターは中断されます。デバッグ中は--skip_validation=trueを渡して上書きできます。

各モジュールのアイデアの由来

• plan — サブタスク。 Hi Robot（Shi 2025）はアトム粒度（「レタスの1枚を拾う」、「ボウルを箱に置く」）に対応し、Pi0.7（Physical Intelligence 2025）は「何を」ではなく「どのように」行うかという詳細に対応します。
• plan — メモリ。 MEM（Torne 2026）: 最小限の関連情報のみを保持します — 結果を保持し、具体的な属性は削除します。
• interjections。 Hi Robot のシナリオ分類体系: negative task、situated correction、specific constraint、preference。発話は tool-call 専用のアトムです (tool_calls=[{type:function, function:{name:"say", arguments:{text:...}}}])。
• vqa. 根拠付き特徴（バウンディングボックス [x_min, y_min, x_max, y_max] およびキーポイント、[0, 1] の画像比率として保存）には ECoT（Zawalski 2024）、マルチ抽象レベルのグラウンディングには Steerable VLA Policies（Zhao 2025）を使用します。Pi0.7 もまた、抽象レベルをまたいで回答をグラウンディングします。

モジュールを改善する際は、ゼロから書き直すのではなく、src/lerobot/annotations/steerable_pipeline/prompts/内のプロンプトテンプレートを調整してください。

おおよそのコスト

エピソードごとに、パイプラインは約plan_max_steps回のプラン呼び出し、max_interjections_per_episode回の割り込み呼び出し、およびvqa_emission_hz × episode_seconds回のVQA呼び出しを行います。デフォルト設定（サブタスク8、割り込み3、1 Hz × 3ペア）で30秒のエピソードの場合、VLMの呼び出しは約50回になります。

ストレージは小さく保たれます: language_persistent はエピソードあたり最大数十 KB 程度です（parquet はフレーム間で繰り返し出現する 1 つのエントリを辞書符号化します）。また、language_events はほとんどのフレームで空です。そのサイズは num_frames × num_emissions ではなく、エミッションの数に比例して増加します。