生产 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 验证模型行为不变。
• 准备回滚预案。

灰度发布

# 用 router 权重灰度
spec:
  args:
    - --worker-urls
    - http://sglang-v0_5:30001
    - http://sglang-v0_6_canary:30001
    - --worker-weights
    - "0.95,0.05"     # 5% canary

观察 canary 的 SLO 指标 24 小时，没问题再 10% → 50% → 100%。

配置变化

新版常加新参数。配置管理（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 \
    -d '{"model_path": "/models/qwen-7b-v2"}'

model_runner.py:update_weights_from_disk 实现。

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

训练侧每 N step 给推理侧一份新权重：

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

# 推理侧
curl -X POST localhost:30000/update_weights_from_distributed \
    -d '{"name": "lm_head.weight", "dtype": "float16", "shape": [...]}'

或者用 CUDA IPC（最快）：

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

model_runner.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)
[ ] Router weight 5%
[ ] 监控 canary 副本: TTFT / TPOT / cache hit / abort
[ ] 业务方观察输出质量
[ ] Postmortem 候选: 任何异常都记

Phase 2: 50% (24 hr)
[ ] Router weight 50%
[ ] 监控总体 SLO 不退化

Phase 3: 100%
[ ] Router weight 100%
[ ] 旧版本副本下线
[ ] 镜像 retention 至少 30 天

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

7. 回滚

任何阶段发现 SLO 退化：

1. 立刻 router weight 切回旧版本。
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. 兼容性矩阵

维护一张表：

每次升级前看这张表。

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.py:1598+。