tao-generate-video-reasoning-annotations

视频推理标注流水线

通过生成多层级字幕、结构化描述和 QA 对（MCQ、二元问答、开放式问答），并附上逐步推理轨迹，从视频生成思维链（CoT）训练数据集。默认适用于任何领域；可自定义提示词以适配任意视频领域。

用途

将原始视频转换为用于视频理解模型的 CoT 问答训练数据。VLM（例如 Gemini、Qwen）充当“教师”标注员：步骤 0–1 要求模型观看视频（调用 VLM）；步骤 2–3 是文本到文本处理（调用成本更低的大模型）。

流水线架构

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] 标记。以上两个参考模块都是可供参考的有效示例。请在运行任何流水线之前完成此步骤。

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。
• 即使 vlm.backend 使用的是前沿视频模型，步骤 2–3 也仅处理文本，因此 llm.backend 可以使用更小、成本更低的大模型。

如果用户完全没有端点且想要自托管，请引导他们使用 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. 试运行与完整运行

• 当领域为 custom、编辑过任何提示词，或这是用户首次运行时，建议先试运行 5–10 个视频。
• 对于 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（续跑），也可使用新的目录（完整重跑）。

质量问题会在下游逐级累积——糟糕的字幕会产生糟糕的描述，进而产生糟糕的 QA。请先重点迭代改进步骤 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	""	可选：写入步骤 4 输出中的 metadata.license（例如 "CC-BY-4.0"）
description_extra	""	可选：在步骤 4 元数据中追加到每项任务描述的文本
prompts_module	""	自定义提示词模块的点分导入路径

提示词

• 内置（通用）：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：JSONL 文件列表，每行包含 {"video_path": "..."}。也接受 video 键；可包含额外字段。
• filter_field：可选的布尔字段，用于筛选 JSONL 条目。

请提供 video_root、input_jsonl_files，或同时提供两者（列表会合并）。

输出

所有输出都写入 results_dir/，并按步骤存放在子目录中（step_0_filter/、step_1a_caption/，…，step_4_output/）：

• 步骤 0–3：JSONL——每行一个视频对应的 JSON 对象。
• 步骤 4：每种非空任务类型生成一个 <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。

步骤 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 前缀后的视频路径。在规范中设置 license 和 description_extra，即可填充元数据。

前置条件

• 容器：tao_toolkit.pyt（通过 versions.yaml 解析为 nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt）。
• ffmpeg / ffprobe：生成分块字幕（步骤 1b）和提取精彩片段（步骤 1c）时必需。
• VLM 端点：至少需要一个——Gemini API 密钥或兼容 OpenAI 的端点。