tao-finetune-cosmos-reason

Cosmos3 TAO 训练

保留一个共享的模型端前端。后端图像字段和合约路径位于 references/skill_info.yaml 的 backend_contracts 下；图像字面值取自 versions.yaml，而被引用的后端 YAML 定义原生运行时架构。两者之间绝不进行转换。

必需的运行时信息收集

规划训练之前，请收集以下所有信息。不得根据历史记录、其他用户、先前的作业、图像或开发者检出推断路径。

• base_model_path_or_uri。对于 Hugging Face 模型 ID 或 URL，可选填友好的 base_model_revision，例如分支或标签。若未填写，则解析 main；不要向用户索要提交 SHA。通过 Hub API 以只读方式将所选引用解析为不可变提交，并在计划中锁定模型 ID、请求的引用和解析出的 SHA。完整的本地快照无需修订版本，并通过其文件指纹锁定。
• 对于 Cosmos3-Nano，必须明确指定输入检查点的 model_type：qwen3_vl 或 cosmos3_omni。如果用户未提供，规划前询问一次；绝不要根据 config.json、模型 ID、路径名称或之前的运行推断选项。用通俗语言解释这两个选项：qwen3_vl 可直接使用兼容的 Hugging Face 检查点，而 cosmos3_omni 需要先进行不可变转换，将其精确转换为 Qwen3-VL safetensors，然后才能训练。将答案记录为 base_model_format。Cosmos3-Edge 根据解析出的模型 ID 推断为 cosmos3_edge，无需提供这个仅适用于 Nano 的选项。
• 正常收集信息时，不要公开 Omni 准备流程的实现字段。对于 Nano，使用 Qwen/Qwen3-VL-8B-Instruct，将两个 Hub 模型都解析为不可变提交，并运行所选后端打包的转换器。Framework 使用 cosmos_framework.scripts.convert_model_to_vlm_safetensors；Cosmos-RL 使用 cosmos_rl.model_preparation.vlm_safetensors 及其固定版本的隔离转换器运行时。验证明确提供的 prepared_checkpoint_path 或供体模型，但默认绝不索要这些信息。
• 直接接受 hf_model://nvidia/Cosmos3-Nano。如果受限或私有模型无法解析，只要求用户在会话环境中设置 HF_TOKEN；绝不要要求用户查找 SHA，也不要让用户在聊天中提供令牌值。
• 明确指定视频采样模式：统一使用 nframes 或使用 fps。FPS 模式还可设置 min_frames 和 max_frames；两种模式都可设置所选后端支持的片段时间、缩放和像素预算字段。
• 用于对话式或任务感知型视频监督的训练／验证标注路径和媒体根目录，以及可选的任务选择。
• 用于对比时明确指定 backend；可选 cosmos-framework 或 cosmos-rl。
• training_mode；可选 dense 或 peft。PEFT 还要求提供 rank、alpha、dropout、目标模块、bias、RS-LoRA、要保存的模块和适配器精度。
• 用户自有的 results_dir、checkpoint_dir、cache_dir；对于 SLURM，还需提供 sqsh_cache_dir、ssh_key_path、挂载路径和调度器设置。
• 运行时顺序：计算节点可读取的 sqsh_path、显式指定的图像，然后是 references/skill_info.yaml 中所选后端的图像。在 SLURM 上，将其复用或转换一次并存放在 sqsh_cache_dir 下。绝不要将 SQSH 文件名与图像标签进行比较，也不要索要来源证明／SHA。
• 仓库路径、提交／树、分支、基础图像、构建上下文和时间戳都是高级输入，只有明确要求 source-build 时才需要。请参阅 references/cosmos-backend-operations.md；绝不要根据运行时选择推断需要构建。

规划器会保留每个原始路径，并报告可访问的 realpath。缺少必需路径时会失败。若提供的 SQSH 缺失，则失败；若未提供 SQSH，则选择打包的图像。不允许回退到任何历史路径或图像。

Nano 检查点模型类型选择

将所选的 base_model_format 视为用户的决定，并验证其与提供的本地检查点的 config.json.model_type 相符。不匹配时必须失败；这并不意味着可以重新标记或改写源检查点。

对于 qwen3_vl，直接对完整且兼容的 Hugging Face Nano 检查点进行指纹识别并使用它。对于 cosmos3_omni，在启动审核中告知用户，Cosmos-RL 会自动准备兼容的检查点，说明计划的输出路径，并保持源检查点不变。不要要求用户提供架构供体、准备镜像或准备 SQSH。 由后端负责的准备步骤会在所选平台的用户所有 checkpoint_dir 下生成经过验证的 qwen3_vl 检查点：

• Docker：本地 Docker 主机的 checkpoint_dir。
• SLURM：经计算节点验证的共享 checkpoint_dir，并由显式容器挂载覆盖。通过 SLURM/Pyxis 契约运行转换；不要将转换后的检查点写入控制器本地存储。

使用打包的 Nano 架构映射和所选后端运行时，除非用户明确提供了高级覆盖。对源、架构映射、转换后的 config/tokenizer/processor/index/shards 以及转换来源进行指纹识别。在转换之前，将封存计划中的后端原生训练字段和 VLM_SAFETENSORS_PATH 绑定到所选容器内计划转换后的检查点。训练前验证该确切输出，不得修改封存计划。原始 Omni/Hugging Face 路径仅保留作来源记录，绝不能继续作为运行时模型路径。只有在目标路径的转换来源完整且匹配，并通过相同验证时，才允许复用。

公开 Cosmos3-Edge 检查点契约

在解析出的不可变修订版本或本地快照上接受公开模型；绝不要求提供第二个检查点。 应用 references/skill_info.yaml 和 references/cosmos-framework-backend.yaml 中针对模型的运行时默认值，同时保留独立的模型和处理器配置文件指纹，以及每个默认值/覆盖值的来源。

后端选择

首先运行 scripts/cosmos_workflow.py resolve。

请求	自动选择
Cosmos3-Nano 普通训练	Cosmos-RL（兼容性默认值）
Cosmos3-Nano AutoML/HPO	Cosmos-RL
Nano Framework-DCP 导出	Cosmos Framework
未显式指定后端的 Nano 评估/推理/微服务	Cosmos-RL
Nano 量化	Cosmos-RL
Cosmos3-Edge 训练/导出/评估/推理/微服务	Cosmos Framework

显式指定受支持的后端时，以该后端为准，因此用户可以为 Nano 训练选择 Cosmos Framework，而无需更改模型所有权。对比运行不接受 auto，因此实验双方都会被有意强制指定后端。 使用 Framework 训练的检查点会通过原生精确键导出器处理，然后交由基于仓库的 TAO 评估适配器。这并不意味着 Framework 是 Cosmos-RL 的某个版本。

评估接收与继承

每个评估操作都运行 scripts/evaluation_workflow.py，并完整遵循 references/cosmos-reason-evaluate.md。父训练计划拥有所有可继承的模型、数据集、提示词、预处理、精度、检查点和评分字段；绝不要要求用户重复提供这些字段。只针对助手的 required_user_inputs 询问一次，执行其 automated_actions，并且只启动校验和有效且 ready=true 的计划。Cosmos-RL 策略检查点必须使用生成的 cosmos_rl_checkpoint_pre_action；Framework DCP 输入必须使用其生成的导出预处理操作。就绪计划包含经过验证的 spec_bundle.execution；应原样将其传递给所选平台。Cosmos 负责运行时证明和评估器配置；平台负责启动。

Framework 检查点前置操作

在执行 Framework 评估、推理或微服务操作前，运行 scripts/framework_checkpoint_action.py plan 及其输出的 prepare 和 verify 步骤。遵循 references/cosmos-backend-operations.md；切勿要求用户手动导出 DCP。在 SLURM 上，仅暂存 workflow_contract.action_helper_dependencies 声明的辅助依赖集；平台会验证完整封闭的依赖包。仅使用已验证的 action_model_path，仅重复使用匹配的完整导出，并记录前置操作、清单、指纹和独立的子结果。

必需的门控

按顺序执行这些阶段，并持久化其输出。

1. 解析模型、后端和操作，并加载所选后端的契约。
2. 仅通过检查凭据是否存在来验证凭据。绝不读取或持久化凭据 值。仅在需要令牌的操作中要求提供令牌。
3. 按规定的收集顺序验证工具、存储、路径和运行时选择；已有 SQSH 和打包镜像模式跳过源代码门槛。
4. 仅在明确选择 source-build 时，验证并构建干净的源代码，并验证 /opt/tao/image-provenance.json。绝不将主机源代码挂载到训练环境。
5. 强制要求明确选择 Nano 检查点模型类型。如果选择 cosmos3_omni，在启动审核中显示转换操作和由平台管理的输出路径， 然后在获得批准后，通过所选干净后端镜像中打包的共享 TAO 集成入口 准备模型。自动将 URI/模型 ID 引用解析为不可变的 Hub 提交。验证精确的张量/配置键，并为模型、 分词器、处理器、权重索引、每个分片及来源信息生成指纹。将 验证后的转换路径（而非原始源路径）指定为训练路径。
6. 验证输入、数量、重复项、重叠、任务和身份信息。不进行字节哈希的请求 会同时启用两个快速指纹标记；元数据仍会进行哈希，而权重/媒体载荷 使用路径和大小。 从已分配的计算节点再次验证解析后的输入。 当启动主机未挂载 SLURM 存储时，允许 cosmos_workflow.py 通过 SSH 将随附的 cosmos_common.py 检查器流式传输到 登录主机。该检查器通过 stdin 运行，保留远程 realpath 值， 且不会创建远程脚本或源代码覆盖层。基于 SSH 的启动主机无需本地安装 Lustre、 sbatch 或 srun。使用 plan 动词仅运行一次这项耗时的输入检查， 并传入本地 --plan-artifact <path>，以便将解析后的请求和检查结果 封存起来，供其余启动动词使用。
7. 根据数据集的结构契约解析视频运行时，并执行 references/cosmos-reproducibility-gates.md 中的所有配置门槛。 Cosmos-RL 的 auto 会为 video_conversation 选择由源代码打包的 pynv-device-rgbp， 为 task_aware_video_reasoning 选择 system-pyav； Framework 选择 torchcodec-cuda-on-demand。所有默认配置均采用有界、 按 rank 本地按需内存，不进行磁盘预热。重复媒体验证可以使用后端原生分组分片器 和仅用于验证的缓存，但必须保留记录、显式批次、权重、提示词和预处理方式。 放宽 batch-1 一致性要求的吞吐量设置必须获得用户授权。
8. 生成后端原生 TOML、环境、拓扑、预检命令、一致性数据、运行时配置和元数据。 完整规范不得包含样本数量限制。在只读的 preflight、 审核后的 materialize 和 render-slurm 之间复用同一个封存的 --plan-artifact；不要重复传入原始输入。 在已验证的计算环境中原子化地生成文件，容器路径只能根据显式挂载推导， 绝不将源代码补丁复制到集群。诊断子集只能由用户明确选择，绝非启动先决条件。
9. 在 SLURM 上复用提供/推导出的 SQSH，或在提交 GPU 作业前仅转换一次所选镜像。 SQSH SHA 和源代码来源信息都不是运行时门槛。 需要准备 Omni 时，检查 SQSH 文件系统；除非其中包含共享 TAO 启动器、 原生 Framework 转换器和 /opt/tao/framework-converter-runtime.json， 否则拒绝使用该 SQSH。运行时制品必须报告 validation_mode=imported_converter_module，以证明隔离转换器的传递依赖图 已在镜像构建期间导入；仅有文件并不足够。 在训练分配环境中验证 Pyxis/Enroot、挂载、Python/软件包、解码器、GPU、CUDA、NCCL 和存储。
10. 直接启动用户请求的训练作业；除非用户明确要求，否则不要提交单独的冒烟测试 作业。对于 Cosmos-RL VLM 训练，必须要求打包的源代码输出支持填充的 attention_mask，并在首次反向传播后、首次优化器更新前运行视觉梯度契约。 持久化视觉编码器、视觉投影器、语言模型和语言头的总数、可训练数量、 冻结数量及梯度范数。如果可训练的视觉组件没有梯度、梯度范数不是有限值 或范数为零，立即失败。明确冻结的视觉组件应报告为不适用，而非失败。
11. 仅生成一次完整规范，并在从同一计划制品渲染作业前，于计算环境中验证其 SHA256。持续监控调度器和结构化 TAO 状态，直至达到终态，并独立于调度器状态 保留子进程退出代码。报告完成前，必须满足子进程退出代码为零、结构化状态为 SUCCESS、训练/验证全局损失为有限值、检查点已完成，且评估器已给出最终指标。
12. 使用 scripts/evaluation_workflow.py 解析评估流程。继承精确的微调制品， 仅收集仍需用户提供的输入，运行由后端负责的自动检查点前置操作，并要求 ready=true。在 Cosmos-RL 上，使用 cosmos_rl_checkpoint_action.py 验证所选 HF 导出，携带其清单重新运行解析，并通过所选平台提交生成的规范包； 绝不选择原生策略目录、将生命周期复制到应用自有启动器中，或自行编造结果/ 状态变量。 使用相同的提示词、预处理、生成、归一化和任务评分方式评估所选检查点。 使用 scripts/extract_cosmos_metrics.py 提取最终指标。

数据集契约

按结构而非项目、基准、目录或文件名解析数据集。支持的类别包括：

• video_conversation：一个 JSON 数组，包含媒体以及至少两个 ShareGPT、 LLaVA 或 OpenAI 风格的对话轮次；
• task_aware_video_reasoning：一个或多个条目封装或数组格式的标注 文件，包含媒体、任务标识以及对话/响应目标。

将 dataset_family 默认设为 auto，检查每个标注文件，并要求训练集 和验证集解析为同一类别。记录样本数、唯一媒体数、媒体复用情况、扩展名、 字节大小分布、任务/指标元数据，以及所有已声明的宽度、高度、FPS 和时长。 根据这些特征和模型层级选择处理器、缓存和资源配置。绝不根据客户数据集名称 进行分支处理。

声明了准确率的任务会参与确定性准确率计算；可识别常见的二分类和多项选择 任务类型。生成式任务报告其声明的指标，并说明将其排除在汇总准确率之外的原因。 汇总准确率按参与计算的记录数加权，这些记录均须有准确率定义。

Dense 和 PEFT 契约

Dense SFT 不包含 LoRA 配置块，并报告可训练、冻结和总参数数量。 PEFT 在不同后端间保留秩、alpha、dropout、目标模块、偏置、RS-LoRA、 保存的模块、精度和可训练参数数量；语义不匹配时，阻止成对比较。

为确保比较公平，强制使用相同的逻辑模型、训练/验证记录、媒体、提示词、 帧数、序列长度、精度、随机种子、轮数、有效全局批次大小、优化器、 学习率、调度策略、预热、权重衰减、梯度裁剪、损失掩码、验证/检查点频率、 评估的检查点以及生成/归一化设置。将差异归类为等效语法、不可避免的实现 差异或无效不匹配；无效不匹配会阻止整组比较。

指标与完成状态

必需的主要指标包括：

• 完整运行的全局归约、按 token 加权的训练损失，包含分子和有效标签分母；
• 最终验证集的全局归约、按 token 加权的损失，包含分子和有效标签分母；
• 仓库评估器输出的最终验证指标及其输出的任何支持值。不要再添加第二道评估后 关卡。

不要对控制台输出行或各 rank 的均值取平均。单步损失不等于平均训练损失。验证 心跳不等于最终验证损失。除非任务有相应定义，否则生成式精确匹配不等于准确率。

原生 Framework 回调和原生 Cosmos-RL 日志记录器负责处理早期失败、检查点、 进度、指标和终止事件。不要暂存状态桥接，也不要在容器启动时修补状态。如果子进程 退出代码非零，或终止时 TAO 状态不成功，则 SLURM 的 COMPLETED 表示失败。

SLURM 不变量

生成的作业使用 Bash、通过 Pyxis 使用 SQSH，默认不重新排队；每个节点运行一个启动器任务，日志由运行时提供，并使用训练子进程的退出代码。单节点独占分配会在 SBATCH 契约中保留请求的 CPU 数量，但会将 SLURM 实际授予的全部 CPU 传递给训练步骤，并记录请求、分配和步骤的 CPU 数量。在训练子进程启动前，同一分配会将规划器管理的打包运行时门禁作为训练作业的第一个 Pyxis 步骤运行；如果门禁失败，则会写入独立的子进程退出产物并阻止训练。生成的作业会设置 SLURM_EXPORT_ENV=ALL，平台使用方仍会通过 sbatch --export=ALL 提交。每个 Pyxis 步骤还会通过 --container-env 接收规划器管理的运行时变量名称，因此镜像内置的 ENV 值无法覆盖所选的解码器、帧传输、缓存或工作进程配置。 框架拓扑为 分片=gpus_per_node，副本=nodes。 Cosmos-RL 在节点零上运行一个控制器，并采用其策略工作进程拓扑。 多节点运行会拒绝异步分布式检查点。

每条作业元数据记录都必须通过 schemas/cosmos-job-metadata.schema.json 验证，并包含路径、指纹、运行时标识、配置、资源、状态、输出和时间信息，且不得包含凭据。来源溯源信息仅适用于 source-build；SQSH SHA 为可选项，且绝不作为运行时门禁。

影响源代码的恢复

如果运行暴露出代码或镜像缺陷，请停止受影响的路径，修改负责的代码库、添加测试并提交，然后从干净的检出状态重新构建镜像和 SQSH，最后从干净且已封存的计划重启所有受影响的训练作业。切勿编辑正在运行的容器、修补现有镜像、在源代码变更后复用旧 SQSH，或依赖临时启动脚本作为实现。

使用 references/cosmos-reproducibility-gates.md 作为源代码所有者和测试映射表。

对于基础设施重试，启动技能会对故障进行分类并创建新的 --retry-of 记录；SLURM 提供经验证的节点清单和排除项。使用新记录的 <action-root>/config/train.toml 运行 cosmos_workflow.py retry-plan；该命令会重新设置所有可写路径，并重新封存 Cosmos 请求。渲染该计划；切勿修补 SBATCH。