tao-finetune-cosmos-reason

Cosmos-RL

在视频推理任务上对 nvidia/Cosmos-Reason2-8B 进行监督微调（SFT）。预训练权重来自 HuggingFace，而非 NGC。这是一个受限模型，需要 HF_TOKEN。

使用基于 FSDP 的并行方式，其中 dp_shard_size 用于设置 GPU 数量，dp_replicate_size 用于设置节点数量（而非标准的 num_gpus/num_nodes）。

适用场景

使用此技能训练、评估、量化或运行 Cosmos-Reason2-8B 推理，以处理视频问答和视频推理任务。核心工作流为：确认 HF_TOKEN 访问限制，抽样检查标注中的 video_fps，加载规格模板，应用下方关键训练覆盖项，然后通过平台技能启动（或在启用 AutoML 时使用 AutoML）。

Dataclass 架构

生成的 TAO Core 架构打包在 schemas/<action>.schema.json 中，schemas/manifest.json 列出了可用操作。每个生成的架构还会根据架构顶层的 default 字段生成 references/spec_template_<action>.yaml。AutoML 是否启用由模型层通过 references/skill_info.yaml 中的 automl_enabled 声明。要实际运行 AutoML，还必须存在并且能够解析 schemas/train.schema.json 和 references/spec_template_train.yaml。使用打包的训练架构获取 automl_default_parameters、automl_disabled_parameters、默认值、最小值/最大值范围、枚举、选项权重、数学条件、依赖项和热门参数。不要假设运行时存在 ~/tao-core；维护者会在打包技能库之前重新生成架构/模板。

训练操作策略

此模型在模型层启用了 AutoML。处理任何训练阶段请求之前，请先读取 references/skill_info.yaml，并根据明确指定的 automl_policy 值或用户的工作流请求，确定本次运行的覆盖项。将“关闭 AutoML”“禁用 AutoML”“不要 HPO”或“普通训练”等表述视为仅对本次运行设置 automl_policy: off；否则默认为 auto。当 automl_policy: auto、automl_enabled: true，且已打包 schemas/train.schema.json 和 references/spec_template_train.yaml 时，默认通过 tao-skill-bank:tao-run-automl 启动训练操作，并传入此模型的 skill_dir。保留工作流/应用针对数据集、规格、输出目录、GPU/平台设置、父检查点和 automl_policy 的覆盖项。仅在 automl_policy: off 或缺少已打包的训练架构/模板时，才直接训练模型；如果缺少架构，请说明此模型已启用 AutoML，但在生成架构之前无法运行 AutoML。

evaluate、inference、export 等非训练操作以及部署工作流仍由此模型技能处理。每次运行的 automl_policy 覆盖项不会更改模型元数据。

凭据

• HF_TOKEN（必需）：HuggingFace 访问令牌。用户必须先在 https://huggingface.co/nvidia/Cosmos-Reason2-8B 接受模型协议，并提供具有读取权限的令牌。该令牌以 docker_env_var 的形式传递给容器。

数据集

数据集类型为 vlm，格式为 llava；接受的意图包括训练、评估和测试。输入可以是数据集根目录（根目录模式会将 <root>/annotations.json 与 <root> 分别映射为标注文件和媒体路径），也可以是直接指定的 spec 键路径（适用于标注文件和媒体位于不同位置的情况）。启动训练、AutoML 或评估前，请抽样检查标注 JSON，并要求每条记录都包含 video_fps——缺少 video_fps 会导致 Cosmos-RL SFT 加载器在作业启动后报错：Error processing sample: 'video_fps'。如果缺少该字段，请在生成 runner 前停止，并要求用户修复标注文件；不要启动 AutoML 后再通过 torchrun 发现此问题。

请参阅 references/datasets.md，了解完整的训练要求、启动前信息确认提醒（spec 键选项、根目录模式映射、容器镜像确认，以及 check_tao_launch_preflight.py 的调用方式）、按操作划分的数据集要求表、带有直接覆盖示例的 data_sources 映射，以及评估数据集／自动拆分策略。

Spec 构建

cosmos-rl 的模式是 mode: config。始终从 references/spec_template_train.yaml 开始（评估时使用 spec_template_evaluate.yaml）——通过 yaml.safe_load(...) 加载模板，然后在其上应用用户覆盖项。模型使用的 spec 是嵌套字典，而不是扁平的点分隔键；点分隔覆盖表示嵌套 spec 中的路径，因此应沿路径遍历并在叶节点赋值。每项操作都必须覆盖数据源，且必须依据 references/datasets.md 中的按操作划分的数据集要求表构建。

请参阅 references/spec-construction.md，了解“加载模板后再覆盖”的模式，以及训练（包括 policy.model_max_length=81920、dp_shard_size／dp_replicate_size 和 LoRA 的 lora_alpha／r／lora_dropout）、评估、量化和推理的完整典型覆盖项；文档还说明，即使默认 spec 对象中没有 custom.val_dataset 的叶键，这些键仍然有效。

关键覆盖项（训练）

以下键的模板默认值有误，或省略它们会使运行切换到另一种模式：

参数	模板默认值	必需值	原因
policy.model_name_or_path	nvidia/Cosmos-Reason2-8B	hf_model://nvidia/Cosmos-Reason2-8B（或本地检查点）	裸 HF ID 会使 cosmos-rl 在运行时从 HF Hub 获取模型；hf_model:// URI 格式会在训练命令启动前预先下载权重
policy.model_max_length	40960	保持为 40960 或更高	小于约 40k 会导致视频输入出现 vision_embeds 形状不匹配
train.train_batch_per_replica	32	train.train_policy.mini_batch 的任意倍数	不匹配会立即触发 AssertionError
train.train_policy.type	"sft"	SFT 工作流中保持为 "sft"	如果在重新生成 Agent 时被删除，cosmos-rl 会切换到 RL 模式 → 分配 rollout 副本 → 尝试多节点运行 → 当 num_nodes=1 时出现主机名错误

参数

train.train_batch_per_replica 必须能被 train.train_policy.mini_batch 整除；视频 SFT 中 policy.model_max_length 必须为 40960 或更高；policy.parallelism.dp_shard_size 应等于每个节点的 GPU 数量，dp_replicate_size 应等于节点数；custom.vision.fps 和 custom.vision.nframes 互斥（必须且只能设置其中一个）。Cosmos-RL 模型有 8B 参数，采用多 GPU FSDP 分片可获得更好的效果——推荐配置：8 块 A100 或 H100（每块 80GB）。

请参阅 references/parameters.md，了解完整的参数参考：训练循环、模型与策略、并行化（包括多节点指南和平台技能指引）、优化与数据加载、视觉编码器（fps 与 nframes 的详细说明，以及 decord／torchvision 的故障模式）、检查点、验证、日志记录和硬件。

评估

评估器会读取一个扁平 TOML 配置，其中包含顶层键 dataset、model、task、evaluation、vision、generation、metrics、results、num_gpus、results_dir。任务类型为 ""（通用评估器，会自动检测二元是/否分类，并计算 TP/FP/TN/FN/准确率/精确率/召回率/F1）或 "its_directionality"（左/右/直行；请勿用于碰撞检测）。references/skill_info.yaml 中的 actions.evaluate 块声明了输入和输出；SDK 调用方式请参见 skills/platform/tao-run-platform/SKILL.md。

配置格式详情、任务类型说明、LoRA 评估（通过 spec_overrides 设置检查点路径，并使用 model.enable_lora/model.base_model_path 及适配器合并行为）、选择性下载（{annotation, format, keys} 部分媒体拉取），以及结果格式和指标，请参见 references/evaluate.md。

错误模式

常见故障包括训练时 CUDA OOM（减小 mini_batch 或增大 dp_shard_size）、LoRA 评估期间 OOM、损失为 NaN、vision_embeds 形状不匹配（将 model_max_length 增大到 40960）、train_batch_per_replica 不能被 mini_batch 整除、train_batch_per_replica 大于每个 rank 的样本数（导致 'NoneType' object has no attribute 'state_dict' 的 0 步崩溃）、更改 fps/total_pixels 后数据集缓存过期，以及受限仓库身份验证循环。

每种错误模式的完整诊断和修复方法，请参见 references/troubleshooting.md。

DEFT 支持与父模型推理

Cosmos-RL 实现了适用于视频 QA 任务的 DEFT 工作流契约（参见 config.json 和 workflow/deft/deft.md）。通过 scripts/analyze_gaps.py 进行的差距分析会读取 cosmos-rl results.json，按 .lower().strip() 后的精确字符串匹配来比较预测，并输出包含失败案例的 parquet 文件，因此评估提示词必须强制要求简短且受约束的回答。特定模型的父模型推理映射（evaluate/inference/quantize/train 规格字段 → 推理函数、检查点元数据和 parent_job_id 处理方式）位于参考文档中，而非 config.json。

差距分析详情及其限制，以及完整的父模型推理映射表，请参见 references/deft-and-inference-mappings.md。