tao-generate-referring-expressions

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

単独でインストールしますか？ このセッションが TAO スキルバンクプラグインによって初期化されていない場合は、まず tao-setup スキルを実行してください（ホストの事前チェック、認証情報、スキル間の検出）。

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

目的

(画像、KITTI ラベル) のペアを、豊富でグラウンディングされた参照表現を含む統一された 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)

• ステップ 0（region_expr） — VLM は、KITTI の各バウンディングボックスに対して、短く識別力のあるフレーズを 1 つ出力します（bbox_2d、type、color、description）。
• ステップ 1（image_caption） — VLM は、位置に依存しない画像全体のシーンキャプションを出力します。
• ステップ 2（grounding_expr） — VLM は、ステップ 0 のオブジェクトをグループ化フレーズにまとめ、各グループに対してバウンディングボックスのリストを 1 つ返します。追加のコンテキストとして、ステップ 1 のキャプションを任意で使用できます。
• ステップ 3（double_check） — VLM は、ステップ 2 の各バウンディングボックスを画像と照らし合わせて再確認します。不一致のものは削除され、少しずれているボックスは調整されます。

ステップ 0 と 1 は、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 を確認します。オブジェクトは適切にグループ化されていますか？また、バウンディングボックスの座標は説明されたグループと一致していますか？
4. step_3_double_check/annotations.jsonl を確認します。一致しないバウンディングボックスは削除または範囲を絞り込まれていますか？新たなエラーは発生していませんか（まれに発生します）？
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 ファイルを読み込み、バウンディングボックス（フィールド 0 + 4-7）を解析し、PIL で各画像の width / height を読み取って、results_dir/ に seed_annotations.jsonl を書き込みます。
2. シード済みアノテーション JSONL（再開 / 事前計算済み領域）。data.input_annotations_jsonl に、1 行につき 1 つの {"image_id", "image_path", "width", "height", "kitti_bboxes": [...]} オブジェクトを含むファイルを指定します。

出力

すべての出力は 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 と同じ形式で、バウンディングボックスを削除または更新します。
• results_dir/annotations.jsonl — 最後に完了したステップの出力のコピーです。
• workflow.output_format が "legacy" または "both" の場合、各ステップでは元の 2d-data-engine ツール用に、バイト互換の step_<N>_*/labels/<stem>.txt.stepN ファイルも書き込みます。

前提条件

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