tao-generate-video-reasoning-annotations

ビデオ推論アノテーションパイプライン

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

ビデオからマルチレベルのキャプション、構造化された説明、QA ペア（多肢選択式、二択式、自由回答式）を生成し、段階的な推論トレースを含む 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 — キャプション要件のチェックリスト。フェーズ 3 — nvidia_tao_ds.auto_label.video_reasoning_annotation.prompt_template の [PLACEHOLDER] マーカーを埋めます。上記の 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、またはその両方を指定します（リストはマージされます）。

出力

すべての出力は results_dir/ に保存されます。各ステップのサブディレクトリ（step_0_filter/、step_1a_caption/、…、step_4_output/）に分かれています。

• Steps 0–3：JSONL — 動画ごとに1行のJSONオブジェクト。
• Step 4：空でないタスクタイプごとに1つの <task>.json ファイルを、tao-vl-reason-v1.0 エンベロープ形式で出力します。最大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。

各 Step 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 を指定します。

前提条件

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