> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 上游版本采纳 SOP

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

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

## 标准步骤

<Steps>
  <Step title="构建执行工件">
    为新版本构建训练镜像（K8s/Docker：OCI digest 固定）或 SIF/SQSH（Slurm），发布到 runtime registry，分配 `runtime_id`。
  </Step>

  <Step title="声明版本变体">
    在 recipe YAML 的 `runtime.versions` 增加新版本项：`runtime_id`、依赖、以及**版本绑定的差异**——入口覆盖（`entrypoint`）、参数路径覆盖（`path_overrides`）、观测补丁认证版本（`observer_versions`）。
  </Step>

  <Step title="跑适配测试">
    SDK 单测覆盖版本矩阵（入口 / 参数路径 / 观测按版本断言）；`tests/` 全量回归。
  </Step>

  <Step title="灰度发布">
    新版本先不设为 `default_version`：想尝鲜的用户 `sf new --framework-version X` / `sf recipe upgrade --framework-version X` 显式选用。稳定后再切默认。
  </Step>

  <Step title="用户升级">
    catalog 发布后，存量实验锁提示漂移；用户 `sf recipe upgrade` 显式升级——没有静默切换。
  </Step>
</Steps>

## 各框架注意点

| 框架          | 常见差异点                                                   |
| ----------- | ------------------------------------------------------- |
| **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。

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