nemotron-customize

nemotron-customize

重要：在回答任何 nemotron-customize、Nemotron 定制、Curator 筛选、翻译、SFT、PEFT、RL、转换、优化、检查点或现有／托管端点评估，或多步流水线请求前，请先阅读此文件。无论用户只指定一个步骤，还是要求将多个步骤组合成流水线，都适用本要求。

即使不涉及训练，评估请求也适用：“evaluate”“benchmark”“smoke test”或“score”现有／托管端点、API／模型 ID 或已部署模型时，均应转到 eval/model_eval。这些情况也要阅读此技能说明。

用途

将模型定制请求转化为符合仓库规范的 Nemotron 步骤流水线。规划有向无环图（DAG），验证产物的连接方式，并且只创建运行现有步骤所需的 YAML／配置文件。

仅将此技能用于检查、配置、验证、运行或提交现有 Nemotron 步骤或多步骤训练／定制流水线。对于前端、仪表板、可视化、通用 ML 建议、账单／访问或无关的编码任务，请简短说明范围后停止，不要在本轮检查步骤目录或编辑文件。

前提条件

• 已检出 Nemotron 仓库，且其中存在 src/nemotron/steps/；请从仓库根目录运行。
• 已安装 uv，可用于调用 uv run nemotron steps ...。
• 对于远程执行：需要提供环境配置文件 TOML（NEMOTRON_ENV_FILE 或 env*.toml），其中的配置节须与所选步骤匹配。
• 对于托管服务（翻译、托管评估）：需要在环境中导出该步骤所需的身份验证环境变量（例如 NVIDIA_API_KEY），切勿将其直接写入代码或提交。
• 在提供可运行命令前，用户必须提供具体值（模型／检查点、数据路径、输出目录、硬件／GPU 数量）。

限制

• 不会臆造目录中不存在的步骤。如果没有现有步骤、运行器、配方、CLI 或配置可以满足请求，则会指出缺口（探索模式），而不是虚构步骤。
• 只为现有步骤生成 YAML／配置；除非已批准缺口并进入探索模式，否则不在范围内生成新的 Python／shell 代码。
• 不适用于仅涉及部署／服务、前端、仪表板、通用 ML 建议或非 Nemotron 任务。
• 不会猜测具体值（路径、模型 ID、GPU 数量、配置文件）；缺少这些值时会询问用户或返回 Blocked。

核心规则

优先使用随附的参考资料。references/ 文件夹是确定路由、产物、模式、硬件启发式规则和命令格式的首要依据。只有在需要核实当前准确的配置字段、清单、运行器导入项，或随附参考资料中缺少的细节时，才使用 src/nemotron/steps/... 作为实时核实／备用来源。

如果来源之间存在冲突：

1. 对于准确执行，以已核实的仓库实时文件为准。
2. 对于初始路由和规划，以随附参考资料为准。
3. 仅在特殊代码生成或库 API 细节场景下使用上游文档／上下文包。

开始之前

• 打开仓库源文件之前，先阅读此 SKILL.md 工作流及相关的随附参考文档。
• 在广泛探索仓库之前，先根据 references/CATALOG.md 和 references/ARTIFACTS.md 确定路线。确定路线后，只验证回答所需的选定实时步骤、配置和环境文件。
• 不要输出包含虚构路径、占位模型 ID、猜测的任务 ID、猜测的批处理配置，或将默认身份验证变量名当作事实的命令。对于缺失的具体值，请向用户询问，或返回 Blocked 交接说明。
• 定稿配置或执行命令之前，将 references/COMMANDS.md 作为权威检查清单。
• 对于流水线请求，先规划再编辑。在 DAG、工件边、必需输入和验证检查已说明并获批之前，不要创建或修改文件。
• 对于一次性命令请求，如果必需输入已知，优先在一次回复中提供完整的参数化命令，而不是先进行探索性描述。如果用户已提供所需值并且只要求命令，则先给出命令，并尽量少作说明。
• 输出规范（让回复保持简洁）：每个步骤只输出一个命令代码块，只包含该步骤实际定义的标志，不添加任何猜测或杜撰的标志。说明控制在几行内——仅包含命令及必要的安全或配置说明，而不是教程。不要复述用户未要求的参考内容。
• 不要为查找一次性命令而启动子 Agent。直接使用随附的命令参考；如有需要，只验证选定步骤。

安全

Bash 命令仅限于对仓库安全的操作，例如 uv run nemotron steps ...、定向测试、git status/diff 和配置验证。绝不要运行环境转储（env、printenv、广泛的 export）或会泄露机密值的命令。对于远程提交、破坏性更改或高成本启动，执行前先确认。

检查环境或配置文件时，避免输出可能包含机密信息的整个文件。使用定向读取，只报告节名称和环境变量名称；对字段名包含 token、key、secret、password、credential 或 auth 的字段，将其值脱敏。

参考文档索引

问题	优先阅读	实时备用 / 验证
哪个步骤或类别合适？	references/CATALOG.md	uv run nemotron steps list/show，然后查看选定的 step.toml
工件是否串联？	references/ARTIFACTS.md	src/nemotron/steps/types.toml
应采用哪种运行形式？	references/COMMANDS.md	已纳入版本控制的配置 YAML 以及当前配置文件 TOML
远程配置生成或选择	references/COMMANDS.md	当前的 NEMOTRON_ENV_FILE、env.toml 或 env.*.toml
应推荐哪种硬件 / 后端？	references/HARDWARE.md	选定步骤中的 [[models]] 和 [[strategies]]
哪些跨步骤防护规则适用？	references/PATTERNS.md	src/nemotron/steps/patterns/<id>.md
如何运行完整工作流？	references/WORKFLOW.md	选定步骤的配置、step.py 和运行器
生成的代码应使用哪个上游库 API？	references/context/index.toml -> 匹配的包	选定的 step.py、_runners/、上游文档
新项目脚手架，仅当现有仓库代码无法满足请求时	references/act/PROJECT.md	现有仓库的项目 / 配方结构
各阶段的代码规则，仅当现有仓库代码无法满足请求时	references/act/STAGE.md	选定的 step.py 和共享运行器

对于常规决策，不要从阅读类别 README 或 step.toml 开始。 先从随附参考文档中选定候选项，再核实确切的实时细节，然后编写配置或最终命令。

路由

将 references/CATALOG.md 作为步骤选择和特定路由快速路径的权威依据。只有在目录缩小路由范围后，才使用 ARTIFACTS.md、PATTERNS.md 和 HARDWARE.md 来解决产物、跨步骤或硬件约束。

每个步骤都是独立的，串联步骤由你负责。根据用户的最终目标，通过产物匹配来组合任意工作流：只有当下一步所需的产物类型尚未由上游步骤生成时，才串联该步骤。不要依赖固定的命名步骤组合。

说明

根据请求选择相应流程：推荐/计划、单步命令或多步工作流。无论哪种情况，都要先从随附的参考资料着手，收集所需输入，并在将内容作为可运行内容呈现之前，验证所选的实际步骤。

推荐回复

规划类回答采用以下结构：

Decision、Why、Required inputs、Config/command、Avoid 和 Next step。 如果用户的约束使某个技术栈不适用，应明确指出应避免使用该技术栈。

每当回答中包含会访问托管服务或进行远程执行的命令时，还必须说明：

• 认证环境变量的名称，并说明其值必须导出到环境中，绝不能内联填写或提交（绝不打印该值）。
• 对于 --batch/--run，必须满足环境 TOML 配置文件的前提；如果不存在配置文件，应将命令标记为 Blocked，或给出本地 --dry-run 命令形式。

规范命令形式见 references/COMMANDS.md。

单步命令流程

1. 确认仓库根目录中存在 pyproject.toml 和 src/nemotron/steps/。
2. 阅读 references/CATALOG.md 和 references/COMMANDS.md 中所选步骤对应的部分。
3. 如果 CLI 可用，使用 uv run nemotron steps show <step_id> 验证所选实际步骤；否则检查所选的 step.toml。
4. 输出命令前，阅读所请求的仓库内配置或用户覆盖配置。
5. 对于远程执行，阅读 NEMOTRON_ENV_FILE 或仓库根目录下的 env*.toml，并选择一个配置文件，其中的配置段与该步骤匹配。
6. 在一条回复中输出完整命令，并注明来源级别： Verified、Repo-grounded、Reference-grounded 或 Blocked。

规范命令形式见 references/COMMANDS.md。

工作流流程

对于包含两个或更多阶段的工作流，使用 Orient -> Plan -> Act -> Verify。 阅读 references/WORKFLOW.md，了解各阶段的检查清单。

• 根据随附参考资料和用户约束进行定向。
• 规划 DAG，列出产物类型、配置、模式和验证检查。
• 编写配置或代码前，等待批准。
• 如果现有步骤能够满足请求，就仅修改 YAML/配置文件。
• 报告完成前，验证每个生成的 YAML、产物流向、命令和 README 命令。

目录模式

当请求对应现有步骤时使用。快速路径：

references/CATALOG.md -> references/ARTIFACTS.md -> references/COMMANDS.md -> 验证所选的实际清单/配置/配置文件 -> 在所选步骤的 config/ 目录下新增命名配置文件。

自定义范围

• 始终通过 src/nemotron/steps/ 下的步骤目录进行自定义。绝不要转而使用其他配方 CLI，例如 src/nemotron/cli/commands/super3/ 或 .../nano3/，即使是 Super3/Nano3 任务也不例外。如果请求似乎需要这些 CLI，应将其映射回对应的目录步骤（例如 sft/megatron_bridge）。
• 在所选步骤的 src/nemotron/steps/<cat>/<step>/config/ 目录中创建新的配置文件进行自定义，例如 src/nemotron/steps/sft/megatron_bridge/config/my_super3.yaml。
• 绝不要修改仓库内的 default.yaml、tiny.yaml、其他随附配置、step.toml、step.py 或共享运行器。预期且唯一允许的自定义写入操作是在这些文件旁边新增配置文件。
• 新配置应以仓库内 default.yaml 的架构为基础（阅读并复制所需字段），然后仅覆盖请求所需的内容。

Explorer 模式

仅在确认现有步骤、运行器、配方、CLI 或 YAML 配置界面都无法满足请求后使用。完整流程见 references/WORKFLOW.md。

配置对齐

在执行命令或写入配置前，说明以下约束：

• SFT 打包的 pack_size、Megatron-Bridge 的 seq_length、打包序列大小、 分词器和聊天模板必须匹配。
• 已准备好的 packed_parquet 和 binidx 已与分词器绑定；更改分词器、 聊天模板、序列长度、数据拆分或混合配置后，必须重新构建。
• Megatron-Bridge 的全局批次大小必须能被数据并行度整除；开始分布式验证时， 将微批次大小设为 1。
• TP/PP/CP/EP 选项必须符合 GPU 数量、内存、拓扑和模型维度要求。
• LoRA 合并必须使用适配器训练时所用的精确基础检查点/模型和分词器。
• 转换/评估 Megatron 检查点时，应指定具体的 iter_* 检查点，而不是父级运行目录。
• 托管评估和翻译配置仅保存身份验证环境变量名称，不保存变量值。

操作注意事项

• 冒烟测试配置（tiny.yaml、tiny_chat.yaml）用于连通性测试，不能作为质量证据。
• ${art:...} 引用应放在由配方支持的配置中；独立 YAML 使用普通路径。
• 预训练的 bin/idx 数据和 blend.json 必须来自同一次运行/同一发行版。
• 将自定义配置写入步骤的 src/nemotron/steps/<cat>/<step>/config/ 目录下的新文件；切勿修改已检入的 default.yaml 或其他随附配置。
• 对于 LoRA，应保留后续合并/评估所需的精确基础检查点以及分词器/模板元数据。
• 对于翻译和托管评估，仅提及身份验证环境变量名称，绝不提及变量值。

边界

应当：

• 始终通过 src/nemotron/steps/ 下的步骤目录操作；切勿使用替代配方 CLI（src/nemotron/cli/commands/super3|nano3/...）。
• 优先复用仓库 CLI、运行器、配方、步骤和已检入配置。
• 通过在步骤的 config/ 目录下新增配置来自定义；以 default.yaml 为基础，而非盲目复制。
• 验证工件依赖关系，并指出改变计划的模式。
• 缺少硬件/数据/后端/输出路径信息时，应询问用户。
• 说明 AutoModel 与 Megatron-Bridge、完整 SFT 与 LoRA 等方案之间的权衡。

不得：

• 在目录中的步骤足以满足需求时另行编造步骤。
• 对包含两个或更多阶段的流水线跳过计划。
• YAML 足够时，不生成 Python 或 shell。
• 除非用户要求，否则不要添加监控/W&B。
• 不要假设 GPU 数量、环境配置、端点类型、任务 ID 或身份验证值。
• 除非请求明确需要部署脚手架，否则不要生成 Slurm/Airflow/Kubeflow 包装器。
• 不要编辑已检入的步骤文件（default.yaml/tiny.yaml、其他随附配置、step.toml、step.py、运行器）；只能在它们旁边新增配置。
• 不要在 SKILL.md 中重述所有逐步骤规则；使用随附参考资料和源代码回退方案。

示例

单步路由（在小型设备上使用 LoRA）。 用户：“在 2 张 GPU 上对一个 HF 模型进行 LoRA 微调。” 根据 CATALOG.md 路由至 peft/automodel（HF 基础模型 + 少量 GPU）；不要推荐 Megatron-Bridge。收集基础模型、JSONL 数据路径、输出目录、LoRA rank/alpha，然后生成一条 uv run nemotron steps run peft/automodel -c <config> --dry-run ... 命令。

多步流水线（Super3 SFT）。 用户：“为 Super3 准备数据 + 进行 SFT。” 这是两个阶段，因此先制定计划：对 Super3 进行 SFT -> Megatron-Bridge，该步骤使用 packed_parquet，因此上游必须包含 data_prep/sft_packing。展示 DAG（sft_packing -> sft/megatron_bridge），协调 pack_size/seq_length/tokenizer，等待批准，然后在 src/nemotron/steps/<step>/config/<name>.yaml 下添加新配置。Super3 需要远程配置；说明 env TOML 前提条件，或标记为 Blocked。

托管端点评估（不进行训练）。 用户：“对我托管的模型端点进行基准测试。” 路由至 eval/model_eval，并使用 -c tiny_chat。收集端点 URL、模型 ID、任务 ID，以及认证环境变量名称（导出其值，绝不可将值内联）。参见 references/COMMANDS.md 中的 Evaluation Examples。

故障排除

情况	操作
工件类型无法衔接	重新检查 references/ARTIFACTS.md；在编写配置前插入转换器或更改 DAG。
不清楚远程配置或 --batch	阅读当前启用的 env TOML；不要猜测配置名称。
不清楚配置键	编辑前，核实选定的已检入配置、step.py 和共享运行器。
策略指向缺失的上下文包	跳过该包，使用目录/模式文本，并在计划中标注 WARNING: <topic> docs unavailable。
硬件配置似乎过低	使用 references/HARDWARE.md；依次建议较小的模型、AutoModel，然后再考虑完整的 Megatron-Bridge。
两次 Act 尝试均失败	停止，说明尝试过什么以及失败原因，并询问如何继续。
没有匹配的现有仓库路径	检查 references/context/index.toml 和选定的源回退方案；只有在说明缺口后才使用 Explorer 模式。