生产 9：版本管理（SGLang / 模型 / API）

谁该读这一篇？ 平台运维 / 上线负责人 —— 处理"换 SGLang 版本怎么平滑"、"模型怎么灰度切换"等问题。 前置阅读： 07-router.md、05-incident-playbook.md。 耗时： 25 分钟 学完能： 1. 区分 SGLang 版本、模型版本、API 版本； 2. 用 router + 双副本灰度切版本； 3. 处理 OpenAI API 兼容协议的版本差异； 4. 写一份发布检查表； 5. 知道权重热更新的几种路径（用于 RL / online learning）。

1. 三个独立的版本维度

三者独立但要协调。

2. SGLang 版本升级

升级前检查

• Read release notes（breaking changes / 新特性 / 废弃）。
• 跑 benchmark 对比新版 vs 旧版。
• 跑业务 eval 验证模型行为不变。
• 准备回滚预案。

灰度发布

将旧版和新版作为独立 worker pool，通过 Kubernetes Service、Gateway API 或 sgl-model-gateway 的 worker registry 分阶段切流。当前 router CLI 没有可依赖的 --worker-weights 合同；权重灰度应由流量入口完成，并为两个 pool 分别打上 版本标签以便比较指标。

配置变化

新版常加新参数。配置管理（Helm values / kustomize）要同步更新。

3. 模型版本切换

场景

• 新训练 checkpoint 发布。
• 切量化版本（BF16 → FP8）。
• 换基础模型（Llama-3.1 → Llama-3.3）。

切换方法

方案 A：滚动重启

简单粗暴。逐 Pod 改 --model-path，等加载完再起下一个。 代价：滚动期间容量减半，需 N+1 副本。

方案 B：影子副本

新模型起独立副本组，router 权重灰度切。 代价：双倍 GPU。 优势：随时回滚。

方案 C：热权重更新

模型架构不变（fine-tune），只换权重：

# SGLang Engine API（不重启）
curl -X POST localhost:30000/update_weights_from_disk \
    -H 'Content-Type: application/json' \
    -d '{"model_path": "/models/qwen-7b-v2"}'

weight_updater.py:update_weights_from_disk 实现。

4. RL / Online Learning 场景的权重同步

训练侧每 N step 给推理侧一份新权重。实际请求 schema 由 UpdateWeightsFrom*ReqInput 定义，部署前先查看 /docs 或 io_struct.py，不要把任意 tensor JSON 当作通用接口：

# 训练侧
import torch.distributed as dist
dist.send(weights, dst=inference_rank)

# 推理侧
curl -X POST localhost:30000/update_weights_from_distributed \
    -H 'Content-Type: application/json' \
    -d '{"names":["lm_head.weight"],"dtypes":["float16"],"shapes":[[32000,4096]],"group_name":"weight_update_group"}'

或者用 CUDA IPC（适合同机协同，句柄 schema 由服务端生成）：

# 训练侧把 tensor 注册为 IPC handle
handle = tensor.share_memory_().get_handle()
# 推理侧通过 IPC handle 直接读
curl -X POST localhost:30000/update_weights_from_ipc \
    -H 'Content-Type: application/json' -d '{"zmq_handles": {"GPU-...":"tcp://..."}}'

weight_updater.py:update_weights_from_ipc。

详见 srt/weight_sync/。

5. API 版本兼容

SGLang 对外有几套 API：

字段兼容

OpenAI 协议偶尔加字段（如 response_format、reasoning_effort）。 SGLang 跟进相对快，但有时滞后。 客户端用最新 SDK 时记得验证 SGLang 版本是否支持。

弃用字段

不推荐：直接删字段。 推荐：保留字段 + 加 deprecation warning（log + metric）。

6. 灰度发布检查表

Pre-flight:
[ ] Release notes 已读 + 内部 review
[ ] 新版本镜像 build + push 完成
[ ] 业务 eval 通过
[ ] Benchmark 没退化
[ ] 回滚预案准备好
[ ] 监控面板 ready

Phase 1: 5% canary (24 hr)
[ ] 流量入口将新版比例设为 5%（Kubernetes/Gateway/router 配置）
[ ] 监控 canary 副本: TTFT / TPOT / cache hit / abort
[ ] 业务方观察输出质量
[ ] Postmortem 候选: 任何异常都记

Phase 2: 50% (24 hr)
[ ] 流量入口将新版比例设为 50%
[ ] 监控总体 SLO 不退化

Phase 3: 100%
[ ] 流量入口将新版比例设为 100%
[ ] 旧版本副本下线
[ ] 镜像 retention 至少 30 天

Post-release:
[ ] 写 release report
[ ] Update internal docs

7. 回滚

任何阶段发现 SLO 退化：

1. 立刻在流量入口将比例切回旧版本。
2. 通知 oncall 监控。
3. 不立刻删 canary —— 留着诊断。
4. 写 incident report。

回滚时间目标：< 5 分钟。

8. 配置版本化

把所有部署相关配置存 git：

ops/
├── helm/
│   ├── values-prod.yaml
│   └── values-staging.yaml
├── kubectl/
│   └── deployments/
└── scripts/
    ├── upgrade.sh
    └── rollback.sh

每次变更 git tag，与镜像 tag 一一对应：

git tag deploy-2026-05-29-sglang-0.6
docker push mycompany/sglang:0.6-2026-05-29

9. 模型权重版本管理

模型 checkpoint 也要版本化：

s3://models/qwen-7b/v1.0/         # 初版
s3://models/qwen-7b/v1.1/         # fine-tune 增量
s3://models/qwen-7b/v1.2/         # bug fix

每个版本：

• 元信息（训练数据、checkpoint hash、训练 loss）。
• Eval 结果（GSM8K / MMLU / 业务 eval）。
• 切换记录（哪天切到这版，切回哪版）。

10. 兼容性矩阵

维护一张表：

不要把历史 0.4/0.5/0.6 小版本号当作能力保证。发布前应锁定 SGLang commit/tag、 镜像 digest、模型 revision、router/gateway commit，并用实际端点做兼容性测试：

python -c 'import sglang; print(sglang.__version__)'
curl -fsS http://localhost:30000/health
curl -fsS http://localhost:30000/v1/models
curl -fsS http://localhost:30000/metrics >/dev/null

每次升级前看这张表。

11. 小结

• 三个独立版本维度：SGLang / 模型 / API。
• 升级走灰度 + canary，5% → 50% → 100%。
• 模型可以热权重更新（disk / distributed / tensor / IPC）。
• 配置 git 化，与镜像 tag 一一对应。
• 维护兼容性矩阵防交叉冲突。

12. 自检

1. SGLang 版本升级前必做的 3 件事？

2. 热权重更新有 4 种路径，哪个最快？

3. 模型切换为什么推荐影子副本而非滚动重启？

4. 客户端 SDK 比 SGLang 新可能出现什么问题？

5. 回滚时为什么不立刻删 canary？

13. 下一步

• 05-incident-playbook.md — 出问题时的 runbook。
• 09-advanced-features/ — 高级功能进阶。
• 源码：srt/model_executor/model_runner.py 的 update_weights_* 方法、srt/weight_sync/。

上游源码：sglang/python/sglang/srt/model_executor/model_runner_components/weight_updater.py。