Recipe 包

不发平台版本，就往 catalog 里加一种训练方法。

sf plugin publish ./my-grpo-variant
sf methods                              # 你的方法已经在 catalog 里
sf new my-exp --method nemo-rl/alice.my-grpo

recipe 包声明一种后训练方法：跑哪个入口、哪些超参可调、支持哪些框架版本和镜像、 控制台该画哪些指标。它不含任何平台会执行的代码。

​

目录结构

my-grpo-variant/
├── plugin.yaml       # kind: recipe
├── recipe.yaml       # 声明本体
├── README.md
└── template/         # `sf new` 拷进用户仓库的东西
    ├── config.yaml
    └── run.py

plugin.yaml

schema: forge/plugin/v1
name: my-grpo
version: 1.0.0
kind: recipe
summary: GRPO with a length-normalised advantage

除 template/ 之外，任何地方出现可执行文件都会被拒。那个目录是交给用户、在用户容器里跑的脚手架； 根层是平台要解析的，不该出现任何让人期待平台去 import 的东西。

​

recipe.yaml

recipe.yaml

name: my-grpo
version: "0.7.0"
framework: nemo-rl
title: GRPO with length-normalised advantage
summary: >
  Group-relative advantage divided by completion length, which stops long answers
  from dominating the batch on verbose datasets.

runtime:
  default_version: "0.7.0"
  versions:
    "0.7.0":
      requires: []
      runtime_id: "nemo-rl-0.7.0"
      source:
        kind: oci
        reference: "nvcr.io/nvidia/nemo-rl:v0.7.0@sha256:75c4821c…"
        ray_version: "2.55.1"

template: template
config_section: grpo
roles: [actor, reference, rollout]

adapter_options:
  config_mode: dot-overrides
  observability: platform
  ray_cluster_profile: nemo-rl-baseline

entrypoint:
  kind: file
  value: examples/run_grpo.py
  experiment_override: run.py

params:
  num_prompts_per_step:
    type: int
    path: grpo.num_prompts_per_step
    group: Training & validation
    doc: Prompts sampled per step
    default: 32
    min: 1
  length_norm_power:
    type: float
    path: grpo.length_norm_power
    group: Advantage
    doc: Exponent on completion length in the advantage denominator
    default: 1.0
    min: 0.0
    max: 2.0

metrics:
  primary:
    - train/reward
    - validation/accuracy
    - train/kl_penalty
    - train/loss
  aliases:
    train/entropy: [train/approx_entropy]

validation:
  sample_kind: conversation
  reward_semantics: scalar

artifacts:
  version: "forge/artifacts/v1"
  checkpoints: ["checkpoints/step_*", "step_*"]
  logs: ["logs"]
  exports: ["hf_export"]
  formats:
    checkpoint: nemo-checkpoint
    log: text
    hf_export: huggingface

​

超参声明

params: 下的每一项，都是 sf validate 能在你笔记本上（而不是在集群上）拦下拼写错误的依据。

type · int | float | str | bool | enum · 必填

写别的会在加载时被拒，并点名是哪个参数。

path · dot.path

这个值落在训练框架自己配置里的哪个位置。有了它，平台才能把扁平的 --set length_norm_power=1.2 翻译成框架原生的 override。

group · string

控制台和 CLI 里的展示分组，不参与校验。

default, min, max, choices, required · mixed

校验契约。min/max 默认闭区间，除非设了 exclusive_minimum。

path_overrides · {version: path}

上游在不同框架版本之间挪了配置键时用它。把这件事声明在这里， 而不是在 adapter 代码里写版本分支。

warmup_ratio:
  type: float
  path: optim.warmup_steps_ratio
  path_overrides:
    "0.9.0": optim.lr_warmup_steps_ratio

​

指标契约

metrics.primary 是有序列表，前两个进总览图，诊断阈值读的也是同一批 key。 aliases 把规范 key 映射到某个框架版本实际发出的名字，这样上游改名不会让一张图变空。

​

双语展示文案

manifest 用英文写，翻译放在一个 i18n: 块里。控制台按读者语言取，缺翻译时回退到 manifest 原文。

title: GRPO with length-normalised advantage
summary: >
  Group-relative advantage divided by completion length.
params:
  num_prompts_per_step:
    type: int
    path: grpo.num_prompts_per_step
    group: Training & validation
    doc: Prompts sampled per step
i18n:
  zh:
    title: GRPO · 长度归一化优势
    summary: >
      把组相对优势除以生成长度，避免长回答在 verbose 数据集上主导整个 batch。
    params:
      num_prompts_per_step: {group: 训练与验证, doc: 每步题目数}

参数翻译放在 locale 底下，而不是挂在每个参数上。一个 recipe 会声明几十个参数， 每个都挂一个 i18n: 会把读者真正来找的契约（path / type / range）埋掉。 给一个没声明过的参数写翻译是错误，所以改名不会留下一条指向空处的翻译。

只有展示文案可翻译。名字、path、指标 key 是契约，任何语言下都一样。

​

命名

已发布方法的 id 永远是 <framework>/<owner>.<name>：

nemo-rl/alice.my-grpo

多出来的这一段让「和内置方法撞名」在结构上不可能发生——你没法发布一个遮蔽 nemo-rl/grpo 的东西。

​

镜像

recipe 声明作业跑哪个容器镜像。这是声明包唯一能表达的真正危险的事： 一份纯 YAML 本来可以让集群去拉任意镜像。

因此镜像必须通过部署的仓库允许列表（FORGE_ALLOWED_IMAGE_REGISTRIES）。 在向用户开放 recipe 发布之前，先把它配好。

​

确认成功

sf recipe sync                          # 拉取 catalog（提交前会自动执行）
sf methods                              # 你的方法出现了，带来源标记
sf methods nemo-rl/alice.my-grpo        # 它可调的参数
sf new probe --method nemo-rl/alice.my-grpo
sf validate probe

sf validate 不碰集群就能验你的参数声明。如果一个不合理的值在那里也通过了， 说明你的声明缺了范围限制。

​

版本

recipe.yaml 里的 version 对齐上游框架的发布号。包的内容身份是另一个东西—— 覆盖 manifest 加 template 的 bundle digest。所以改一个默认值或修一个模板会更新 digest， 而不必假装框架变了。

实验在 recipe.lock.json 里锁住 digest。你发布新版本后，已有实验照常工作， 直到它们的主人执行 sf recipe upgrade。