tao-generate-video-reasoning-annotations

動画推論アノテーションパイプライン

動画からマルチレベルのキャプション、構造化された説明、QA ペア（MCQ、二択、自由回答）を生成し、段階的な推論トレースを含む Chain-of-Thought（CoT）トレーニングデータセットを作成します。デフォルトではドメインに依存しません。プロンプトをカスタマイズすれば、どのような動画ドメインにも対応できます。

目的

生の動画を、動画理解モデル向けの CoT Q&A トレーニングデータに変換します。VLM（Gemini、Qwen など）が「教師」アノテーターとして機能します。ステップ 0〜1 ではモデルが動画を見る必要があるため VLM を呼び出し、ステップ 2〜3 はテキスト間の処理なので、より低コストな LLM 呼び出しで実行できます。

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

Step 0:  [Optional] Filter & classify videos  → Keep domain-relevant, classify anomaly vs normal
Step 1a: Global + dense captions               → VLM: narrative summary + timestamped events
Step 1b: Chunk captions                         → VLM: fixed-duration segment micro-captions
Step 1c: [Optional, anomaly only] Highlight     → LLM extracts anomaly timestamp, VLM captions clip
Step 2:  Description synthesis                  → LLM: synthesize captions into structured narrative
Step 3:  QA generation                          → LLM: MCQ, binary, open-ended with reasoning
Step 4:  Parse outputs                          → Per-task `tao-vl-reason-v1.0` JSON files

workflow.steps を使って、個々のステップを選択できます。パイプラインには再開機能が組み込まれており、各ステップでは処理済みの動画がスキップされます。そのため、プロンプトを調整した後に再実行しても安全です。

初回の相談

ユーザーがこのスキルを呼び出したら、次の質問を順番に確認します。省略しないでください。ドメインと VLM へのアクセスを最初に正しく設定すれば、無駄な実行を防げます。

1. 動画

• 動画ディレクトリへのパス、および／または各行に {"video_path": "..."} を含む JSONL。
• 形式を確認します（.mp4 を推奨します。.avi、.mov、.mkv も検索されます）。

2. ドメイン — プロンプトの選択に影響します

ユーザーに「これらの動画はどのドメインのものですか？」と尋ねます。次の分岐から選びます。

ドメイン	対応方法
general	デフォルトのプロンプトを使います。prompts_module: "" を設定するか、省略します。組み込みの nvidia_tao_ds.auto_label.video_reasoning_annotation.prompts が、ドメインに依存しないコンテンツをカバーします。
traffic（交差点や高速道路の CCTV。ドライブレコーダーは対象外）	リファレンスモジュールを使います。prompts_module: "nvidia_tao_ds.auto_label.video_reasoning_annotation.prompts_traffic" を設定するか、references/prompts_traffic.py をユーザーのプロジェクトにコピーして、個々のカメラアングルに合わせて調整し、コピー先を prompts_module に指定します。
warehouse（産業施設の CCTV — 安全、運用、セキュリティ）	同じ方法で設定します。prompts_module: "nvidia_tao_ds.auto_label.video_reasoning_annotation.prompts_warehouse" を設定するか、references/prompts_warehouse.py をコピーして調整します。
custom（その他のドメイン）	references/domain_adaptation.md のワークショップを実施します。ユーザーがモデルに回答させたい質問の種類を確認するフェーズ 1、キャプション要件のチェックリストを作成するフェーズ 2、nvidia_tao_ds.auto_label.video_reasoning_annotation.prompt_template 内の [PLACEHOLDER] マーカーを埋めるフェーズ 3 を順に進めます。上記 2 つのリファレンスモジュールを、作成例として参考にしてください。パイプラインを実行する前に実施します。

3. 異常／正常／混在

• 混在データセット → workflow.mode: "auto"（ステップ 0 で各動画を分類します）。
• 事前に分割された異常のみのデータセット → workflow.mode: "anomaly" を設定し、ステップ 0 を削除します。
• 事前に分割された正常のみのデータセット → workflow.mode: "normal" を設定し、ステップ 0 と 1c を削除します。

4. VLM／LLM エンドポイント — 実行前にアクセスを確認

• Gemini（vlm.backend と llm.backend の両方でデフォルト）：ユーザーは GOOGLE_API_KEY を設定するか、キーを YAML に記述する必要があります。
• OpenAI 互換（vLLM 経由の Qwen、NIM エンドポイントなど）：ユーザーが base_url、model_name、api_key を指定します。
• ステップ 2〜3 はテキストのみの処理です。vlm.backend が最先端の動画モデルであっても、llm.backend にはより小型で低コストな LLM を使えます。

ユーザーにエンドポイントがなく、セルフホストを希望する場合は、skills/applications/tao-run-inference-service スキルを案内します。このワークフローでは、ネットワーク固有の TAO 推論マイクロサービスをローカルで起動し、OpenAI 互換エンドポイントを公開します。Cosmos、Qwen、Gemma に対応しているはずです。特定のモデルに依存する前に、skills/applications/tao-run-inference-service/references/service.yaml で現在の valid_network_arch_config_basenames リストを確認してください。

ユーザーがエンドポイントにアクセスできず、まだセットアップする準備もできていない場合は、ここで止めて、まず問題の解決を支援してください。

5. パイロット実行と本番実行

• 5～10 本のパイロットを推奨するのは、ドメインが custom の場合、いずれかのプロンプトを編集した場合、またはユーザーの初回実行である場合です。
• 本番実行で問題ないのは、general / traffic / warehouse について、ユーザーが以前に同じデータ型で出力品質を検証済みの場合です。
• パイプラインにはレジューム機能が組み込まれているため、パイロットに続けて本番実行しても、パイロットの動画が再処理されることはありません。

クイックスタート

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

auto_label generate -e /path/to/spec.yaml \
    results_dir=/results \
    video_reasoning_annotation.data.video_root=/videos \
    video_reasoning_annotation.vlm.gemini.api_key=$GOOGLE_API_KEY \
    video_reasoning_annotation.workflow.mode=auto

開始点としてデフォルトのスペックを生成します。

auto_label default_specs results_dir=/results module_name=auto_label
# then set:  autolabel_type: "video_reasoning_annotation"

すべてのフィールドは、コマンドラインで Hydra のドット記法によるオーバーライドをサポートしています。完全な YAML リファレンス（すべてのフィールド、モデル／エンドポイントの設定、エラーパターン）については、references/configuration.md を参照してください。

パイロットワークフロー

5～10 本のパイロットを実行する場合は、こちらを使用します。

1. 選択した prompts_module と workflow.mode を使用して、パイロットサブセットでパイプラインを実行します。
2. results_dir/step_1a_caption/captions.jsonl を確認します — キャプションは正確で、適切な詳細レベルを捉えていますか？
3. results_dir/step_3_qa/qa_output.jsonl を確認します — 質問は意味があり、回答は正確で、推論は論理的ですか？
4. 品質が不十分な場合：プロンプトを調整し（ドメインカスタマイズ済みなら prompts_module 内で、ドメインモジュールが過剰にチューニングされているなら general にフォールバック）、再実行します。パイプラインは処理済みの動画を自動的にスキップします。
5. 満足したら、data.video_root（または data.input_jsonl_files）をデータセット全体に向けて、同じ results_dir（レジューム）または新しい results_dir（完全な再実行）で再実行し、全データセットにスケールします。

品質は下流に複合的に影響します — 悪いキャプションは悪い説明を生み、それが悪い QA を生みます。まず Step 1a/1b の出力に反復を集中してください。キャプションが正しくなれば、説明と QA は通常改善します。

設定の概要

主要なフィールド（完全なリファレンスは references/configuration.md）：

フィールド	デフォルト	説明
workflow.steps	["0","1a","1b","1c","2","3","4"]	実行するパイプラインステップ
workflow.mode	"auto"	"auto"、"anomaly"、または "normal"
vlm.backend	"gemini"	"gemini" または "openai"（OpenAI 互換）
llm.backend	"gemini"	同じ選択肢。テキスト専用で、より安価なモデルでも動作します
workflow.max_workers	4	ステップごとの並列スレッド数（API レート制限に注意）
license	""	任意：step 4 の出力の metadata.license に書き込まれます（例："CC-BY-4.0"）
description_extra	""	任意：step 4 のメタデータでタスクごとの説明に追記される追加テキスト
prompts_module	""	カスタムプロンプトモジュールへのドット区切りのインポートパス

プロンプト

• 組み込み（general）：nvidia_tao_ds.auto_label.video_reasoning_annotation.prompts — ドメイン非依存で、デフォルトで使用されます。
• テンプレート：nvidia_tao_ds.auto_label.video_reasoning_annotation.prompt_template — 同じ 26 個のキーを持ち、ドメインカスタマイズ用の [PLACEHOLDER] マーカーが付いています。
• 参照モジュール（コンサルテーションの traffic / warehouse ブランチ向けの動作する例）：references/prompts_traffic.py、references/prompts_warehouse.py。
• カスタムドメイン：完全なワークショップとプレースホルダーのリファレンスについては、references/domain_adaptation.md を参照してください。

入力

• video_root：動画のディレクトリ（.mp4、.avi、.mov、.mkv を再帰的に探索）。
• input_jsonl_files：各行に {"video_path": "..."} を持つ JSONL ファイルのリスト。video キーも受け付けられます。追加のフィールドも許可されます。
• filter_field：JSONL エントリをフィルタリングするための任意のブール型フィールド。

video_root、input_jsonl_files、またはその両方を指定します（リストはマージされます）。

出力

すべての出力は、ステップごとのサブディレクトリ（step_0_filter/、step_1a_caption/、…、step_4_output/）を含む results_dir/ に保存されます。

• ステップ 0～3：JSONL — 動画ごとに 1 行の JSON オブジェクトです。
• ステップ 4：空でないタスクタイプごとに、tao-vl-reason-v1.0 エンベロープ形式の <task>.json が 1 つ生成されます。最大 10 個のファイルです：mcq.json、mcq_openended.json、bcq.json、bcq_openended.json、open_qa.json、causal_linkage.json、temporal_localization.json、temporal_description.json、scene_description.json、video_summarization.json。

各ステップ 4 のファイルは次の形式です。

{
  "format": "tao-vl-reason-v1.0",
  "metadata": {"type": "annotation", "task": "<task>", "date": "YYYY-MM-DD",
               "description": "<per-task + description_extra>", "license": "<from config>"},
  "media_root": "<data.video_root>" | null,
  "items": [{"video_id": "...", "question": "...", "answer": "...", "reasoning": "..."}, ...]
}

media_root は data.video_root を反映します（未設定の場合は null）。各項目の video_id は、video_root のプレフィックスを取り除いたエントリーの動画パスです。メタデータを設定するには、spec で license と description_extra を指定します。

前提条件

• コンテナ：tao_toolkit.pyt（versions.yaml を介して nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt に解決されます）。
• ffmpeg / ffprobe：チャンクのキャプション生成（ステップ 1b）とハイライトの抽出（ステップ 1c）に必要です。
• VLM エンドポイント：少なくとも 1 つ必要です — Gemini API キーまたは OpenAI 互換エンドポイント。