一、灰度不是百分比，而是可解释的变更账本
图注：先记录谁、为何、改了什么、影响谁，再讨论从多少比例开始放量。
很多团队说要给统一模型网关做灰度，最后落地成了一个数字：5%、10%、50%、100%。这个数字有用，但它不是灰度本身。真正的灰度是一个可解释的变更过程：谁发起变更，为什么变更，改了哪条路由，影响哪些调用方，验收哪些协议语义，观察哪些指标，在哪个条件下暂停，出现什么信号时回滚。没有这些账本，调小比例只是把不确定性推迟，而不是把风险变小。
模型网关的灰度比普通后端服务更敏感，因为它通常承载多个团队、多个应用、多个租户和多个上游。一次路由改动可能改变模型名映射、流式响应格式、错误分类、重试行为、超时预算、内容过滤、计费归属和审计字段。对某个低风险内部工具来说可接受的变化，放到客服、搜索、代码助手或自动化任务上，影响完全不同。如果只按全局百分比分流，就会把不同风险等级的调用混在一起。
所以灰度的第一步不是建路由规则，而是建变更账本。账本至少要写清 change_id、route_id、old_version、new_version、owner、affected_apps、affected_envs、affected_tenants、risk_level、validation_plan、pause_condition、rollback_version 和 approved_at。这些字段看起来琐碎，但它们能让事故中最关键的问题有答案：这次变更到底影响了谁，能不能停，怎么退回去，退回去会不会带回另一个风险。
本文只讨论通用工程方法，不把这些能力归因给某个具体服务。涉及"向量引擎"时，只使用事实白名单中已确认的固定地址：Base URL 是 https://api.vectorengine.cn，OpenAI 兼容接口前缀是 https://api.vectorengine.cn/v1，Chat Completions 接口是 https://api.vectorengine.cn/v1/chat/completions。需要延伸阅读配置入口时，可以查看 https://178.nz/dn。除此之外，不推断价格、模型数量、并发、延迟、SLA、日志、合规、SDK、客户案例或企业采购能力。
模型网关的灰度目标也要明确。它不是为了证明"新路由一定更好"，而是为了在可控范围内发现"不兼容、不稳定、不符合业务预期"的证据。能成功放量当然最好，但能及时暂停和回滚同样是成功。一个灰度系统如果只能向前推进，不能解释为什么暂停，也不能证明回滚生效，本质上只是慢速全量发布。
变更账本还应把"非目标"写清楚。比如这次只验证路由切换，不评估模型质量；这次只验证流式协议，不改变配额；这次只改预发环境，不影响生产租户。非目标不是多余说明，它能阻止灰度过程中临时叠加需求。很多事故并不是原始变更太危险，而是在执行中不断顺手加小改动：顺手换一个超时，顺手开一个日志字段，顺手调整一个重试次数。账本把边界写清楚，值班人员才有理由拒绝临时加料。
账本还要能被普通调用方看懂。模型网关维护者知道 route_id 和 policy_version 的含义，不代表业务团队知道自己是否受影响。变更单里最好同时保留机器字段和人能读懂的摘要：影响哪些应用、预计在哪个时间窗口观察、失败时谁会通知、调用方需要准备什么验证用例。灰度不是网关团队单方面的事情，它需要调用方提供业务验收信号。没有这层协作，网关只能看到技术指标，看不到真实体验是否退化。
二、先拆变更类型：模型、协议、路由和策略不能混在一起
图注：同样叫模型网关变更，风险可能来自模型、协议、路由或治理策略。
统一模型网关里的变更至少可以拆成四类。第一类是模型变更，例如把某条业务路由从一个模型切到另一个模型，或者调整模型名映射。第二类是协
议变更，例如从非流式改成流式，调整消息字段、工具调用、错误体或响应结束信号。第三类是路由变更，例如按应用、租户、地域、环境或标签切到不同上游。第四类是策略变更，例如鉴权、配额、重试、超时、日志采样和内容脱敏规则。
这四类变更不要混在同一次灰度里。一次只改模型时，验收重点是输出质量、错误率、延迟和业务指标；一次只改协议时，验收重点是客户端是否能解析响应、是否能处理流式 chunk、错误码是否被正确归因；一次只改路由时，验收重点是流量是否进入预期上游、上游配额是否足够、回滚是否能回到旧路由；一次只改策略时，验收重点是拒绝率、误杀率、审计字段和告警对象。
如果一次发布同时改模型、改协议、改路由、改重试和改日志，灰度失败时就很难定位。调用方看到的是同一个"请求失败"，网关日志里却可能有多个同时变化的因子。工程上更稳妥的做法是让每个变更都有独立版本号，必要时按阶段串联：先在影子流量里验证协议，再对低风险调用方切路由，再小比例验证模型表现，最后调整治理策略。每一步都有单独的停止条件。
变更类型拆清楚后，灰度对象也能更具体。模型变更可以按任务类型和业务租户切；协议变更可以按客户端版本切；路由变更可以按应用、环境或上游健康度切；策略变更可以按权限主体、租户或风险等级切。不要把所有变更都强行塞进同一个百分比开关。百分比只描述流量大小，不能描述风险结构。
这也是为什么"能请求成功"不能等同于"兼容"。一个 OpenAI 兼容入口看起来字段相似，但语义仍需要单独验证。model 字段是否真实映射到调用方预期能力，messages 是否支持相同角色和内容结构，stream 的事件顺序是否被客户端正确处理，错误响应是否能被 SDK 或业务代码识别，超时和重试是否会放大上游压力。这些都不是一个 200 状态码能证明的。
拆变更类型时，还要标注依赖关系。协议适配器没有通过验证，就不要先切模型；路由账本没有写入请求日志，就不要开始分批；回滚版本不可加载，就不要进入生产 canary。依赖关系能让发布流程从"经验判断"变成"状态机"。每个状态只允许进入下一个明确状态，失败时回到哪个状态也写清楚。这样做看似保守，但对共享模型网关很必要，因为它影响的不是一个服务，而是一组团队的共同入口。
实践中可以用一张简单矩阵管理变更。横轴是变更类型，纵轴是验收项：请求结构、响应结构、流式结束、错误分类、超时、重试、日志字段、配额归属、回滚动作。每次变更只填相关格子，其他格子标为不涉及。这样既不会把所有发布都变成大工程，也不会漏掉关键协议语义。矩阵的价值不是文档好看，而是让"这次为什么敢放量"有可追溯依据。
三、路由账本要能回答谁被切走了
图注：路由账本要能反查某次请求为何进入某个上游，而不是只看当前配置。
模型网关的路由配置经常从一个简单映射开始：某个模型名转发到某个上游地址。随着团队增多，路由会越来越复杂：同一个模型名在不同环境下走不同上游，同一个应用在预发和生产走不同版本，同一个租户需要保留旧模型，同一个调用方因为合规或成本原因不能进入某条路由。此时如果仍然只保存当前配置，事故中就无法回答"这条请求为什么被切到了那里"。
路由账本至少要记录三个层次。第一层是声明层：某条路由的目标、匹配条件、负责人、风险等级、创建原因和回滚版本。第二层是决策层：每次请求命中了哪些条件，最终选择哪个 route_id 和 upstream_id。第三层是结果层：这次选择带来了什么状态码、错误类别、延迟、重试次数和上游请求 ID。声明层解释"本来想做什么"，决策层解释"实际做了什么"，结果层解释"做完发生了什么"。
灰度期间最怕"当前配置覆盖历史"。比如上午 10 点把 10% 流量切到新路由，10 点 15 分改成 30%，10 点 20 分临时排除一个租户，10 点 35 分又改了错误映射。若系统只保存最新配置，复盘时无法知道 10 点 18 分那批失败请求处在哪个版本。路由账本必须保存每个版本的生效时间、结束时间和审批关系，日志里也要记录请求命中的 policy_version。
Kubernetes Deployment 文档里滚动更新、暂停 rollout 和回滚 revision 的思路可以借鉴到网关变更：发布不是一次覆盖，而是一连串可观察、可暂停、可回到历史版本的状态转换。网关不一定运行在 Kubernetes 上，但它同样需要 revision 概念。没有 revision，就没有可靠回滚；没有请求级 route_id，就没有可靠归因。
路由账本还要避免把真实密钥写进去。日志里记录的是凭据引用、路由 ID 和上游名称，不是完整 API Key。调用方排错时应提交 trace_id、app_id、env、tenant_id 和错误码，而不是截图完整请求头。这样既能反查路由决策，又不会把灰度过程变成新的泄露渠道。
路由账本最好同时记录"未命中原因"。当某个调用方本应进入 canary 却没有进入时，问题可能来自环境字段缺失、租户不在名单、客户端版本过低、灰度开关被暂停、主体哈希不在比例内，或者更高优先级的保护规则覆盖了 canary。只记录最终路由，不记录排除原因，排错时仍然需要人工猜。把未命中原因写进调试字段，可以让调用方理解自己为什么还在旧路径，也能帮助网关团队发现规则顺序错误。
另一个细节是配置传播延迟。多副本网关、边缘节点、区域化部署和本地缓存都会让新路由版本在不同实例上生效时间不同。账本里应记录配置发布时间、实例加载时间和请求命中的版本。如果一个请求在灰度窗口内仍命中旧版本，不能简单判断为路由规则错误，可能只是实例还未加载新配置。没有这些时间戳，灰度复盘会被大量假线索干扰。
四、流量染色比随机百分比更适合多团队网关
图注：多团队共享入口应按调用方和风险染色，随机百分比只能作为辅助。
随机百分比适合风险相对均匀的流量，但模型网关里的流量通常不均匀。一个内部报表助手、一个客服对话系统、一个生产代码生成工具、一个离线摘要任务，对延迟、正确性、成本、隐私和可回滚性的要求都不同。如果把它们放进同一个 10% 抽样池，低风险流量可能没有被抽到，高风险流量却先被打中。
更实用的方法是流量染色。染色字段可以来自调用方身份、应用 ID、环境、租户、客户端版本、业务场景、请求类型和风险等级。比如先让开发环境和内部工具进入 canary，再让预发环境进入，再让少数低风险租户进入，最后才扩大到生产主路径。每一层都不是"更大的百分比"，而是"更明确的责任边界"。
OpenFeature 的 evaluation context 和 targeting key 给了一个有用的抽象：规则评估需要上下文，targeting key 可以稳定识别被评估主体，fractional evaluation 可以在稳定主体上做分配。放到模型网关里，灰度不要只靠请求时间随机，而应基于稳定主体。否则同一个用户或同一个应用的一连串请求可能在新旧路由之间来回跳，导致对话上下文、缓存、配额和用户体验都变得不可解释。
染色字段要少而稳。不要把完整用户输入、完整 prompt 或敏感业务正文放进路由规则；也不要依赖容易变化的临时字段。更适合的字段是 app_id、env、tenant_id、client_version、route_group、risk_level 和 stable_subject_hash。这样可以保证灰度规则可复现，也能降低敏感数据进入配置系统的风险。
Argo Rollouts 的 canary 策略支持 setWeight 和 pause，traffic management 还可以结合 header 等条件做 canary 路由。这个思路对模型网关有启发：权重只是一个维度，header、身份和上下文条件同样重要。把权重和染色结合起来，才能做到"先切哪些人，再切多少量"。
染色还要保证一致性。同一个会话、同一个任务链或同一个批处理作业，最好不要在中途随机切换路由。尤其是多轮对话、工具调用和异步任务，前半段走旧路由、后半段走新路由，会让上下文、缓存和错误归因变得混乱。可以用 stable_subject_hash 绑定会话或任务，让它在一个灰度窗口内稳定命中同一路由。等任务结束或新窗口开始，再重新评估。这样牺牲一点随机性，换来可解释性。
对于高风险租户，染色规则应支持显式排除。不是所有调用方都适合参与早期 canary。重要客户、关键生产任务、监管敏感数据、正在事故恢复中的业务，都可以先固定在旧路由。灰度系统不是为了展示覆盖率，而是为了控制风险。早期排除高风险对象，后期再单独制定验证计划，比把它们混进随机流量池更稳妥。
五、影子验证要先看协议，再看效果
图注：影子验证先证明新路由能处理同类请求，再谈生成效果是否更好。
灰度前最好有影子验证。影子验证不是把结果返回给用户，而是把真实或脱敏后的同类请求复制到候选路由，观察它是否能稳定处理。它的第一目标不是判断新模型回答更好，而是判断协议能不能跑通：请求体是否被接受，字段是否兼容，流式事件是否完整，错误响应是否可解析，超时和限流是否在预期范围内。
对 OpenAI 兼容接口迁移来说，协议验证尤其重要。Chat Completions 的流式输出会以 chunk 的形式返回，OpenAI 文档也提醒新流式场景应关注 Responses API 的语义事件。无论团队使用哪一种接口风格，网关都要验证客户端真正消费的事件序列。很多"模型不可用"的投诉，实际是流式解析器没有处理某个结束事件、空增量、工具调用片段或错误体。
影子验证应该输出结构化结果，而不是只看日志里有没有 200。建议至少记录：请求是否被候选路由接受，首包时间，最终状态码，错误类别，流式 chunk 数量，结束原因，请求大小区间，响应大小区间，是否触发重试，是否出现解析异常。内容质量评估可以另做，但协议和可用性先过关。协议不过关时，不要让真实用户进入灰度。
影子流量要控制边界。不要复制敏感正文到未授权上游，不要把生产用户的完整输入发给没有审批的候选路由，不要把影子输出写入普通日志。可以使用脱敏样本、合成请求、小型标注集或只复制元数据和结构。影子验证的目的不是扩大数据流转范围，而是在可控范围里发现不兼容。
影子验证通过后，仍然不能直接全量。它证明候选路由能处理相似请求，不证明它在真实业务里一定更稳。真实灰度还要观察业务级指标，例如有效回答率、用户取消率、人工接管率、任务完成率、重试率和投诉量。协议指标回答"能不能跑"，业务指标回答"是否可接受"，两者都需要。
影子验证也要注意样本代表性。只用短 prompt、单轮对话和成功路径样本，很容易漏掉长上下文、工具调用、空输出、上游限流和流式中断。样本集应覆盖常见长度、边界长度、错误请求、超时请求、不同客户端版本和不同业务场景。每个样本不一定需要真实内容，可以用结构相同的脱敏文本或合成文本替代。关键是让候选路由经历与真实流量相似的协议压力。
影子输出不要直接作为线上答案使用，但可以进入离线评估。对于有标注集的场景，可以对比旧路由和新路由在关键任务上的差异；对于没有标注集的场景，可以先做人工抽样或规则检查。无论使用哪种方式，都要把"质量评估"与"协议验证"分开记录。协议失败时停止推进，质量存在争议时进入业务评审，不要把两者混成一个模糊的通过结论。
六、放量门禁要写清暂停条件
图注：每个放量台阶都要有指标、观察时间、暂停条件和负责人。
很多灰度事故不是因为一开始放了 5%，而是因为从 5% 到 100% 的中间没有门禁。一个健康的放量计划应写成台阶：0% 影子验证，1% 内部生产，5% 低风险租户，20% 选定业务线，50% 主路径，100% 全量。每个台阶都要有观察时间、指标阈值、负责人、暂停条件和回滚版本。
门禁指标要分层。基础可用性指标包括成功率、错误率、超时率、首包时间、总耗时、流式中断率和上游 429。网关治理指标包括路由命中、策略拒绝、配额拒绝、重试次数、熔断次数和回滚开关状态。业务指标包括任务完成率、用户重试、人工接管、投诉、转化或内部验收评分。不要只看一个平均延迟，也不要只看上游状态码。
暂停条件要提前写好。比如任一关键调用方错误率超过基线两倍，流式解析异常超过阈值，某个租户出现连续鉴权失败，上游 429 明显上升，人工反馈出现严重误答，审计日志缺字段，或者回滚演练失败，都应暂停继续放量。暂停不是失败，而是灰度系统在工作。没有暂停条件的灰度，实际上是自动全量。
AWS 的 canary deployment 文档强调先把少量流量导向新版本，验证后再扩大；蓝绿部署则通过两个环境之间切换流量降低停机和回滚风险。模型网关可以组合这两种思想：对低风险流量使用 canary，对高风险主路径准备蓝绿或备用路由。关键不是套用术语，而是每个阶段都能停、能看、能退。
门禁还要避免被总量掩盖。假设全局错误率只上升 0.2%，看起来很小，但如果这个 0.2% 全部集中在一个高价值租户或一个生产应用上，就不应继续放量。指标面板要能按 app_id、tenant_id、env、route_id 和 error_class 下钻。全局指标用于看趋势，分组指标用于做决策。
门禁阈值不要只写固定数字，也要写相对基线。某些批处理任务本来延迟就高，某些交互式应用本来错误率极低。统一阈值会让低风险任务过度报警，也会让高风险路径的轻微退化被忽略。更好的方式是为每个 route_group 保存基线：过去一段时间的成功率、首包时间、超时率和业务反馈。灰度时比较候选版本与同类旧版本，而不是拿它和全站平均值比。
门禁还应包含人工信号。模型输出质量很难完全靠状态码判断，早期 canary 可以要求业务值班人员在固定时间窗口内确认样本。人工信号不需要替代指标，但能补足指标盲区。比如技术指标正常，客服人员却发现回答风格明显偏离；或者错误率没有上升，用户却更频繁地重新提问。这些都应成为暂停继续放量的理由。
七、观测字段要能区分退化来自哪里
图注：观测字段要区分调用方、网关策略、协议解析、上游和业务结果。
模型网关灰度中的退化可能来自多个层次。调用方可能传了新路由不支持的字段；网关策略可能误拒绝；协议适配器可能解析不了流式事件；上游可能限流或超时；模型输出可能在业务上不可接受；日志系统可能漏掉关键字段。观测字段如果只记录状态码，就无法区分这些层次。
建议把错误分类拆成五层。第一层是 caller_error，包括鉴权失败、权限不足、请求体不合法、租户不匹配。第二层是 gateway_policy_error，包括配额、路由禁用、灰度门禁、敏感数据规则和管理策略拒绝。第三层是 adapter_error，包括协议转换、流式解析、字段映射和响应归一化失败。第四层是 upstream_error，包括上游 429、5xx、连接失败和超时。第五层是 business_degradation，包括输出不符合业务验收、人工反馈变差和任务完成率下降。
OpenTelemetry 的 GenAI 属性给了记录生成式 AI 调用的方向，例如 provider、request model、response model、stream 标志等。使用这类语义约定时要注意版本和稳定性，也要注意敏感数据边界。遥测字段应帮助理解调用行为，而不是把完整提示词、完整响应和完整密钥复制到可观测系统。
一条灰度请求日志可以包含这些字段：trace_id、change_id、route_id、policy_version、app_id、env、tenant_id、targeting_key_hash、request_kind、stream_enabled、candidate_version、http_status、error_class、latency_ms、first_token_ms、chunk_count、retry_count、upstream_request_id、rollback_eligible。它们足以解释请求路径和失败层，不需要保存完整正文。
观测还要能对比基线。新路由的指标要和旧路由同类流量比较，而不是和全站平均比较。低风险内部工具的平均延迟不能作为客服主路径的基线，短请求的成功率也不能代表长上下文请求。灰度账本里要写清对照组是什么，否则"看起来差不多"很容易误导决策。
观测字段要有缺失告警。灰度期间如果 trace_id、route_id、policy_version 或 error_class 缺失，本身就是发布风险。缺字段意味着后续无法归因，即使请求暂时成功，也不应该继续扩大范围。很多团队只在业务错误时报警，却忽略了观测失明。对共享模型网关来说，观测失明应被视为暂停条件，因为它让后续失败不可解释。
还要限制高基数字段。把完整用户 ID、完整 prompt 哈希、动态错误文本或上游原始消息直接作为指标标签，会让可观测系统膨胀，也可能泄露敏感信息。更适合的做法是把高基数字段放入受控日志，把低基数字段用于指标标签，例如 error_class、route_group、env 和 app_id。这样既能聚合看趋势，也能在需要时通过 trace_id 下钻。
八、回滚不是改回旧 URL，而是恢复旧语义
图注：回滚要恢复路由、协议、策略和凭据引用，而不只是把地址改回去。
模型网关回滚最常见的误区，是把上游地址改回旧值就算完成。真实回滚要恢复旧语义：旧模型名映射、旧请求适配器、旧流式解析、旧错误分类、旧配额策略、旧凭据引用、旧日志字段和旧路由条件。只改 URL，可能仍然保留新协议、新重试、新采样或新鉴权规则，调用方仍然会失败。
因此每次变更都要有 rollback_version。这个版本不是一段口头说明，而是一组可加载配置。它至少包含 route_version、adapter_version、policy_version、credential_ref、quota_policy、timeout_policy、retry_policy 和 log_schema_version。回滚时系统加载上一组已知可用配置，并记录谁在什么时候执行了回滚，影响范围是什么，回滚后哪些指标恢复。
Kubernetes 的 kubectl rollout undo 支持回到之前的 rollout，Argo Rollouts 也把 canary 步骤做成可暂停、可继续的状态。这些机制背后的共同点是：系统知道历史版本，而不是让人凭记忆重建旧配置。模型网关也需要这个能力。没有版本化配置，回滚就是人工拼图。
回滚还要提前演练。演练不需要等事故，可以在低风险路由上定期做：切到候选版本，观察，暂停，回到旧版本，确认旧版本真正接管流量，确认 trace_id 能证明回滚后命中新 route_id，确认旧错误率恢复，确认日志没有断层。没有演练过的回滚方案，在事故中往往会变成新的变更。
还要区分"回滚到旧路由"和"回滚到安全降级"。如果新路由失败是因为候选模型退化，可以回到旧路由；如果旧路由的凭据已经泄露，不能回到旧凭据；如果旧协议存在安全漏洞，也不能恢复旧协议。回滚的目标是恢复业务安全状态，不是机械恢复所有旧值。
回滚后还要做确认，而不是执行完命令就结束。确认项包括：新请求是否命中旧版本，已进入候选路由的长连接或流式请求如何处理，失败队列是否仍在重放，调用方缓存是否需要刷新，管理端配置是否显示正确版本，审计日志是否记录回滚原因。特别是流式请求，回滚无法改变已经建立的连接，只能影响新请求。若需要中断已有连接，也要写进应急动作和用户影响说明。
回滚通知也要有层次。对调用方来说，最有价值的信息是影响范围、当前状态、是否需要重试、是否需要刷新配置、后续如何验证。对网关维护者来说，最有价值的是 rollback_version、执行人、指标恢复情况和遗留任务。不要只发一句"已回滚"。在多团队环境里，模糊通知会让调用方重复排查，甚至自行绕过网关。
九、防止灰度触发重试风暴
图注：灰度期间要限制客户端、网关和上游多层重试叠加。
灰度失败时，重试会把小问题放大。客户端看到超时会重试，网关看到上游失败会重试，队列任务会重新投递，上游 SDK 也可能有内置重试。原本 5% 的灰度流量，经过多层重试后可能变成更高的物理请求量，进而触发限流、排队和更多超时。于是团队以为新模型不稳定，实际上是重试策略把故障扩大了。
灰度计划里应写清重试边界。调用方可以对幂等、安全、短时失败做有限重试；网关应识别逻辑请求和物理尝试，限制每条逻辑请求的最大尝试次数；上游 429 应尊重 Retry-After 或内部等待策略；流式响应已经开始返回内容后，不要盲目重放同一业务请求；非幂等工具调用更不能自动重试。
日志里要同时记录 logical_request_id 和 attempt_id。前者表示用户或业务的一次意图，后者表示网关内部的物理尝试。这样才能解释为什么一次用户点击产生了三次上游调用，也能在配额账本里区分业务量和重试量。灰度看板应同时显示请求数、尝试数、重试率和重试原因。只看请求数，会低估上游压力。
当灰度触发异常时，优先动作通常是暂停放量和降低重试，而不是继续扩大样本。很多团队为了"再观察一下"继续放量，结果让上游保护策略和客户端超时同时触发。更稳妥的是先固定流量范围，关闭非必要自动重试，保留证据，再判断是协议问题、路由问题、上游问题还是业务效果问题。
重试保护也要纳入回滚验证。回滚后不应只看错误率下降，还要看重试率和队列积压是否恢复。如果回滚只让新请求走旧路由，但旧的失败任务仍在队列里反复重放，系统仍可能持续承压。灰度账本里要记录是否清理、暂停或重新调度了失败积压。
灰度期间还可以给候选路由设置单独的重试预算。比如候选版本每分钟最多消耗多少额外尝试，超过预算就自动暂停，而不是继续把失败请求压向上游。重试预算与流量比例不同：流量比例控制进入候选路由的逻辑请求，重试预算控制候选路由失败后的放大倍数。两者缺一不可。
对于流式响应，重试策略尤其要谨慎。用户已经看到部分输出后，重新发起同一请求可能产生重复、矛盾或上下文错乱。网关可以把"首包前失败"和"首包后失败"分开处理：首包前失败可以有限重试，首包后失败更适合返回可恢复错误和 trace_id，让客户端决定是否重新发起新任务。这个边界如果不写清楚，灰度中的流式中断会制造大量难以复现的用户问题。
十、发布前检查清单：能看、能停、能退
图注：上线前不只验通请求，还要验身份、路由、观测、暂停和回滚。
统一模型网关发布前，不要只做一条 curl。能通只能证明某个请求在某个时刻通过了网络和鉴权，不能证明灰度可控。发布前检查可以分成六组。
第一组是身份和范围。确认 affected_apps、affected_tenants、affected_envs 已列出，确认高风险调用方是否被排除，确认灰度主体使用稳定 targeting key。第二组是协议和适配器。确认非流式、流式、错误响应、工具调用和超时路径都被最小样本验证，确认客户端能解析候选路由返回。第三组是路由和凭据。确认 route_id、upstream_id、credential_ref 都有版本，确认候选路由不会使用错误环境的凭据。
第四组是观测和门禁。确认 trace_id、change_id、route_id、policy_version、error_class、latency_ms、chunk_count、retry_count 等字段可查，确认看板能按应用、租户、环境和路由下钻。第五组是暂停和回滚。确认每个放量台阶都有暂停条件，确认 rollback_version 可加载，确认回滚操作有权限边界和审计记录。第六组是安全和隐私。确认日志、截图、告警和工单不会包含完整 API Key、完整 Authorization 头、完整提示词和完整响应正文。
可以把检查结果写成机器可读文件，随变更单保存。例如：
{
"change_id": "gw-2026-07-10-canary",
"route_version": "route-v2",
"rollback_version": "route-v1",
"shadow_validation_passed": true,
"streaming_contract_checked": true,
"redaction_checked": true,
"pause_condition_defined": true
}
这样的文件不能替代人工判断，但它能避免遗漏。复盘时也能看到当时到底检查了什么，而不是只剩"发布前已确认"。
发布前还要做失败路径测试。故意构造无权限主体、错误租户、候选路由超时、上游 429、流式中断、审计写入失败和回滚版本不存在等情况。每个失败都要验证三件事：请求是否被正确拒绝，日志是否保留足够证据，错误响应是否没有泄露敏感字段。灰度系统如果只在成功路径上漂亮，事故时仍然不可用。
检查清单还应要求"截图可脱敏"。实际发布中，很多证据会被贴到工单、群聊或复盘文档里。看板如果默认显示完整请求头、完整租户名称、完整用户输入或上游错误原文，就会让排错材料变成敏感材料。发布前应确认常用看板和导出报表默认展示的是引用、摘要和分类，而不是秘密本身。证据越容易共享，越要提前脱敏。
发布窗口也要选得合理。模型网关影响面广，不适合在业务高峰或值班力量不足时做大范围切换。早期 canary 可以在低峰进行，但也要覆盖真实调用，而不是只在完全无流量时验证。每个放量台阶都应有观察时间，不能为了赶进度连续点击下一步。灰度的价值来自观察，不是来自仪式。
十一、落地路线：从路由表走向发布系统
图注：先做版本和账本，再做染色、门禁、观测和自动化回滚。
如果团队现在只有一张简单路由表，可以按四个阶段演进，不必一次性做成复杂平台。
第一阶段，给路由加版本。每次修改 route_id、上游地址、模型名映射、凭据引用和策略，都保存 old_version 与 new_version。请求日志里写入命中的 route_version。这个阶段的目标是能回答"某个时间点到底用的是哪一版配置"。
第二阶段，给流量加染色。要求调用方带上 app_id、env、tenant_id 和稳定主体标识。先不急着做复杂规则，至少能按环境、应用和租户分批切流。这个阶段的目标是避免全局随机百分比，让灰度范围可以被解释。
第三阶段，给发布加门禁。影子验证、协议验收、观测字段、暂停条件、负责人和 rollback_version 都写进变更单。放量从人工改配置变成按台阶推进。这个阶段的目标是让继续放量、暂停和回滚都有依据。
第四阶段，给回滚加自动化。系统能一键加载上一个已知可用版本，能自动记录审计，能把失败指标和回滚动作关联起来。对于明显越界的指标，可以自动暂停继续放量；对于高风险主路径，仍保留人工确认。这个阶段的目标不是完全无人值守，而是减少事故中依赖手工拼配置。
整个路线里最重要的原则是：模型网关的发布能力要比单个业务服务更保守。因为它一旦出错，影响的是多个团队的共同入口。灰度不是为了让改动更快推到 100%，而是让每一步都有证据、有边界、有停止点。百分比只是工具，账本、观测和回滚才是安全感的来源。
最后，把模型网关当成生产发布系统来管理，而不是当成一张可随手编辑的代理配置表。每次切模型、切上游、改协议、改配额、改日志，都应该能留下变更原因、影响范围、验证结果和回滚版本。做到了这一点，团队才有资格说自己的灰度是工程能力，而不是一次慢一点的冒险。
路线落地后，还要定期做复盘抽样。随机挑选几次网关变更，检查变更账本是否完整、灰度门禁是否真的执行、暂停条件是否被触发过、回滚版本是否仍可加载、观测字段是否仍在日志里。没有抽样，流程会慢慢退化成填表。抽样不是为了找人背锅，而是为了确认发布系统仍然可信。
更进一步，可以把历史灰度结果反哺到策略模板里。哪些调用方适合早期 canary，哪些指标最早发现退化，哪些错误分类经常误判，哪些回滚动作最耗时，都可以沉淀成下一次变更的默认值。这样模型网关的发布能力会随着每次变更变强，而不是每次都从头依赖个人经验。
参考资料
- Kubernetes Documentation：Deployments，https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
- Kubernetes Documentation：kubectl rollout undo，https://kubernetes.io/docs/reference/kubectl/generated/kubectl_rollout/kubectl_rollout_undo/
- Argo Rollouts Documentation：Canary Deployment Strategy，https://argo-rollouts.readthedocs.io/en/stable/features/canary/
- Argo Rollouts Documentation：Traffic Management Tools in Kubernetes，https://argo-rollouts.readthedocs.io/en/stable/features/traffic-management/
- AWS Documentation：Canary deployments，https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/canary-deployments.html
- AWS Documentation：Blue/Green Deployments on AWS，https://docs.aws.amazon.com/whitepapers/latest/blue-green-deployments/welcome.html
- OpenFeature Specification：Evaluation Context，https://openfeature.dev/specification/sections/evaluation-context/
- OpenAI Developers：Streaming API responses，https://developers.openai.com/api/docs/guides/streaming-responses
- OpenAI API Reference：Chat Completions streaming events，https://developers.openai.com/api/reference/resources/chat/subresources/completions/streaming-events
- OpenTelemetry Documentation：Gen AI，https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/