tao-generate-referring-expressions

画像の参照表現パイプライン

KITTI 形式のバウンディングボックスラベルを持つ画像から、参照表現とグラウンディングのアノテーションを生成します。単一の VLM（Gemini または OpenAI 互換エンドポイント）が、オブジェクト領域ごとの説明、画像全体のキャプション、バウンディングボックスに結び付けられたグループ化グラウンディング表現、任意の二重確認検証の 4 つのステップを実行します。

目的

(image, KITTI labels) のペアを、豊富でグラウンディングされた参照表現を含む統一された annotations.jsonl に変換します。VLM は「教師」アノテーターとして機能します。ステップ 0～1 では画像を確認し、ステップ 2 ではステップ 0 の出力をグループ化して、グループ化表現とバウンディングボックスのリストを作成します。ステップ 3（任意）では、画像と照らし合わせてそれらのバウンディングボックスを再確認し、不一致を修正します。

パイプラインのアーキテクチャ

Step 0: Region expression  ──┐
                              ├──▶  Step 2: Grounding expression  ──▶  [Step 3: Double check]
Step 1: Image caption  ──────┘                                                   (optional)

• Step 0 (region_expr) — VLM が KITTI の各バウンディングボックスに対して、識別に役立つ短い表現（bbox_2d、type、color、description）を 1 つ生成します。
• Step 1 (image_caption) — VLM が、場所に依存しない画像全体のキャプションを生成します。
• Step 2 (grounding_expr) — VLM がステップ 0 のオブジェクトをグループ化表現にまとめ、各グループに対応するバウンディングボックスのリストを 1 つ返します。任意でステップ 1 のキャプションを追加のコンテキストとして使用できます。
• Step 3 (double_check) — VLM がステップ 2 の各バウンディングボックスを画像と照らし合わせて再確認します。一致しないものは削除し、わずかにずれているボックスは範囲を調整します。

ステップ 0 と 1 は、単一のスレッドプール内で並列に実行されます（どちらもシードレコードのみに依存します）。各ステップは独自の step_<N>_*/annotations.jsonl に書き込みます。再実行時は、workflow.force_reprocess: true が設定されていない限り、処理済みの画像をスキップします。

手順

初期設定

ユーザーがこのパイプラインを実行する場合は、次の手順を案内してください。

1. 画像：.jpg、.jpeg、または .png 画像が格納されているディレクトリ data.image_dir を尋ねます。

2. KITTI ラベル：画像ごとに 1 つの .txt ラベルファイルが格納されているディレクトリ data.kitti_label_dir を尋ねます。各ラベル行は KITTI 形式を使用する必要があります：<type> <truncated> <occluded> <alpha> <bbox_left> <bbox_top> <bbox_right> <bbox_bottom> ...。フィールドが 8 個未満の行は、通知なくスキップされます。ステップ 0 と 2 で必要となるため、ステップ 1 のみ実行する場合も設定してください。

3. 既存のアノテーションから再開：以前の実行で生成された統合済みの annotations.jsonl がすでにある場合は、data.image_dir と data.kitti_label_dir を初期データとして使用する代わりに、data.input_annotations_jsonl にそのファイルを設定します。

4. API アクセス：使用する VLM エンドポイントをユーザーに尋ねます。次の 5 つの選択肢を提示し、選択に応じて対応します。

   1. Gemini — vlm.backend: "gemini" を設定し、GOOGLE_API_KEY（環境変数または vlm.gemini.api_key）を必須とします。
   2. NIM（例：https://inference-api.nvidia.com/v1）— vlm.backend: "openai" を設定し、base_url、model_name、api_key を収集します。
   3. TAO 推論マイクロサービス（セルフホスト、OpenAI 互換）。サーバーがすでに起動しているか確認します。
      • 起動済み — base_url、model_name、および（任意で）api_key を収集し、vlm.backend: "openai" を設定します。
      • 未起動 — skills/applications/tao-run-inference-service スキルを使って、OpenAI 互換 API を備えたローカル TAO 推論マイクロサービスを起動する手順を案内します。特定のモデルを利用できると約束する前に、skills/applications/tao-run-inference-service/references/service.yaml の valid_network_arch_config_basenames を確認します。サーバーの起動後、base_url、model_name、および（任意で）api_key を収集し、vlm.backend: "openai" を設定します。
   4. vLLM（セルフホスト、OpenAI 互換）。サーバーがすでに起動しているか確認します。
      • 起動済み — base_url、model_name、および（任意で）api_key を収集し、vlm.backend: "openai" を設定します。
      • 未起動 — references/vllm_server.md に従って vLLM サーバーをインストールして起動し、その後 base_url、model_name、および（任意で）api_key を収集して、vlm.backend: "openai" を設定します。
   5. カスタム（その他の OpenAI 互換エンドポイント）— vlm.backend: "openai" を設定し、base_url、model_name、および（任意で）api_key を収集します。

   エンドポイントがなく、設定する意思もない場合は、いったん止めて、まず API アクセスの解決を支援してください。

5. ワークフローのステップ：次のいずれかを選択します。

   • パイプライン全体：["0", "1", "2", "3"]
   • キャプション生成なし：["0", "2", "3"]。この場合、ステップ 2 は画像のみのコンテキストにフォールバックします
   • 検証なし：["0", "1", "2"]
   • カスタムサブセット：サポートされている任意のステップの組み合わせ

6. 出力形式：次のいずれかを選択します。

   • jsonl：統合スキーマのみ
   • legacy：バイト単位で互換性のある .txt.stepN ファイルのみ
   • both：両方の形式を書き出します。後続のツールではこれがデフォルトです

パイプラインの実行

パイプラインは、auto_label CLI を介して TAO Toolkit コンテナ内で実行されます。

auto_label generate -e /path/to/spec.yaml \
    results_dir=/results \
    image_referring_expression.data.image_dir=/data/images \
    image_referring_expression.data.kitti_label_dir=/data/labels \
    image_referring_expression.vlm.gemini.api_key=$GOOGLE_API_KEY

デフォルトの仕様を生成します：auto_label default_specs results_dir=/results module_name=auto_label。次に、autolabel_type: "image_referring_expression" を設定します。すべてのフィールドで、コマンドライン上の Hydra ドット記法によるオーバーライドを使用できます。

YAML 構造全体、すべてのパラメーター、モデル／エンドポイントの設定、エラーパターンについては、references/configuration.md を参照してください。

推奨されるパイロットワークフロー

1. 5～10 枚の画像に対し、4 つのステップをすべて実行します。
2. step_0_region_expr/annotations.jsonl を確認します。オブジェクトの種類、色、識別に役立つ表現は正確ですか？
3. step_2_grounding_expr/annotations.jsonl を確認します。オブジェクトは適切にグループ化されていますか？bbox の座標は、説明されたグループと一致していますか？
4. step_3_double_check/annotations.jsonl を確認します。一致しない bbox は削除または調整されていますか？新たなエラーが発生していませんか（まれです）？
5. 品質が不十分な場合は、VLM をより高性能なモデル（例：gemini-2.5-pro または、より大規模な Qwen3-VL エンドポイント）に切り替え、media_resolution / max_output_tokens を引き上げてから、workflow.force_reprocess=true を指定して再実行します。
6. 問題がないことを確認したら、データセット全体に適用します。

設定

主な設定フィールド（詳細はreferences/configuration.mdを参照）：

フィールド	デフォルト	説明
workflow.steps	["0","1","2","3"]	実行するステップ（0=region_expr、1=image_caption、2=grounding_expr、3=double_check）
workflow.max_workers	4	各ステップの並列スレッド数（API のレート制限に注意してください）
workflow.force_reprocess	false	ステップごとのキャッシュ済み出力を無視し、最初から再処理します
workflow.output_format	"jsonl"（デフォルトの仕様では "both" に設定）	"jsonl"、"legacy"、または "both"
vlm.backend	"gemini"	"gemini" または "openai"（OpenAI 互換エンドポイント）
data.image_dir	必須	入力画像のディレクトリ（.jpg / .jpeg / .png）
data.kitti_label_dir	必須（再開時を除く）	KITTI 形式の .txt ラベルファイルのディレクトリ
data.input_annotations_jsonl	""	任意の事前シード済み annotations.jsonl（KITTI のシード処理をスキップします）

入力

パイプラインにシードデータを設定する方法は 2 通りあります。

1. 画像ディレクトリ + KITTI ラベル（デフォルト）。data.image_dir と data.kitti_label_dir を設定します。オーケストレーターは画像ディレクトリを走査し、対応する <stem>.txt KITTI ファイルを読み取って bbox（フィールド 0 および 4～7）を解析し、PIL で各画像の width / height を読み取り、results_dir/ に seed_annotations.jsonl を書き込みます。
2. 事前シード済みアノテーション JSONL（再開 / 事前計算済み領域）。data.input_annotations_jsonl に、各行に {"image_id", "image_path", "width", "height", "kitti_bboxes": [...]} オブジェクトが 1 つずつ記載されたファイルを指定します。

出力

すべての出力は results_dir/ に保存されます。

• seed_annotations.jsonl — 画像ごとの初期レコード（input_annotations_jsonl が指定されている場合を除く）。
• step_0_region_expr/annotations.jsonl — regions[]（それぞれに bbox / bbox_2d、type、color、description を含む）を追加します。
• step_1_image_caption/annotations.jsonl — caption（文字列）を追加します。
• step_2_grounding_expr/annotations.jsonl — expressions[]（各要素は {text, instances: [{bbox: [x1,y1,x2,y2]}]}）を追加します。
• step_3_double_check/annotations.jsonl — Step 2 と同じ形式で、bbox が削除または更新されています。
• results_dir/annotations.jsonl — 最後に完了したステップの出力のコピーです。
• workflow.output_format が "legacy" または "both" の場合、各ステップでは、元の 2d-data-engine ツール向けに、バイト互換の step_<N>_*/labels/<stem>.txt.stepN ファイルも書き込みます。

前提条件

• コンテナー：nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt
• API アクセス：少なくとも 1 つの VLM エンドポイント（Gemini API キー、または画像入力に対応する OpenAI 互換エンドポイント）
• PIL / Pillow：シード処理中に画像の寸法を読み取るために必要です（TAO コンテナーにすでに含まれています）