灰度发布与回滚

灰度发布与回滚用于降低大模型系统上线风险。

LLM 系统的发布对象不只是模型权重。模型版本、tokenizer、chat template、prompt、RAG 配置、工具 schema、推理参数、安全策略和路由规则，任何一个变化都可能改变线上行为。

一句话概括：

LLM 灰度发布 = 小流量验证新行为，指标通过后再逐步扩大；
LLM 回滚 = 把模型、配置、prompt、RAG 和工具一起退回可复现版本。

1. 为什么模型上线需要灰度

模型系统具有几个特点：

• 输出不是完全确定的。
• 用户输入分布很长尾。
• prompt 和模板会显著影响行为。
• RAG 和工具调用会引入外部依赖。
• 小质量变化可能造成大业务影响。
• 性能和成本变化不一定在离线评估中暴露。

离线评估通过，不代表线上一定稳定。

常见线上风险：

风险	示例
质量回退	回答更啰嗦、更保守、格式遵循变差
性能回退	TTFT 上升、ITL 抖动、p99 变差
成本上升	输出变长、prompt token 膨胀、工具调用变多
安全变化	拒答率异常、敏感内容漏出、误拦截
工具异常	参数格式变化、调用错误率上升
RAG 异常	引用减少、错误引用、召回内容被忽略
兼容性问题	tokenizer、chat template、stop token 不匹配

灰度发布的目标不是“慢慢上线”，而是在影响面可控的范围内发现问题。

2. 发布对象

LLM 发布需要明确到底发布了什么。

常见发布对象：

对象	示例
模型权重	base model、fine-tuned model、LoRA
tokenizer	vocab、special tokens、processor
chat template	对话格式、tool calling 模板
prompt	system prompt、任务模板、few-shot 示例
推理参数	temperature、top_p、max_tokens、stop
RAG 配置	index、embedding model、top k、rerank
工具 schema	tool name、参数、描述、权限
安全策略	输入拦截、输出审核、敏感词策略
路由规则	模型别名、权重、租户白名单
服务框架	vLLM / SGLang 参数、batch 配置

发布记录应该把这些对象版本化。否则“回滚模型”可能并没有回滚真实行为。

3. 版本管理

建议把线上行为定义成一个 release bundle。

release bundle:
  model_version
  tokenizer_version
  chat_template_version
  prompt_version
  generation_config_version
  rag_config_version
  tool_schema_version
  safety_policy_version
  serving_config_version

每次灰度和回滚都围绕 bundle 操作，而不是只围绕模型文件。

一个请求日志里也应该记录命中的版本：

{
  "model": "qwen3-32b",
  "release": "support-chat-2026-04-18",
  "model_version": "2026-04-18",
  "prompt_version": "support-v12",
  "rag_config_version": "kb-rag-v7",
  "tool_schema_version": "crm-tools-v4"
}

这样线上问题才能按版本聚合和对比。

4. 发布前门禁

灰度之前要先通过基本门禁。

建议至少包括：

1. 模型文件 checksum 校验。
2. tokenizer 和 chat template 匹配检查。
3. 基础功能 smoke test。
4. 离线评估集通过。
5. 安全评测通过。
6. 工具调用格式测试通过。
7. RAG 样例测试通过。
8. 性能压测达到最低要求。
9. 回滚版本可用。
10. 监控和告警已配置。

没有回滚方案，不应该进入灰度。

对于高风险业务，还应加入人工验收：

• 固定黄金样例。
• 高风险 prompt 集。
• 业务专家抽检。
• 格式和引用检查。
• 多轮对话检查。

5. Shadow Traffic

shadow traffic 是把真实线上请求复制一份给新版本，但不把新版本结果返回给用户。

用户请求
  -> 旧版本生成并返回用户
  -> 同步或异步复制给新版本
  -> 新版本结果只记录和评估

适合验证：

• 新版本是否能稳定处理真实输入。
• 延迟、错误率和 token 用量是否异常。
• 工具调用格式是否变化。
• 安全策略命中率是否变化。
• 输出长度是否明显变化。

shadow traffic 的优点是用户无感；缺点是：

• 成本会增加。
• 不能观察真实用户反馈。
• 有副作用的工具不能直接执行。
• 异步 shadow 可能和真实上下文不完全一致。

对于工具调用，要特别小心。shadow 请求不应真实执行写操作，例如下单、发消息、修改数据库。可以使用 dry-run、mock 工具或只记录模型计划调用。

6. Canary Release

canary release 是让少量真实流量命中新版本。

常见比例：

1% -> 5% -> 10% -> 25% -> 50% -> 100%

每一阶段都要观察固定窗口，例如 30 分钟、2 小时或一个业务高峰周期。窗口长度取决于业务流量和风险。

灰度流量可以按这些维度选择：

• 内部用户。
• 白名单租户。
• 低风险业务。
• 某个区域。
• 某个入口。
• 随机用户百分比。
• 特定模型别名。

不要一开始就把高价值客户、高风险场景或强副作用工具暴露给新版本。

7. A/B Test

A/B test 更偏向效果比较，而 canary 更偏向上线安全。

项	Canary	A/B Test
目标	验证新版本是否安全稳定	比较两个版本哪个效果更好
流量	通常逐步扩大	通常保持实验比例
指标	错误率、延迟、成本、安全	转化率、满意度、任务成功率
决策	通过、暂停、回滚	胜出、失败、继续实验

LLM A/B test 要注意随机性和用户一致性。

建议：

• 按用户或会话做稳定分桶。
• 同一会话不要频繁切换模型。
• 记录实验组、模型版本和 prompt 版本。
• 同时观察质量、延迟和成本。
• 对小样本结论保持谨慎。

如果只是验证新版本会不会炸，优先做 canary；如果要比较两个 prompt 或模型对业务指标的影响，再做 A/B。

8. 模型版本路由

灰度发布依赖稳定的版本路由。

路由规则可以按：

• 模型别名。
• 租户。
• 用户。
• 会话。
• 请求类型。
• 地域。
• 权重比例。
• 实验分组。

示例：

model alias: support-chat
  stable: release-2026-04-10, weight 95
  canary: release-2026-04-18, weight 5

路由层要保证：

• 同一会话尽量命中同一版本。
• 灰度比例可快速调整。
• 可以按租户快速拉黑或拉白。
• 日志记录实际命中的 release。
• 回滚不依赖重新部署代码。

模型别名和实际版本要分开。业务侧调用 support-chat，平台侧决定它路由到哪个 release。

9. Prompt 版本和模型版本

prompt 变更也要灰度。

很多线上行为变化不是模型升级导致的，而是：

• system prompt 改了。
• few-shot 示例改了。
• RAG 拼接模板改了。
• tool 描述改了。
• 输出格式约束改了。
• stop sequence 改了。

prompt 应该像代码一样版本化。

建议：

• 每个 prompt 有稳定版本号。
• prompt 发布经过评估和灰度。
• 请求日志记录 prompt version。
• prompt 回滚可以独立于模型回滚。
• 模型升级时明确是否同时升级 prompt。

模型和 prompt 有耦合关系。新模型可能需要新 template 或新 prompt 才表现正常；但这也意味着回滚时要一起考虑。

10. 指标门禁

灰度期间要有明确指标门禁。

建议至少观察：

指标	作用
error rate	服务稳定性
timeout rate	链路和推理耗时
p99 TTFT	首 token 体验
p99 ITL	流式输出顺滑度
E2E latency	完整请求耗时
input / output tokens	token 膨胀和成本
GPU memory / KV Cache	资源压力
tool error rate	工具兼容性
safety block rate	安全策略变化
user feedback	用户满意或投诉
task success rate	业务效果

门禁要分硬门禁和软门禁。

硬门禁示例：

• 错误率高于稳定版本 2 倍。
• p99 TTFT 高于目标阈值。
• OOM 或 CUDA error 出现明显增加。
• 工具写操作失败率上升。
• 安全漏拦或误拦达到高风险阈值。

软门禁示例：

• 输出平均长度增加 20%。
• 用户负反馈略有上升。
• 某些任务类型质量下降。

硬门禁触发应自动暂停或回滚；软门禁触发可以进入人工评估。

11. 自动回滚和手动回滚

回滚分两类：

类型	适合场景
自动回滚	明确指标异常，例如错误率、OOM、超时、p99 爆炸
手动回滚	质量问题、用户投诉、安全判断、业务指标变化

自动回滚依赖稳定指标和阈值。适合机器能明确判断的问题。

手动回滚适合语义质量问题，因为“回答变差”常常需要人工确认。

回滚动作要尽量轻量：

将模型别名路由从 canary release 切回 stable release

不应该依赖重新构建镜像、重新发布代码或人工修改多个配置文件。

12. 回滚范围

LLM 回滚要明确范围。

可能需要回滚：

• 模型权重。
• tokenizer。
• chat template。
• prompt。
• 推理参数。
• RAG index 或检索配置。
• rerank 模型。
• tool schema。
• 工具实现。
• 安全策略。
• 路由规则。
• serving 参数。

常见错误是只回滚模型权重，但 prompt、template 或工具 schema 仍是新版本，导致行为没有真正恢复。

建议每次发布都有完整回滚目标：

current release: support-chat-2026-04-18
rollback target: support-chat-2026-04-10
rollback scope: release bundle

13. 灰度期间的数据采集

灰度期间要记录能支持对比的数据。

建议采集：

• release id。
• model version。
• prompt version。
• request id / trace id。
• input / output tokens。
• TTFT、ITL、E2E。
• finish reason。
• error code。
• RAG chunk id 和 score。
• tool call 轨迹。
• safety 命中结果。
• 用户反馈。
• 人工标注结果。

对比时不要只看整体平均值，要按场景拆分：

• 短问答。
• 长文档。
• RAG。
• 工具调用。
• 多轮对话。
• 高风险任务。
• 不同租户或业务线。

新版本可能整体指标正常，但在某个长尾场景明显退化。

14. 线上问题复现

灰度发现问题后，要能复现。

复现需要：

• 原始输入或脱敏后的可重放输入。
• release bundle。
• 模型和 tokenizer 版本。
• chat template。
• prompt 变量。
• RAG index version 和 chunk id。
• tool schema 和工具返回。
• 推理参数。
• seed，若支持。
• 请求时间和上下文。

如果问题涉及外部工具，要记录工具响应或构造 mock。否则工具数据变化后，模型行为可能无法重现。

对于随机采样模型，即使参数一致，输出也可能不完全一致。复现目标通常不是逐字一致，而是确认问题机制和风险范围。

15. 发布策略

不同变更适合不同策略。

变更类型	建议策略
prompt 小改	离线评估 + 小流量 canary
模型小版本升级	shadow + canary + 指标门禁
大模型切换	shadow + 白名单 + 分阶段 canary + 人工质检
RAG index 更新	离线召回评估 + shadow + 部分租户灰度
tool schema 变更	契约测试 + dry-run + 白名单灰度
推理框架参数变更	压测 + 单 worker 灰度 + 资源指标门禁
安全策略更新	离线安全集 + shadow + 误拦/漏拦分析

风险越高，越要先 shadow，再小流量，再扩大。

16. 常见问题

16.1 灰度指标正常，放量后出问题

可能原因：

• 灰度流量样本太少。
• 灰度用户不代表真实用户。
• 没覆盖高峰期。
• 长尾场景没进入灰度。
• 放量后资源竞争变化，p99 变差。

处理方式：

• 延长灰度窗口。
• 覆盖真实高峰期。
• 按任务类型分层灰度。
• 加入容量和资源门禁。

16.2 回滚后问题仍然存在

可能原因：

• 只回滚模型，没回滚 prompt 或 RAG 配置。
• 路由缓存未刷新。
• 客户端或业务服务缓存了旧配置。
• 工具或外部数据已经变化。
• 日志里记录的是模型别名，不是真实 release。

处理方式：

• 使用 release bundle 回滚。
• 验证请求实际命中的版本。
• 检查缓存和配置下发链路。
• 对工具和 RAG 做版本化。

16.3 新版本质量更好但成本明显上升

可能原因：

• 输出更长。
• 推理速度更慢。
• 工具调用更多。
• prompt 或 tool schema 更长。
• RAG top k 增加。

处理方式：

• 对比 input / output token。
• 对比工具调用次数。
• 评估质量收益是否值得成本。
• 通过输出长度、prompt 压缩或路由分层降本。

16.4 A/B 结果不稳定

可能原因：

• 样本量不足。
• 用户分桶不稳定。
• 同一会话跨版本。
• 模型随机性太高。
• 指标受外部业务变化影响。

处理方式：

• 按用户或会话稳定分桶。
• 延长实验周期。
• 记录实验组和 release。
• 降低评估噪声，必要时加入人工标注。

17. 实践检查清单

上线前确认：

1. 发布对象被打包成 release bundle。
2. 模型、tokenizer、chat template、prompt、RAG、tool schema 都有版本。
3. 请求日志记录实际命中的 release。
4. 新版本通过离线评估、性能压测和安全测试。
5. shadow traffic 不会执行有副作用的真实工具。
6. canary 流量有明确比例、窗口和扩大规则。
7. 指标门禁覆盖错误率、TTFT、ITL、p99、token、成本和安全。
8. 自动回滚阈值明确，手动回滚责任人明确。
9. 回滚目标版本已部署并可用。
10. 回滚动作可以通过路由完成，不依赖重新构建。
11. 灰度期间能按场景、租户和版本对比指标。
12. 线上问题有足够日志支持复现。

18. 和其他概念的关系

• 和 模型部署流程：灰度和回滚是模型上线流程的最后防线。
• 和 推理服务架构：版本路由、模型别名和多副本决定灰度能力。
• 和 可观测性：没有版本日志、延迟、错误和质量指标，就无法做可靠门禁。
• 和 容量与成本规划：灰度期间新旧版本并行，需要额外容量。
• 和 推理参数：推理参数变化会改变输出、成本和可复现性，也要纳入发布。
• 和 RAG 工程化：RAG index、chunk、rerank 和拼接模板都需要灰度和回滚。

19. 总结

LLM 灰度发布的核心是控制影响面，LLM 回滚的核心是恢复完整行为。

不要只把“模型权重”当成发布对象。真正影响线上结果的是一组版本：

模型 + tokenizer + chat template + prompt + RAG + 工具 + 推理参数 + 安全策略 + 路由

可靠的上线流程应该做到：

• 发布前有评估和压测。
• 发布中有 shadow、canary 和指标门禁。
• 发布后有日志、反馈和质量对比。
• 出问题时能快速按 release bundle 回滚。

这样模型系统的上线才不是一次性冒险，而是可观察、可控制、可复现的工程流程。