发布单元与版本谱系
本节目标
把“换了模型”扩展为对整个LLM复合应用的版本管理，并学会为每次回答保留可重建的谱系。
为什么不能只记模型名
同一个模型在不同Prompt、知识库、检索top-k、工具schema或安全策略下会表现得像不同系统。反过来，供应商模型名未变也不足以证明行为永远不变。因此运维对象应是一个 release manifest（发布清单），而不是一个孤立字符串。
最小发布单元
| 组件 | 应固定的证据 | 常见隐形变化 |
|---|---|---|
| 应用代码 | Git commit、构建制品摘要 | 未提交本地改动 |
| API 与 SDK | API 契约版本、SDK 锁文件摘要 | SDK 自动升级、字段或错误语义变化 |
| Prompt | 模板ID、内容摘要、变量契约 | 在管理页直接编辑 |
| 上下文 | 组装策略、系统信息顺序、截断规则 | token预算或会话摘要变化 |
| 检索 | 索引/快照ID、Embedding、Chunking、过滤、top-k、Reranker | 文档同路径被覆盖 |
| 模型 | 供应商、模型固定版本或可验证识别符、推理参数 | latest或浮动别名 |
| 工具 | 名称、schema摘要、实现版本、权限策略 | 工具名不变但副作用改了 |
| 护栏 | 输入/输出策略、分类器版本、降级策略 | 策略热更新未进入发布记录 |
| 评测 | 回归集、评分器、人工标注规范与门策略版本 | 只保留总分而丢失样本结果 |
| 路由与价格 | 路由/回退清单、价格口径与生效时间 | 自动换供应商或用当前价格回算历史 |
不可变版本与可移动别名
不可变版本指向一个确定内容；production、champion、latest等别名是可移动指针。别名便于运维，但发布系统必须：
- 在开始时解析别名；
- 将实际版本和内容摘要写入发布记录；
- 发布中途不再重新解析；
- 在Trace中记录实际版本，而不只记别名。
对不提供固定模型快照的供应商，当前只能记录可获得的最强证据，加强回归评测和Canary，并明确标注“无法证明服务端权重不变”。
一个简化manifest
{
"release_id": "support-agent-2026-07-14.1",
"app": {"commit": "6f1a2c9"},
"api": {"contract": "responses-v3", "sdk_lock": "sha256:..."},
"prompt": {"id": "triage-v4", "sha256": "sha256:..."},
"context_policy": "context-v3",
"retrieval": {"snapshot": "kb-2026-07-10", "config": "retrieval-v7"},
"model": {"provider": "provider-a", "version": "pinned-model-id"},
"tools": [{"name": "lookup_ticket", "schema": "sha256:...", "implementation": "tool-v5"}],
"guardrail_policy": "guardrails-v2",
"eval": {"suite": "support-regression-v8", "rubric": "rubric-v4", "grader": "grader-v5"},
"routing": {"policy": "routing-v3", "fallback": "fallback-release-v2"},
"pricing_policy": "price-snapshot-2026-07-12"
}这段是可复制的严格 JSON，故不在行尾插入会破坏语法的注释：release_id 是一次不可变发布身份；app 与 api 固定代码和接口合同；prompt、context_policy、retrieval、model 与 tools 共同定义模型运行输入与外部能力；guardrail_policy 绑定安全控制；eval 固定离线证据；routing 固定路由和降级路径；pricing_policy 固定成本解释口径。
sha256:...是教学占位符，不是真实摘要。真实manifest还需包含创建者、创建时间、评测证据、审批与回滚目标。
谱系查询要回答什么
从任意一次线上输出的request_id开始，应能回答：当时运行的release是谁？用了哪些文档或工具？评测过哪些版本化门？同一release是否会因外部依赖漂移而改变？如果不能回答，系统只有“日志”，没有完整谱系。
常见错误与排查
- 用文件名当版本：
prompt.txt可以被覆盖；保留内容摘要和不可变快照。 - 工具schema版本化，实现没有：同一参数可能开始产生新副作用；两者都要固定。
- 只记知识库名：文档会持续变化；记快照或索引构建ID。
- 把会话原文当谱系：原文可含个人信息和密钥；谱系优先记版本和摘要，内容需独立的必要性、脱敏和保留期策略。
练习与自测
为“基于内部文档回答报销问题”的助手写一份manifest，必须包含Prompt、上下文、检索、模型、工具、护栏和评测。然后回答：
- 为什么Git commit不能代替Prompt内容摘要？
- 如果供应商只给一个浮动模型名，你能证明什么，不能证明什么？
- 为什么回滚必须以整个manifest为单元？
小结与下一步
LLMOps的第一步是让行为变化有名字、有证据、能比较。下一步用 网关、配额与弹性 控制这些发布单元如何访问外部模型。
参考资料
- OpenAI API backwards compatibility（访问于2026-07-14；说明固定模型版本与评测的作用）
- MLflow Tracking（访问于2026-07-14；通用 run 与制品追踪思路）