tao-generate-image-grounding

画像グラウンディングパイプライン

(image, caption) のペアを、画像ごとのグラウンディング済みアノテーションに変換します。アノテーションには、整形済みキャプション、文字範囲付きの参照表現、および各表現に対応するピクセル空間のバウンディングボックスが含まれます。1 つの VLM（Gemini または OpenAI 互換エンドポイント）が両方のステップを処理します。

目的

参照表現モデルとグラウンディングモデル向けの、フレーズ単位でグラウンディングされた学習データを生成します。VLM は「教師」アノテーターとして機能します。ステップ 0 では、画像を見ながらキャプションから参照表現を抽出し、ステップ 1 では、各画像の各表現について 1 セットのバウンディングボックスを返します。

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

Step 0: Expression extraction  → VLM cleans caption, extracts referring expressions + char spans
Step 1: Phrase grounding       → VLM returns pixel bboxes + scores per expression

各ステップは workflow.steps で個別に選択できます。各ステップはサンプルごとのチェックポイントを step_<N>_*/.ckpt/<sample_id>.json に書き込み、再実行時には処理済みのレコードをスキップします。チェックポイントを無視して最初から再処理するには、workflow.force_reprocess: true を設定します。

手順

初期設定

ユーザーがこのパイプラインを実行したい場合は、次の手順に沿って案内します。

1. 入力 JSONL：JSONL のパスを尋ねます。各行は {"image_path": "...", "caption": "..."} のようなオブジェクト 1 つである必要があります。image_path は絶対パスでも相対パスでもかまいません。

2. 画像ルート：image_path の値に相対パスが含まれる場合は、それらの解決先となるディレクトリを data.image_root に設定します。

3. 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 inference microservice（セルフホスト可能、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 アクセスの解決を支援します。

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

   • パイプライン全体：["0", "1"]
   • 表現抽出のみ：["0"]
   • グラウンディングのみ：["1"]。この場合、results_dir/step_0_expression_extraction/annotations.jsonl にステップ 0 の出力が存在する必要があります。

5. 再開または新規実行：ワークフローはデフォルトでチェックポイントを再利用し、完了済みのレコードをスキップします。すべてを再処理するには、image_grounding.workflow.force_reprocess=true を設定します。

パイプラインの実行

パイプラインは auto_label CLI を使って TAO Toolkit コンテナ内で実行します。

auto_label generate -e /path/to/spec.yaml \
    results_dir=/results \
    image_grounding.data.input_jsonl=/data/captions.jsonl \
    image_grounding.data.image_root=/data/images \
    image_grounding.vlm.gemini.api_key=$GOOGLE_API_KEY

デフォルトの仕様ファイルを生成します：auto_label default_specs results_dir=/results module_name=auto_label。その後、autolabel_type: "image_grounding" を設定します。すべてのフィールドは、コマンドラインで Hydra のドット記法によるオーバーライドに対応しています。

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

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

1. 両方のステップを実行し、5～10 枚の画像で試します
2. step_0_expression_extraction/annotations.jsonl を確認します。cleaned_caption と expressions[] は正確ですか？ 適切な名詞句が抽出されていますか？
3. step_1_grounding/annotations.jsonl を確認します。expressions[].instances[] の bbox は適切ですか？ 信頼度スコアは妥当ですか？
4. 品質が不十分な場合は、VLM をより高性能なモデル（例：gemini-2.5-pro）に切り替えるか、media_resolution／max_output_tokens の値を上げてから、force_reprocess=true を指定して再実行します。
5. 問題がないことを確認したら、データセット全体で実行します。

設定

主な設定項目（全項目については references/configuration.md を参照）：

項目	デフォルト	説明
workflow.steps	["0","1"]	実行するパイプラインのステップ（"0" = 表現、"1" = グラウンディング）
workflow.max_workers	4	ステップごとの並列スレッド数（API のレート制限に注意してください）
workflow.force_reprocess	false	サンプルごとのチェックポイントを無視し、最初から再処理します
vlm.backend	"gemini"	"gemini" または "openai"（OpenAI 互換エンドポイント）
data.input_jsonl	必須	1 行ごとに image_path と caption を含む入力 JSONL のパス
data.image_root	""	相対 image_path エントリの解決に使用する任意のプレフィックス

入力

data.input_jsonl に指定する単一の JSONL ファイルです。1 行につき JSON オブジェクトを 1 つ記述します。

項目	必須	説明
image_path	はい	絶対パス、または data.image_root を基準に解決する相対パス
caption	はい	画像の自由記述キャプション
image_id	いいえ	安定した識別子です。指定がない場合はファイル名から自動生成されます
width, height	いいえ	画像のピクセル単位の寸法です。指定がない場合、bbox の範囲制限には 1920×1080 が使用されます

出力

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

• step_0_expression_extraction/annotations.jsonl — cleaned_caption と expressions[]（各要素に text、expression_id、char_span、noun_chunk、空の instances[] を含む）が追加されたレコードごとの出力です。
• step_1_grounding/annotations.jsonl — 同じレコードに expressions[].instances[] を入力したものです（各インスタンスには、ピクセル座標空間の bbox: [x1,y1,x2,y2]、[0.0, 1.0] の範囲の score、bbox_id が含まれます）。
• results_dir/annotations.jsonl — 利便性のため、最後のステップの出力をコピーしたものです。
• step_<N>_*/.ckpt/<sample_id>.json — 再開に使用するサンプルごとのチェックポイントです。

前提条件

• コンテナー：nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt
• API アクセス：少なくとも 1 つの VLM エンドポイント（Gemini API キー、または画像入力に対応した OpenAI 互換エンドポイント）