tao-generate-image-grounding

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

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

(画像, キャプション) のペアを、画像ごとのグラウンディング済みアノテーションに変換します。アノテーションには、クリーニング済みキャプション、文字スパン付きの参照表現、各表現のピクセル座標系バウンディングボックスが含まれます。1 つの VLM（Gemini または OpenAI 互換の任意のエンドポイント）が両方のステップを処理します。

目的

参照表現モデルとグラウンディングモデル向けの、フレーズをグラウンディングした学習データを生成します。VLM は「教師」アノテーターとして動作します。ステップ 0 では画像を見ながらキャプションから参照表現を抽出し、ステップ 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": "..."} のようなオブジェクトである必要があります。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 推論マイクロサービス（セルフホスト、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"]。この場合、ステップ 0 の出力が results_dir/step_0_expression_extraction/annotations.jsonl に存在する必要があります。

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[] の bboxes は適切ですか？信頼度スコアは妥当ですか？
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 ファイルです。各行に 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:7.3.0-pyt
• API アクセス：少なくとも 1 つの VLM エンドポイント（Gemini API キー、または画像入力に対応した OpenAI 互換エンドポイント）