上游版本采纳 SOP

NeMo-RL / verl / TRL 出新版本时，平台怎么跟进

平台对上游框架采用精确锁定策略：每个已发布版本 = recipe 版本矩阵里的一个变体 + runtime registry 里的一个执行工件。跟进新版本是声明式流程，多数情况不改平台代码。

​

标准步骤

1. 构建执行工件

   为新版本构建训练镜像（K8s/Docker：OCI digest 固定）或 SIF/SQSH（Slurm），发布到 runtime registry，分配 runtime_id。

2. 声明版本变体

   在 recipe YAML 的 runtime.versions 增加新版本项：runtime_id、依赖、以及版本绑定的差异——入口覆盖（entrypoint）、参数路径覆盖（path_overrides）、观测补丁认证版本（observer_versions）。

3. 跑适配测试

   SDK 单测覆盖版本矩阵（入口 / 参数路径 / 观测按版本断言）；tests/ 全量回归。

4. 灰度发布

   新版本先不设为 default_version：想尝鲜的用户 sf new --framework-version X / sf recipe upgrade --framework-version X 显式选用。稳定后再切默认。

5. 用户升级

   catalog 发布后，存量实验锁提示漂移；用户 sf recipe upgrade 显式升级——没有静默切换。

​

各框架注意点

框架	常见差异点
NeMo-RL	官方 YAML 基底更新（同步 configs/base/）、Megatron/DTensor 配置键迁移
verl	训练入口整合（如 0.9 的 main_ppo 统一）、Ray 版本要求
TRL	Trainer API 签名变化、Accelerate 配置默认值

​

什么不要做

• ❌ 在 adapter 代码里写 if version >= X 分支——版本差异属于 recipe 声明；
• ❌ 用 latest / 分支名当版本——只接受精确 semver 或完整 commit；
• ❌ 复用旧 runtime_id 指向新镜像——工件不可变，新镜像新 id。

这套机制的完整评估（为什么锁定不是过度耦合）见仓库 docs/ops/upstream-version-adoption.md。