知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent 版本管理与灰度发布 > 导读:本文从"只改了一句 Prompt,退款流程的成功率一夜之间掉了三成"这个具体痛点出发,把 Agent 为什么比普通服务难做版本管理、四类可独立变更的"版本"、Agent 版本建模与快照、灰度分流与会话级一致性、双门禁评估与自动回滚、变更可追溯,以及一个"配置化 Agent 版本 + 灰度分流"的实现示例逐项讲透,最后给出工程实践与踩坑清单。适合正在把 Agent 从 Demo 推向生产、需要对线上效果负责的后端、平台与算法同学。 ## 一、先建立全局认知 ### Q:为什么 Agent 比普通服务难做版本管理? A:结论先行——**普通服务的一次变更,边界是"代码 + 配置 + 数据 Schema",发布物是唯一的镜像,改了什么都写在 diff 里;而 Agent 的行为由 Prompt、模型、工具、记忆这四类可独立变更的资产共同决定——它们能各自独立上线、改动成本极低、且彼此耦合,任何一个动一下都可能让整体行为发生非线性偏移。** 先把两种系统的"变更面"摆在一起对比: | 维度 | 普通微服务 | Agent 服务 | | --- | --- | --- | | 行为由谁决定 | 代码逻辑(确定性) | Prompt + 模型 + 工具描述 + 记忆策略(统计性) | | 可变更资产数量 | 1 个发布物(镜像) | 4 类,可独立变更、独立上线 | | 变更粒度 | 代码级(需构建、测试、发布) | 文本级(改一行 Prompt 就能生效) | | 效果可预测性 | 高(同输入同输出) | 低(同样输入,行为可能整体偏移) | | 回滚方式 | 回滚镜像/版本号 | 回滚哪一个资产?Prompt 还是模型? | | 故障定位 | 看栈、看指标、看变更 | 没有栈,只有"答得不对",因果链长 | | 影响面 | 按接口/流量 | 按会话,且同一会话可能跨越版本切换 | 这里最关键的一点是**变更成本的非对称**:改一个 Prompt 的成本接近于零(不用编译、不用发版),但它的效果影响可能是全局的。低成本 + 高杠杆,意味着团队会频繁改动,而每一次改动都没有天然的"发布仪式"来兜住风险。这正是版本管理要解决的问题。 举一个真实会发生的链路:  *图:无版本无灰度改 Prompt,三个副作用拖垮退款成功率* ```text 运营反馈:"退款政策变了,请把 System Prompt 里那句'7 天无理由'改成'15 天无理由'。" │ ├─ 工程师直接改 Prompt → 保存 → 即时生效(无版本、无灰度) │ ├─ 副作用 1:Prompt 变长 40 字,前缀缓存命中率从 X% 掉到更低 ├─ 副作用 2:模型把"15 天"错误地套用到"换货"分支 ├─ 副作用 3:工具描述的语义边界没跟着改,模型开始乱调 submit_refund │ └─ 结果:退款成功率下降,但没有任何指标能立刻指向"因为改了那句话" ``` 这张图的重点不是"改错了",而是**改一次 Prompt 引发的后果散布在缓存、工具调用、分支语义三个层次,而团队没有把它们绑成一次可回滚的发布**。 ### Q:Agent 的四类"版本"分别是什么? A:结论先行——**一次完整可追溯的 Agent 行为,至少由四类可独立变更的版本共同决定:Prompt/指令版本、模型版本、工具与工具描述版本、记忆与检索策略版本。它们不是四个子系统,而是四个"能各自单独变、却共同决定一次输出"的变量。** 四类版本的定义、变更频率与典型事故: | 版本类型 | 内容 | 变更频率 | 典型事故 | | --- | --- | --- | --- | | Prompt/指令版本(Prompt Version) | System Prompt、少样本示例、输出格式约束、安全边界话术 | 高 | 改了措辞,模型对工具的选择偏好整体偏移 | | 模型版本(Model Version) | 供应商、模型名、具体版本号、采样参数 | 中 | 供应商静默升级模型版本,风格/格式兼容性变化 | | 工具与工具描述版本(Tool & Tool-Description Version) | 工具名、参数 Schema、**自然语言描述**、实现代码 | 中 | 只改了工具实现没改描述,模型仍按旧语义调用 | | 记忆与检索策略版本(Memory & Retrieval Version) | 会话记忆策略、摘要规则、检索器、切片/TopN/重排、Embedding 模型 | 中 | 换了 Embedding 模型,历史向量与查询不同源,召回全乱 | 这里有三个必须建立起来的认知: 1. **Prompt 版本 ≠ 提示词文件版本。** 同一个文件里的内容拼接顺序(System / 工具定义 / 少样本 / 检索片段 / 历史 / 当前问题)本身就是行为的一部分。拼接顺序变了,即使每段文本都没改,行为也可能变——尤其当存在前缀缓存时,顺序直接决定成本。 2. **工具描述是"给模型看的 API 文档",它和工具体是两套可独立变更的东西。** 工具体改了返回结构但描述没改,模型会按旧结构解析,导致"参数对不上"的隐性失败;反过来,描述写得含糊会让模型乱调工具,即使实现完全正确。 3. **记忆与检索是"隐形的版本"。** 它不在 Prompt 文件里,但检索回来的内容会改变模型看到的事实。切片策略、TopN、相似度阈值、Embedding 模型任何一项变了,都等价于换了一套 Prompt。 用一张结构图把四类版本与"一次生成"的关系固定下来:  *图:四类版本拼装成一次推理请求,工具副作用回流为记忆* ```text ┌──────────────────────┐ │ Prompt/指令版本 │──┐ └──────────────────────┘ │ ┌──────────────────────┐ │ 拼装成一次 │ 模型版本(+参数) │──┼──▶ 推理请求 ──▶ 输出 └──────────────────────┘ │ ┌────────────┐ ┌──────────────────────┐ │ │ 记忆/检索 │────▶│ 工具与工具描述版本 │──┘ │ 策略版本 │ └──────────────────────┘ └────────────┘ │ ▲ ▼ │ 实际执行的工具调用(副作用/写数据) └─────────── 产生新的记忆,回流 ──────────── ``` **这张图的工程含义**:四类版本必须能被"打包成一个可寻址的快照"(下一节),否则你永远说不清"线上现在跑的到底是什么"。 ### Q:为什么"改一个 Prompt"就可能整体退化? A:结论先行——**因为 Prompt 不是一段独立文案,而是整个 Agent 联合行为分布的"调节旋钮":它同时影响模型的工具选择偏好、输出格式、拒绝边界和上下文关注点,这些影响彼此缠绕,且模型没有"局部改动只产生局部影响"的保证。** 具体拆开看,一次看似局部的 Prompt 改动会通过四条路径扩散: **路径一:改变工具选择的先验。** 模型选哪个工具,很大程度上取决于工具描述与 System Prompt 里的措辞。你在 System Prompt 里加一句"优先保证用户满意度",模型可能从"先查订单再退款"变成"直接退款",跳过了本该有的校验步骤。 **路径二:改变输出格式的稳定性。** 加一句"请用自然语言友好地解释",可能让本该严格 JSON 的输出带上前后缀,下游解析直接失败。格式类约束是"全有或全无"的,退化表现为解析失败率上升,而不是"稍微差一点"。 **路径三:改变安全边界。** 安全话术往往靠"不要做 X"这类负向约束实现,而模型对负向约束的遵守程度低于正向约束。你为了措辞更简洁把"绝对不能"改成"尽量不要",拒绝率可能显著变化。**具体影响幅度需结合所用模型与版本做回归确认。** **路径四:改变 Token 结构与成本。** Prompt 变长会直接影响输入 Token;如果这段文本位于可缓存前缀中,把它插到中间会打断前缀,缓存命中率下降。 一句话总结:**Prompt 是杠杆,不是文案。杠杆的另一端连着四个你不想同时动的开关。** ## 二、版本建模:把一次 Agent 配置定义成可寻址的快照 ### Q:怎么把一个"Agent 版本"定义清楚? A:结论先行——**把 Agent 版本定义为一个不可变的、内容可寻址的配置快照,它必须包含"能唯一复现一次行为"的全部要素:四类版本引用、采样参数、工具集、拼接顺序、以及安全/预算约束。任何没有写进快照的东西,都会成为线上不可复现的"幽灵变量"。** 下面是推荐的字段清单(不是某个框架的 API,而是通用建模清单): | 分组 | 字段 | 作用 | | --- | --- | --- | | 身份 | `agent_id`、`version_id`、`content_hash`、`status` | 寻址、判等、生命周期状态 | | Prompt | `prompt_ref`、`prompt_version`、`template_vars`、`segment_order` | 指令内容 + 拼接顺序 | | 模型 | `provider`、`model`、`model_version`、`params`(温度、最大输出等) | 复现生成行为 | | 工具 | `tools[]`(名称 + 描述版本 + 实现版本)、`tool_choice` 策略 | 决定"能做什么" | | 记忆/检索 | `memory_strategy`、`retriever_version`、`chunk_policy`、`top_k`、`embedding_model` | 决定"看到了什么" | | 安全/预算 | `max_steps`、`max_tokens`、`timeout`、`guardrails_version` | 决定"最多能做多少" | | 治理 | `owner`、`created_by`、`created_at`、`changelog`、`parent_version` | 可追溯、可对比 | 关键原则有三条: 1. **不可变(Immutable)。** 一个 `version_id` 一旦发布就不能再修改内容。要改就产生新版本。这保证"回滚"是切换到旧快照,而不是"重新编辑"。 2. **内容寻址(Content-addressed)。** `content_hash` 由快照内容计算得出,两个版本内容相同则哈希相同。这样能自动识别"换了个名字但内容没变"的无效发布。 3. **引用而非内联。** Prompt、工具描述等可以单独版本化,快照里存引用。这样一个 Prompt 被多个 Agent 共用时,改动影响面可被精确查询。 一个直观的快照示例(YAML 仅为示意,字段按自身平台定义): ```yaml # 一个不可变的 Agent 版本快照(示意,字段名按自身平台约定) version_id: refund-assistant@2026.09.14-3 content_hash: sha256:xxxxxxxx # 由下方内容计算,用于判等与去重 status: canary # active | canary | deprecated | rolled_back prompt: ref: prompt://refund/system prompt_version: 12 # Prompt 独立版本号 segment_order: # 拼接顺序属于快照的一部分 - system - tool_defs - few_shots - retrieved_docs - history - user_input model: provider: your-provider model: your-model model_version: "2026-09" # 必须写具体版本,禁止 "latest" params: temperature: 0.2 # 取值区间/是否生效需结合所选模型确认 max_output_tokens: 1024 tools: - name: query_order desc_version: 3 impl_version: 7 - name: submit_refund desc_version: 5 impl_version: 9 memory: strategy: session_summary # 会话摘要策略 retriever_version: 4 top_k: 5 embedding_model: your-embedding-model guardrails: max_steps: 8 timeout_ms: 60000 guardrails_version: 2 governance: owner: team-payments created_by: alice changelog: "把退款时效 7 天改为 15 天,并同步更新 submit_refund 描述" parent_version: refund-assistant@2026.09.10-1 ``` **代码后解释**:这份快照的价值在于,给出 `version_id` 就能完整复现一次行为,也能回答"这版和上一版到底差在哪"(逐字段 diff)。`model_version` 明确禁止 `latest` 这类浮动值——浮动值等于把版本控制权交给供应商,是线上事故的常见根因。**模型是否支持该参数、默认值是多少,需结合版本与官方文档确认。** ### Q:版本号和快照,谁才是真正的"发布单元"? A:结论先行——**发布单元是不可变快照,版本号只是它的人类可读别名。真正决定线上行为的是快照内容,而不是版本号字符串;因此判等与回滚都必须基于 `content_hash`,而不是基于名字。** 原因很直接: - 人会重命名、会复用旧名字、会"就地改一下"同一版本。如果发布单元是版本号,就会出现"同一个 `v2` 在不同时间代表不同内容",追溯立刻失效。 - 回滚必须是"把流量切回某个确定的旧内容",而不是"把某个叫 v2 的东西重新部署一遍"。 因此发布流程应固化为:  *图:版本变更从 content_hash 到灰度发布的门禁流程* ```text 编写配置 ──▶ 计算 content_hash ──▶ 与已有版本比对 │ ┌────────────────┴────────────────┐ 已存在 不存在 │ │ 提示"内容无变化" 落库为新快照(不可变) │ ┌────────────────────────┴───────────────┐ │ 离线评测门禁(评测集回归) │ └────────────────────────┬───────────────┘ │ 通过 进入 canary(小流量) │ 在线指标门禁通过 ▼ 提升为 active(全量) │ 任一指标越界 ▼ 自动切回上一个 active 快照 ``` ### Q:四类版本和 Agent 版本是什么关系? A:结论先行——**Agent 版本是"四类版本引用的集合 + 编排参数"的父快照;四类版本是子版本。发布时以父快照为单位,但排查与评估时以子版本为线索。** 这带来一个很实用的能力:**影响面分析**。当某个 Prompt 版本被改动时,你可以回答"哪些 Agent 版本引用了它、这些 Agent 版本当前承载多少流量、涉及哪些会话"。反之,当某个 Agent 版本指标异常时,能 diff 出它的四类子版本相对上一版各自变了什么。  *图:父快照含四个子版本,被多版本共享就互相牵连* ```text Agent 版本(父快照) ├── prompt_version: 12 ──┐ ├── model_version: 2026-09│ ├── tools[].desc_version ─┼──▶ 子版本被多个 Agent 版本共享时, └── retriever_version: 4 ─┘ 一次子版本变更 = 多个 Agent 受影响 ``` 这张图的工程含义:**子版本共享是"省事"和"爆炸半径"的交换。** 共用一份 Prompt 减少维护成本,但一次改动会同时命中所有引用者。所以共享的子版本变更必须走"父版本级"的灰度,而不是"子版本直接覆盖"。 ## 三、灰度分流与会话级一致性 ### Q:Agent 的灰度怎么做分流? A:结论先行——**分流维度按"隔离强度"从高到低依次是:租户/账号 → 用户 → 会话 → 请求。应优先在"用户/会话"这种稳定维度上分流,避免在"请求"维度分流出"同一会话反复横跳"的问题。** 常见分流维度对比: | 分流维度 | 一致性 | 样本代表性 | 适用阶段 | | --- | --- | --- | --- | | 按租户(Tenant) | 最强 | 偏差大(大客户可能被整体隔离) | 早期验证、重要客户保护 | | 按用户(User) | 强(用户级粘性) | 较好 | 常规灰度主力 | | 按会话(Session) | 强(会话内一致) | 好 | 有状态对话的推荐维度 | | 按请求(Request) | 无(同一会话会横跳) | 最好 | 仅适合无状态、单轮场景 | | 按地域/渠道 | 强 | 有偏差 | 便于运营侧观测对比 | 分流的实现要点: 1. **用稳定键做哈希,而不是随机数。** 以 `session_id` 或 `user_id` 为输入做一致性哈希映射到 `[0, 100)`,落在区间内的走新版本。随机数会导致同一个用户每次请求结果不同。 2. **灰度比例要能被"逐步抬升"而不中断已有会话。** 从 5% 抬到 20% 时,已经在 5% 里的会话必须仍然命中新版本(映射区间单调扩张),不能"抬升后又被切回旧版"。 3. **必须有止损开关(Kill Switch)。** 一个不看比例的强制开关,出事时能一键把某版本流量归零。 一个把"灰度比例 + 会话粘性"讲清楚的分流示意:  *图:按 hash 分桶做会话级灰度,5% 抬到 20% 不横跳* ```text bucket = hash(agent_id + session_id) % 100 # 0..99,会话级稳定 若 bucket < canary_percent ──▶ 走 canary 版本 否则 ──▶ 走 active 版本 比例抬升:canary_percent 5 → 20 bucket=3 的会话:3<5 且 3<20 ──▶ 始终 canary(不横跳) bucket=10 的会话:10≥5 但 10<20 ──▶ 旧→新(一次性切换,之后稳定) bucket=50 的会话:始终 active ``` 关键点:**哈希输入里带上 `agent_id`**,避免"多个 Agent 共用同一个用户的会话键"时,灰度比例被互相干扰。适用边界:当某个会话被固定到 canary 后,如果该会话很长、跨越了版本切换点,仍然只能整体走一个版本——这正是下一问要解决的约束。 ### Q:为什么同一会话不能中途换版本? A:结论先行——**因为 Agent 会话是有状态的,上下文(历史消息、工具调用记录、已产生副作用的操作)是跨轮累积的。中途换版本会出现"上下文结构与新版本 Prompt 不兼容""工具调用参数按旧 Schema 提交""同一会话前后行为不一致导致用户困惑"三类问题。** 具体三类风险: | 风险 | 发生机理 | 后果举例(示意) | | --- | --- | --- | | 上下文不兼容 | 新版本 Prompt 期望的历史格式/字段与旧版不同 | 新版解析不到旧版写入的关键字段,丢失约束 | | 工具 Schema 漂移 | 会话中还挂着旧版工具调用的中间状态,新版参数结构变了 | 参数校验失败、重复提交、重复扣款 | | 行为不一致 | 用户对同一会话已有预期,突然换了话术/策略 | 用户感知为"这机器人坏了" | 因此工程上要做**会话级版本钉死(Version Pinning)**:会话创建时确定版本,并把 `version_id` 写入会话状态;此后该会话的每一轮都强制用这个版本,直到会话结束或用户显式开新会话。  *图:会话创建时绑定 version_id 并保持稳定* ```text 会话生命周期: 创建会话 ──▶ 计算 bucket ──▶ 确定 version_id ──▶ 写入会话状态(持久化) │ ├─ 第 1 轮 ──▶ 读会话状态 → version_id=A ──▶ 用 A ├─ 第 2 轮 ──▶ 读会话状态 → version_id=A ──▶ 用 A (即使灰度已抬升到更高比例) ├─ ... └─ 会话结束/超时 ──▶ 下次新会话重新计算 bucket ``` 例外与边界: - **长会话需要"迁移策略"。** 如果某个版本因严重问题被紧急下线(`rolled_back`),钉死在该版本的会话必须被强制迁移。此时不能"悄悄换版本",而应明确降级话术(如"当前会话状态异常,请重新开始"),并记录迁移事件。 - **安全性优先于一致性。** 当版本被判定为存在安全/合规问题时,会话一致性必须让位于止损,直接强制切换并重置会话上下文。 ### Q:什么是影子流量,为什么 Agent 特别需要它? A:结论先行——**影子流量(Shadow Traffic)是把真实请求复制一份发给新版本、但只记录其输出、不把结果返回给用户、也不执行其副作用。Agent 特别需要它,因为 Agent 的输出是统计性的,A/B 小流量往往不足以在"有副作用的工具调用"上暴露问题。** 影子流量的关键约束: 1. **必须屏蔽副作用。** 新版本若调用了写数据的工具(下单、退款、发消息),影子模式必须把这些工具替换为"空实现/录制实现",否则影子流量会真实改数据。 2. **只用于质量对比,不用于放量决策的唯一依据。** 影子流量不承担真实用户反馈,因此它擅长发现"离线评测覆盖不到的失败模式",但不能替代在线指标。 3. **成本要单列。** 影子流量会成倍消耗 Token 与工具调用配额。**影子比例必须受控,并把影子成本单独归因,避免污染租户账单。**  *图:影子版本只跑 dry-run,结果落日志做离线对比* ```text 真实请求 ──┬──▶ 线上版本(active) ──▶ 结果返回用户(副作用真实执行) │ └──▶ 影子版本(canary) ──▶ 结果仅落日志(副作用被替换为 dry-run) └─▶ 离线/在线对比:差异率、失败类型分布 ``` ## 四、评估门禁与自动回滚 ### Q:Agent 的效果怎么评估才敢放量? A:结论先行——**必须"双门禁":离线评测集回归(防"已知能力退化")+ 在线指标监控(防"未知场景退化")。两者都通过才能放量;离线保证不劣化既有用例,在线保证真实分布下没有新问题。** 两类门禁的分工: | 门禁 | 数据来源 | 优势 | 局限 | 放量作用 | | --- | --- | --- | --- | --- | | 离线评测集 | 固定用例集(问题→期望行为/答案) | 可复现、可回归、快 | 覆盖不到长尾、易过期 | 放量的必要条件 | | 在线指标 | 真实流量(成功率、工具成功率、投诉率等) | 反映真实分布、发现未知问题 | 有噪声、需要量、慢 | 放量的决策依据 | Agent 的评估指标不能只看"答得像不像",要分层次: | 层次 | 指标示例 | 说明 | | --- | --- | --- | | 任务层 | 任务完成率、多步成功率 | 端到端是否把事办成 | | 工具层 | 工具选择准确率、参数正确率、调用失败率、重复调用率 | Agent 特有,最能暴露问题 | | 输出层 | 格式合规率、拒答率、幻觉率(抽样) | 稳定性与安全 | | 成本/性能层 | 平均步数、Token/请求、P95 延迟 | 退化常伴随步数暴涨 | | 体验层 | 追问率、转人工率、投诉率 | 最终护栏 | **离线评测集要分层:** 核心集(少量、高频、必须 100% 通过)+ 回归集(历史 bug 用例)+ 探索集(覆盖长尾)。评测集的维护规则同样重要:**评测集本身要有版本和过期机制**,因为业务规则(如退款时效)变了之后,旧评测集的"标准答案"会变成错的,此时用它做门禁会误伤正确的改动。 ### Q:自动回滚的触发条件怎么设? A:结论先行——**回滚条件应基于"相对变化"而非绝对值,且要区分"立即回滚(硬伤)"和"观察后再定(软伤)"两类。硬伤类(安全、错误率飙升、工具重复副作用)一经触发立即回滚;软伤类(体验指标轻微波动)先观察,结合样本量再判断。** 触发条件设计示例(阈值 X 必须用自身业务历史波动定,**不要照搬任何"业界值"**): ```text 【硬伤:立即回滚】 1) 安全违规事件数 > 0(越权、泄露、违规动作) 2) 工具重复副作用率(同一会话重复写操作)环比 > X% 3) 任务完成率下降 > X%(且样本量 ≥ N,避免小样本误判) 4) 错误率/异常率突增 > X% 5) P95 延迟上涨 > X%(用户可感知的卡顿) 【软伤:告警 + 观察窗口】 6) 追问率上升 > X% 7) 平均步数上涨 > X%(成本与效率信号) 8) 输出格式合规率下降 > X% 9) 拒答率异常上升(可能过度保守) 【回滚执行】 - 回滚动作 = 把流量从 canary 快照切回上一个 active 快照 - 回滚必须同时:① 停止新会话进入 canary;② 按会话一致性策略处理已钉死会话 - 回滚后自动冻结该版本,禁止再次直接放量,需人工复核 ``` 三个易踩的细节: 1. **样本量不足时不要触发自动回滚。** 灰度初期样本少,一个偶发失败就可能让指标"看起来"暴跌。所有触发条件都应带"最小样本量"前置判断。 2. **回滚要"彻底"。** 只切流量而不处理缓存、会话状态、异步任务,等于"看起来回滚了,其实还在跑旧版"——见踩坑清单。 3. **回滚不是终点。** 每次自动回滚都应自动附带一份"版本 diff + 相关指标快照",否则复盘时无法快速定位到是哪一类子版本变更导致。 ## 五、变更可追溯与实现示例 ### Q:出了问题怎么追溯到"谁改的、改了哪一版、影响哪些会话"? A:结论先行——**可追溯的前提是"每一次生成都写入完整的版本指纹,每一次变更都写入不可篡改的变更记录"。缺版本指纹,就无法从一次坏回答反推到版本;缺变更记录,就无法从版本反推到人。** 要记录的两类数据: | 记录类型 | 必含字段 | | --- | --- | | 生成侧(每次调用) | `trace_id`、`session_id`、`tenant_id`、`user_id`、`agent_version_id`、`content_hash`、四类子版本号、`model_version`、`prompt_segment_order_hash` | | 变更侧(每次发布) | `version_id`、`parent_version`、`diff`(逐字段)、`changed_by`、`approved_by`、`changelog`、`offline_eval_result`、`released_at`、`rollback_of`(若为回滚) | 有了这两类数据,三个追溯问题都能回答: - **谁改的、改了哪一版?** → 按 `version_id` 查变更记录,得到人、时间、逐字段 diff。 - **影响哪些会话?** → 按 `version_id` 反查生成侧记录,得到命中的 `session_id` 集合与流量占比。 - **如何复现?** → 用 `content_hash` 取出当时的完整快照,加上保存的输入与随机种子/参数,重放该次生成。**能否逐字节复现取决于供应商是否暴露确定性参数,需结合版本确认。**  *图:变更侧与生成侧记录,用 version_id 关联* ```text ┌────────────── 变更侧(发布记录) ──────────────┐ │ version_id ─ diff ─ changed_by ─ 评测结果 │ └───────────────────────┬───────────────────────┘ │ version_id ▼ ┌────────────── 生成侧(调用记录) ──────────────┐ │ trace_id ─ session_id ─ user_id ─ 指标 ─ 结果 │ └───────────────────────────────────────────────┘ 一次坏回答 ──▶ 反查版本 ──▶ 反查变更人 ──▶ diff 定位子版本 ``` ### Q:一个"配置化 Agent 版本 + 灰度分流"的实现示例 下面用一个最小可运行的 Python 示例,把"快照 + 内容寻址 + 会话级分流 + 熔断开关"串起来。它解决的是"如何稳定地把一个会话钉死到某个版本,并支持安全放量与一键回滚"。 ```python import hashlib import json from dataclasses import dataclass, field, asdict from typing import Dict, List, Optional @dataclass(frozen=True) # 不可变:发布单元必须冻结 class AgentVersion: version_id: str prompt_version: int model: str model_version: str desc_versions: Dict[str, int] # 工具名 -> 描述版本 retriever_version: int segment_order: List[str] = field(default_factory=list) def content_hash(self) -> str: """内容寻址:由快照内容计算,用于判等与去重""" payload = json.dumps(asdict(self), sort_keys=True, ensure_ascii=False) return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest() class VersionRegistry: """版本注册表:active 为全量版本,canary 为灰度版本""" def __init__(self): self._active: Optional[AgentVersion] = None self._canary: Optional[AgentVersion] = None self._canary_percent = 0 # 灰度比例 0..100 self._kill_switch = False # 强制回滚开关 def set_active(self, v: AgentVersion): self._active = v def set_canary(self, v: AgentVersion, percent: int): if not 0 <= percent <= 100: raise ValueError("percent 必须在 0..100") self._canary, self._canary_percent = v, percent def promote(self): """灰度通过在线门禁后,canary 提升为 active""" if self._canary is None: raise RuntimeError("没有可提升的 canary 版本") self._active, self._canary, self._canary_percent = self._canary, None, 0 def rollback(self): """一键回滚:停止 canary 流量(active 不变)""" self._canary, self._canary_percent, self._kill_switch = None, 0, True # 注意:已钉死会话需按迁移策略处理,见下方 resolve_for_session def _bucket(self, agent_id: str, session_id: str) -> int: """稳定哈希:同一会话恒得同一桶,抬升比例时不横跳""" key = f"{agent_id}:{session_id}".encode("utf-8") return int(hashlib.sha256(key).hexdigest(), 16) % 100 def resolve_for_session(self, agent_id: str, session_id: str, pinned: Optional[str]) -> AgentVersion: """ 会话级版本解析: 1) 已钉死 → 直接返回钉死版本(会话内一致) 2) 未钉死 → 按桶决定 canary 还是 active """ if pinned: if self._canary is not None and pinned == self._canary.version_id: # 钉死的 canary 版本仍允许继续,保证会话内不横跳 return self._canary if self._active is not None and pinned == self._active.version_id: return self._active # 钉死版本已被下线:强制迁移,需显式提示,不能静默换版 raise RuntimeError(f"pinned version {pinned} 已下线,请重置会话") if self._kill_switch or self._canary is None: return self._active return self._canary if self._bucket(agent_id, session_id) < self._canary_percent \ else self._active ``` **代码后解释与适用边界:** - `AgentVersion` 用 `frozen=True` 强制不可变,`content_hash()` 实现内容寻址,发布会话中若与既有版本哈希一致可直接拒绝重复发布。 - `_bucket` 用 `sha256(agent_id + session_id) % 100`,保证**会话级稳定**与**比例单调抬升**:比例从 5 涨到 20,原本落在 [0,5) 的会话仍在 canary 中,不会横跳。 - `pinned` 参数体现**会话级一致性**:一旦确定版本就写回会话状态,后续轮次直接复用。 - 钉死版本被下线时抛异常而不是静默换版,是为了**避免中途换版**;生产上应配合"重置会话"的用户提示,而不是无感切换。 - 边界:本示例把 `canary` 与 `active` 放在单进程内存里,**生产环境必须持久化到配置中心/数据库**,否则多实例间灰度比例不一致;同时 `_kill_switch` 应为全局可下发状态,且回滚后要能级联处理已钉死的长会话。此外,本示例未包含"按租户强制隔离"逻辑,接入多租户时需在 `resolve_for_session` 前增加租户白/黑名单判断。 ## 六、工程实践与踩坑 **坑 1:会话中途换版。** 根因:分流按"请求"维度做,或灰度比例抬升后没有做会话粘性。表现:用户在第 3 轮突然发现 Agent 换了个人格,或工具调用参数结构对不上。防护:**分流键用会话/用户且哈希稳定;版本写入会话状态并持久化;比例抬升只允许单调扩张。** **坑 2:缓存与 Prompt 版本不一致。** 根因:语义缓存/Prompt 前缀缓存的键里没带 `prompt_version`,改了 Prompt 后仍命中旧缓存;或改了拼接顺序导致前缀缓存失效但无人知晓。防护:**所有缓存键必须包含 `agent_version_id`(或至少 `prompt_version`);缓存命中率纳入发布门禁指标;发布后校验缓存是否正确失效。** **坑 3:灰度样本不足就下结论。** 根因:小流量下指标波动被当成"退化",或反过来把偶发的"看起来更好"当成成功。防护:**所有门禁加最小样本量前置;对完成率这类二值指标,关注置信区间而不是点估计;灰度时长至少覆盖一个业务周期(如工作日/周末)。** **坑 4:回滚不彻底。** 根因:只切了流量入口,但缓存、会话钉死状态、异步任务队列、影子流量开关没有一起处理。表现:"回滚了但用户还在报错"。防护:**把回滚定义为一次原子操作清单(流量 + 缓存 + 会话迁移 + 异步任务 + 开关),回滚后跑一遍冒烟用例确认。** **坑 5:评测集过期。** 根因:业务规则变了,评测集里"标准答案"没更新。表现:正确的改动被门禁拦下,或错误改动被放行。防护:**评测集纳入版本管理,随业务规则变更同步维护;对每条用例标注"依据的业务规则版本",规则失效则用例失效。** **坑 6:模型版本写 `latest` 或用浮动别名。** 根因:图省事用浮动版本,把版本控制权交给了供应商。表现:某天供应商静默升级,风格/格式兼容性变化,无任何本地变更记录可查。防护:**快照里写具体版本号;对模型版本做定期观测与钉死策略;供应商若不提供版本固定能力,需在应用层做输出格式的强校验兜底。** **坑 7:只版本化 Prompt,不版本化工具描述。** 根因:认为"工具描述只是注释"。表现:工具体改了返回结构但描述没改,模型按旧结构解析导致隐性失败。防护:**工具描述纳入版本与变更评审;描述与工具体在同一发布单元内一起变。** **坑 8:没有"影响面"查询能力。** 根因:子版本被多个 Agent 共用,但没有反向索引。表现:改了一个共享 Prompt,不知道会影响哪些 Agent,只能全量重启。防护:**在版本注册表中维护"子版本 → 引用它的 Agent 版本"反向索引;共享子版本的变更必须走父版本级灰度。** **坑 9:影子流量把真实副作用打出去。** 根因:影子模式没有把写类工具替换为 dry-run。表现:测试流量真实下单/退款/发消息。防护:**影子模式默认屏蔽一切写操作;只允许读类工具真实执行;影子成本单独归因。** **坑 10:把"灰度"当成了"测试环境"。** 根因:认为进了 canary 就可以随便改,不受门禁约束。表现:canary 里版本被反复就地修改,无法追溯到底测的是哪一版。防护:**canary 同样是不可变快照;要改就发新版本;canary 流量比例与时长都要有明确上限。** ## 小结 - Agent 的行为由 **Prompt、模型、工具与工具描述、记忆与检索** 四类可独立变更的版本共同决定,四者耦合,任一处微调都可能造成非线性退化。 - 发布单元是**不可变、内容可寻址的快照**,版本号只是别名;回滚是"切回旧快照",不是"重新编辑"。 - **Prompt 是杠杆不是文案**:它会同时影响工具选择、输出格式、安全边界与 Token 结构。 - 灰度分流优先在**会话/用户**这类稳定维度进行,必须做**会话级版本钉死**,绝不允许同一会话中途换版;模型版本禁止使用浮动别名。 - 评估必须**双门禁**:离线评测集防已知退化、在线指标防未知退化;回滚触发条件基于相对变化并带最小样本量,硬伤立即回滚、软伤观察再定。 - 可追溯依赖两类记录:生成侧的**版本指纹**与变更侧的**不可篡改变更记录**;两者缺一不可。 - 所有阈值、比例、时长都要用自己的数据回归得出;评测集本身也要版本化并设置过期机制。 ## 思考题 1. 你的 Agent 目前能回答"线上这一次生成用的是哪一版 Prompt、哪一版工具描述"吗?如果不能,缺的是哪个环节的埋点。 2. 请为你的业务设计一份"Agent 版本快照"字段清单:哪些字段必须进快照才能复现行为?哪些可以外置成引用? 3. 灰度比例从 5% 抬到 20% 时,如何保证已有会话不被切回旧版?请写出你的哈希与区间设计。 4. 影子流量在你的系统里会产生哪些真实副作用?请列出需要 dry-run 化的工具清单与验证方法。 5. 设计一套"自动回滚"触发条件:哪些指标属于硬伤(立即回滚),哪些属于软伤(观察窗口)?你会给每个条件设置多小的样本量下限,理由是什么? 6. 评测集为什么会过期?请设计一套"随业务规则同步维护评测集"的流程,并给出用例失效的判定标准。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入