nemo-automodel-recipe-development

NeMo AutoModel 配方开发

说明

对于配方相关问题，请给出最精简且完整的行动路径：

1. 指明相关的配方文件或 YAML 部分。
2. 列出涉及的构建器函数或配置键。
3. 如果问题询问如何配置，请提供最简 YAML 或命令示例。
4. 最后给出本地验证命令或简短的兼容 CPU 测试。

对于概念性配方问题，请仅依据本技能作答，不要检查代码库或加载其他 AutoModel 技能，除非用户要求你编辑文件。回答应聚焦于配方 YAML、构建器、CLI 路由、测试和本地验证。

常见问题可使用以下精简回答模式：

• 新建微调配方变体：从 nemo_automodel/recipes/ 下最接近的文件开始，更新模型、数据集或数据加载器、优化器、损失函数、LR 调度器、步数调度器和检查点构建器；只有在添加命令或领域别名时才注册 CLI 路由；在 examples/ 下添加示例 YAML；然后添加一个兼容 CPU 的小型单元测试，并运行 automodel finetune llm -c <config.yaml>。
• _target_ 字段：将 _target_ 说明为完全限定的 Python 可调用对象，解释同级键会作为关键字参数传入，展示优化器和数据集示例，并提及嵌套 CLI 覆盖，例如 --optimizer.lr。
• 验证和检查点：指出 step_scheduler.val_check_interval、step_scheduler.checkpoint_interval、validation_dataset、restore_from.path 和合并后的 safetensors；包含本技能中的最简 YAML 片段。

对于验证和检查点，务必指出：

• step_scheduler.val_check_interval 用于设置验证频率。
• step_scheduler.checkpoint_interval 用于设置保存频率。
• validation_dataset 是验证数据加载器的数据源。
• restore_from.path 用于恢复训练。
• 默认检查点格式为合并后的 safetensors，以兼容 HF 生态系统。

路由边界

本技能适用于配方构建和执行流程相关问题：YAML 结构、_target_ 可调用对象、构建器函数、验证数据集、检查点配置、CLI 路由注册以及配方专属测试。

不要将本技能用于独立的分布式策略选择、集群启动器配置或模型架构接入，除非用户询问这些选项在 AutoModel 配方 YAML 中的写法。

配方架构

执行流程

CLI (automodel finetune llm -c config.yaml)
  -> app.py parses command + domain + config
    -> recipe script (e.g. train_ft.py) main(config_path)
      -> Recipe class .setup() builds all components
        -> .run_train_validation_loop() executes training

配方类

配方继承自 BaseRecipe，并实现两个方法：

• setup() —— 通过构建器函数构建模型、优化器、数据加载器、损失函数、LR 调度器、步数调度器和检查点配置。
• run_train_validation_loop() —— 执行训练和验证循环。

构建器模式

所有组件均通过专用构建器函数构建：

• build_model() —— 根据配置实例化模型
• build_optimizer() —— 创建优化器（AdamW 等）
• build_dataloader() —— 设置训练和验证数据加载器
• build_loss_fn() —— 创建损失函数
• build_lr_scheduler() —— 创建学习率调度器
• build_step_scheduler() —— 创建用于控制训练进度的步数调度器
• build_checkpoint_config() —— 配置检查点

基础设施应用顺序

构建后，按以下严格顺序应用各组件：

1. PEFT（LoRA 等）
2. FP8 量化
3. QAT（量化感知训练）
4. 加载检查点 / 恢复
5. 冻结参数
6. 分片（FSDP2、Megatron-FSDP、DDP）
7. 设备放置
8. torch.compile
9. 上下文并行挂钩

YAML 配置结构

完整的配方配置遵循以下结构：

step_scheduler:
  max_steps: 1000
  num_epochs: 1
  grad_accumulation_steps: 4
  val_check_interval: 100
  checkpoint_interval: 500
  log_interval: 10

dist_env:
  master_addr: localhost
  master_port: 29500

rng:
  seed: 42

model:
  _target_: nemo_automodel.models.llm.NemotronHForCausalLM
  name_or_path: meta-llama/Llama-3.2-1B
  # additional model kwargs passed to the constructor

compile:
  enabled: false
  backend: inductor

clip_grad_norm:
  max_norm: 1.0

distributed:
  strategy: fsdp2       # fsdp2 | megatron_fsdp | ddp
  dp_size: auto
  tp_size: 1
  cp_size: 1

loss_fn:
  _target_: torch.nn.CrossEntropyLoss

dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  tokenizer_name_or_path: meta-llama/Llama-3.2-1B
  max_seq_length: 2048

validation_dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  split: validation

packed_sequence:
  enabled: false

dataloader:
  batch_size: 4
  num_workers: 4
  pin_memory: true

optimizer:
  _target_: torch.optim.AdamW
  lr: 2.0e-5
  weight_decay: 0.01

lr_scheduler:
  _target_: nemo_automodel.schedulers.CosineAnnealingWarmup
  warmup_steps: 50
  min_lr: 1.0e-6

_target_ 模式

_target_ 键用于指定完全限定的 Python 可调用对象。该部分中的所有其他键都会作为关键字参数传入：

optimizer:
  _target_: torch.optim.AdamW   # callable
  lr: 2.0e-5                    # kwarg
  weight_decay: 0.01            # kwarg

这等同于：torch.optim.AdamW(lr=2e-5, weight_decay=0.01)。

CLI 覆盖

可以从命令行覆盖任何配置值：

automodel finetune llm -c config.yaml \
  --optimizer.lr 1e-4 \
  --step_scheduler.max_steps 500 \
  --distributed.tp_size 2

示例

验证与检查点：

step_scheduler:
  val_check_interval: 100
  checkpoint_interval: 500

validation_dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  split: validation

restore_from:
  path: /checkpoints/step-500

领域专属说明

LLM

• nemo_automodel/recipes/llm/train_ft.py 同时处理微调和预训练。两者的区别由配置决定（数据集、学习率等）。
• nemo_automodel/recipes/llm/kd.py 使用教师模型和学生模型实现知识蒸馏。
• nemo_automodel/recipes/llm/benchmark.py 运行吞吐量和延迟基准测试。

VLM

• 使用 NeMoAutoModelForImageTextToText，而非因果语言模型类。
• 配置包含 processor 部分，而非单独的分词器。
• 配方位于 nemo_automodel/recipes/vlm/finetune.py。

Diffusion

• 使用 NeMoAutoDiffusionPipeline。
• 配置中需要 parallel_scheme 字典来定义并行策略。
• 仅支持 DDP 和 FSDP2 策略（不支持 Megatron-FSDP）。
• 配方位于 nemo_automodel/recipes/diffusion/train.py。

Retrieval

• 两种编码器模式：
  • 双编码器（nemo_automodel/recipes/retrieval/train_bi_encoder.py）：分别使用查询编码器和文档编码器，并采用对比损失。
  • 交叉编码器（nemo_automodel/recipes/retrieval/train_cross_encoder.py）：联合编码，并使用分类头。
• 难负例挖掘：nemo_automodel/recipes/retrieval/mine_hard_negatives.py。

训练循环详情

每个周期的训练循环遵循以下结构：

for epoch in range(num_epochs):
    for batch_idx in range(batches_per_epoch):
        # --- gradient accumulation inner loop ---
        for micro_batch in micro_batches:
            if pipeline_parallel:
                schedule.step(micro_batch)    # PP schedule
            else:
                loss = model(micro_batch)     # direct forward
                loss.backward()

        # --- optimizer step ---
        scale_grads_and_clip_grad_norm(model, max_norm)
        optimizer.step()
        lr_scheduler.step()
        optimizer.zero_grad()

        # --- logging ---
        MetricsSample(step, epoch, loss, grad_norm, lr, mem, tps, mfu)

        # --- validation (at configured intervals) ---
        if step % val_check_interval == 0:
            run_validation()

        # --- checkpoint (at configured intervals) ---
        if step % checkpoint_interval == 0:
            save_checkpoint()

StepScheduler

控制所有训练进度：总周期数、总步数、梯度累积步数、验证间隔、检查点间隔和日志记录间隔。

梯度裁剪

在反向传播之后、优化器步进之前，通过 scale_grads_and_clip_grad_norm() 执行。由配置中的 clip_grad_norm.max_norm 控制。

上下文并行

当 cp_size > 1 时，使用 make_cp_batch_and_ctx() 在上下文并行组间拆分批次。此操作必须在前向传播之前完成。

MetricsSample

每个训练步骤都会生成一个包含以下字段的 MetricsSample：

• step -- 全局步数
• epoch -- 当前周期
• loss -- 训练损失
• grad_norm -- 裁剪后的梯度范数
• lr -- 当前学习率
• mem -- GPU 内存使用量
• tps -- 每秒处理的令牌数
• mfu -- 模型 FLOPS 利用率

验证与检查点

验证

• 按照 step_scheduler.val_check_interval 定义的间隔运行。
• 使用根据 validation_dataset 配置构建的验证数据加载器。
• 模型设为评估模式；梯度已禁用。

检查点

• 默认格式：整合后的 safetensors，便于在 HF 生态系统中部署（始终优先使用此格式，而非 DCP）。
• 检查点间隔由 step_scheduler.checkpoint_interval 控制。
• 通过 restore_from 配置键指定指向检查点目录的路径，以恢复训练。

restore_from:
  path: /checkpoints/step-500

常见问题

问题	原因	解决方法
配置错误未被提示	_target_ 值拼写错误	类路径必须是有效且可导入的 Python 可调用对象。请仔细检查模块路径和类名。
训练在第一步崩溃	global_batch_size 不能被 local_batch_size * dp_size * grad_accumulation_steps 整除	确保各维度的批次大小计算一致。
新配方无法通过 CLI 访问	未注册 CLI 命令别名	在 CLI 应用中注册新路由，以便 automodel <command> <domain> 能正确解析。
前向传播时形状不匹配	数据集整理函数的输出与模型输入签名不匹配	确认整理函数返回的张量具有模型所需的键和形状。
验证期间发生 OOM	验证批次过大，或未禁用梯度	使用 torch.no_grad() 包裹验证过程，并考虑减小验证批次。
检查点恢复失败	检查点与配置中的模型架构不匹配	确保模型配置与检查点完全一致（层数、隐藏维度、词表大小）。