
名称	tao-generate-video-reasoning-annotations
描述	>- 多步骤视频标注流水线，将原始视频转换为思维链（Chain-of-Thought）训练数据——包括多层级字幕、结构化描述以及带推理过程的问答对（选择题、判断题、开放题）。通过VLM/LLM蒸馏实现。当用户想要“创建视频训练数据”、“生成视频QA数据集”、“从视频构建CoT推理轨迹”、“自动标注视频”或运行video_reasoning_annotation流水线时使用。触发词包括“视频标注”、“视频思维链”、“视频问答”、“思维链”、“视频字幕流水线”、“视频蒸馏”。
开源协议	Apache-2.0 compatibility: 需要Docker + nvidia-container-toolkit + 至少一个VLM端点（Gemini API密钥或OpenAI兼容端点）。 metadata:
作者	NVIDIA Corporation
版本	“0.1.0” allowed-tools: Read Bash Write tags: - 视频 - 标注 - 思维链 - 字幕生成 - QA生成 - VLM - LLM - 自动标注

视频推理标注流水线

独立安装？ 如果此会话未通过TAO技能库插件初始化，请先运行tao-setup技能（主机预检、凭据、跨技能发现）。

通过生成多层级字幕、结构化描述以及带逐步推理过程的问答对（选择题、判断题、开放题），从视频中生成思维链训练数据集。默认领域无关——可根据任何视频领域定制提示词。

目的

将原始视频转换为用于视频理解模型的 CoT Q&A 训练数据。VLM（例如Gemini、Qwen）充当“教师”标注器：步骤0–1需要模型查看视频（VLM调用）；步骤2–3是文本到文本（更便宜的LLM调用）。

流水线架构

步骤0:  [可选] 过滤和分类视频 → 保留领域相关，区分异常与正常
步骤1a: 全局+密集字幕 → VLM：叙事摘要 + 带时间戳的事件
步骤1b: 分块字幕 → VLM：固定时长片段微字幕
步骤1c: [可选，仅异常] 高亮 → LLM提取异常时间戳，VLM字幕剪辑
步骤2: 描述合成 → LLM：将字幕合成为结构化叙事
步骤3: QA生成 → LLM：多选题、判断题、开放题，带推理
步骤4: 解析输出 → 每个任务生成`tao-vl-reason-v1.0` JSON文件

步骤可通过workflow.steps单独选择。流水线内置断点续跑——每个步骤自动跳过已处理的视频，因此修改提示词后重新运行是安全的。

初始协商

用户调用此技能时，请按顺序询问这些问题。不要跳过——正确的领域和VLM访问权限可避免浪费运行。

1. 视频

视频目录路径和/或JSONL文件路径（每行包含{"video_path": "..."}）。
确认格式（优先.mp4；同时支持.avi、.mov、.mkv递归扫描）。

2. 领域——决定提示词选择

询问用户：“这些视频来自哪个领域？” 选择以下分支之一：

领域	操作
通用	使用默认提示词。设置`prompts_module: ""`（或省略）。内置的`nvidia_tao_ds.auto_label.video_reasoning_annotation.prompts`涵盖领域无关内容。
交通（CCTV路口、高速公路；不包括行车记录仪）	使用参考模块。设置`prompts_module: "nvidia_tao_ds.auto_label.video_reasoning_annotation.prompts_traffic"`，或将`references/prompts_traffic.py`复制到用户项目中，根据其具体摄像机角度进行调整，然后将`prompts_module`指向该副本。
仓库（工业场所CCTV——安全、运营、安防）	相同模式。设置`prompts_module: "nvidia_tao_ds.auto_label.video_reasoning_annotation.prompts_warehouse"`，或复制`references/prompts_warehouse.py`并调整。
自定义（任何其他领域）	先运行references/domain_adaptation.md中的工作坊。它指导：阶段1——用户希望模型回答的问题类型；阶段2——字幕需求清单；阶段3——填写`nvidia_tao_ds.auto_label.video_reasoning_annotation.prompt_template`中的`[占位符]`标记。上述两个参考模块是可参照的工作示例。在任何流水线运行之前完成。

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兼容（Qwen via vLLM、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. 试点vs全量运行

当领域为custom、任何提示词被编辑或这是用户首次运行时，建议进行5-10个视频的试点。
如果用户之前已在相同数据类型上验证过输出质量，则general / traffic / warehouse可进行全量运行。
流水线内置断点续跑，因此试点后接全量运行不会重新处理试点视频。

快速开始

流水线通过auto_label CLI在TAO工具包容器中运行：

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
# 然后设置: autolabel_type: "video_reasoning_annotation"

所有字段支持命令行上的Hydra点标记覆盖。完整YAML参考（每个字段、模型/端点设置、错误模式）请参阅references/configuration.md。

试点工作流

使用此方法进行5-10个视频的试点：

使用选定的prompts_module和workflow.mode在试点子集上运行流水线。
检查results_dir/step_1a_caption/captions.jsonl——字幕准确吗？是否捕获了正确级别的细节？
检查results_dir/step_3_qa/qa_output.jsonl——问题有意义吗？答案正确吗？推理逻辑合理吗？
如果质量不足：调整提示词（若领域定制则在prompts_module中调整，或者如果领域模块过度调整则回退到general），然后重新运行。流水线自动跳过已处理的视频。
满意后，通过将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个键，带[占位符]标记，用于领域定制。
参考模块（用于咨询的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以填充元数据。

先决条件

容器：nvcr.io/nvidia/tao/tao-toolkit:7.1.0-pyt。
ffmpeg / ffprobe：分块字幕（步骤1b）和高亮提取（步骤1c）必需。
VLM端点：至少一个——Gemini API密钥或OpenAI兼容端点。