LLM 路由器金丝雀发布是一种受控方式，用于迁移模型流量，而不会把一次迁移变成生产事故。它不是一次性把所有请求从现有路由切换到新模型、供应商或网关策略，而是先发送一小部分流量，将候选路径与稳定路径进行对比，并且只在证据足够可靠时才推进。
对于 AI API 来说，这一点比许多普通 Web 端点更重要。新的模型路由可能同时改变延迟、错误类型、token 使用量、拒绝行为、输出格式、每个被接受答案的成本，以及支持工作量。仅仅返回一个正常的 200 响应还不够。该路由必须在保持产品质量、计费和事故复盘完整的同时运行。
Flatkey 的公开站点将 flatkey.ai 定位为官方 GPT、Claude 和 Gemini 流量的单一密钥，并提供位于 https://router.flatkey.ai/v1 的 OpenAI 兼容基础 URL、模型健康上下文，以及用于查看使用量、成本、路由和错误的仪表盘。可以将这些控制作为验证循环的一部分，但不要因为基础 URL 已经平稳切换，就默认金丝雀是安全的。更稳妥的做法，是把 LLM 路由器金丝雀发布视为一份运行手册，其中包含阶段、通过指标、停止条件以及回滚负责人。
LLM 路由器金丝雀发布应该验证什么
金丝雀不只是“把 5% 的流量发到新模型”。官方发布系统会以不同方式使用同样的模式。Argo Rollouts 用 setWeight 和 pause 来建模金丝雀步骤。Istio 演示了从旧服务版本到新服务版本的加权流量迁移。AWS API Gateway 可以将配置好的百分比 API 流量拆分到金丝雀发布中，而 SageMaker 的金丝雀流量切换使用带有告警和回滚的 bake period。KServe 也将同样的思路应用于推理服务，通过将一定比例的流量路由到新版本来实现。
对于 LLM 路由器金丝雀发布，可以借用渐进式交付模式，再增加 AI 特有的验证。金丝雀应该证明：
- 兼容性：候选路径接受与稳定路径相同的请求结构、流式模式、工具 schema、响应解析器和超时预算。
- 可靠性：错误类别、重试量、超时率和回退尝试不会超过你的停止条件。
- 质量：输出通过产品特定的评估或审查检查，而不仅仅是传输层面的成功。
- 成本控制：token 使用量、缓存 token 行为、多模态单元、重试以及每个被接受输出的成本都保持在约定范围内。
- 可观测性：每个金丝雀请求都可以按路由、模型、密钥、环境、请求 ID、状态、延迟、用量和成本进行追踪。
- 回滚：团队可以快速将流量返回稳定路由，并且不会留下 schema 迁移或计费疑云。
从路由记录开始，而不是从切换开始
在 LLM 路由器金丝雀发布中，第一个错误是把路由当成一个配置值。应在第一个真实请求到来之前先写好路由记录。它应该对平台工程、产品、财务和支持团队都可读。
| 字段 | 记录内容 | 重要原因 |
|---|---|---|
| 稳定路由 | 当前供应商、模型、端点族、版本、超时、重试策略和回退 | 定义金丝雀必须超越或匹配的基线 |
| 候选路由 | 新模型行、网关路由、策略、密钥作用域、端点和能力标志 | 避免“我们同时改了好几样东西”掩盖根因 |
| 流量类别 | 内部、预发布、Beta、低风险生产、批处理、高价值客户或全部流量 | 限制影响范围，并让支持团队形成正确预期 |
| 成功窗口 | 最小请求数、烘焙时间、代表性工作流和时区覆盖 | 避免把安静时段误判为健康发布 |
| 负责人 | 审批人、发布人、指标审查人、回滚负责人、财务审查人、支持联系人 | 当证据发生变化时，可快速推进或回滚 |
如果新路由同时更改了模型和提示词，就把金丝雀拆开。先用现有提示词和解析器验证路由。然后再测试提示词或评估变更。清晰的 LLM 路由器金丝雀发布会隔离足够多的变量，从而让失败阶段指向可修复的原因。
模型流量的实用金丝雀阶梯
合适的百分比取决于流量规模和风险。面向消费者的聊天应用、内部代理、发票工作流、代码助手和视频生成流水线，并不适合使用相同的阶梯。以下阶段可作为默认值，并根据你的实际流量调整请求最低数量。
| 阶段 | 流量 | 适用对象 | 晋升门槛 | 回滚触发条件 |
|---|---|---|---|---|
| 0. 影子模式或回放 | 0% 用户不可见 | 记录的提示词、合成测试、内部评估集 | 请求形态、解析器和评估框架通过 | Schema 不匹配、缺少使用记录、不安全的输出类别 |
| 1. 内部金丝雀 | 1% | 内部用户、预发布环境或受信任的 Beta 流量 | 无严重错误；请求 ID 和路由标签可见 | 任何 Sev-1 路径、认证失败、缺少计费追踪 |
| 2. 低风险生产流量 | 5% | 低风险工作流或非企业流量 | 延迟、错误率、成本和质量均在阈值内 | 在 bake 窗口内错误率或超时率超过阈值 |
| 3. 代表性切片 | 10-25% | 覆盖正常生产分段的均衡路由 | 支持工单、回退率和被接受输出率保持稳定 | 重试循环、回退风暴、格式破坏、成本激增 |
| 4. 大多数流量 | 50% | 广泛生产流量，仍可回滚 | 通过两个 bake 窗口，若可能包括峰值流量 | p95 延迟、成本、质量或客户影响出现回归 |
| 5. 全量晋升 | 100% | 所有预期流量 | 保留稳定路由作为回滚路径，直到上线后审查完成 | 任何与候选路由相关的晋升后事故 |
在各阶段之间暂停。Argo 的金丝雀文档明确建模了暂停，而 SageMaker 描述了由告警监控的 baking 周期。正是在这段暂停期，LLM 路由器金丝雀发布体现其价值。目标不是快速达到 100%。目标是在受影响的流量切片仍然很小时发现问题。
晋升前需要比较的指标
OpenAI 的 API 概览建议在生产环境记录请求 ID，并指向响应头中的请求 ID 和速率限制详情。OpenTelemetry 将指标描述为通过计数器和直方图等仪器捕获的运行时测量，而直方图适用于请求延迟。在模型金丝雀中，使用这些思路在同一时间窗口内比较稳定路由和候选路由。
| 指标组 | 稳定路由与候选路由的比较 | 晋升问题 |
|---|---|---|
| 传输 | HTTP 状态、提供方错误类别、超时率、速率限制响应、重试次数 | 候选路由失败次数更少，或者至少没有更多吗？ |
| 延迟 | p50、p95、p99、首个 token 时间、完整完成时间、排队时间 | 产品在峰值流量下能否承受候选路由？ |
| 输出质量 | 评估通过率、解析器成功率、幻觉审查、拒绝率、工具调用有效性 | 被接受的输出是否与稳定路由一样有用？ |
| 成本 | 输入 token、输出 token、缓存 token、多模态单元、重试成本、每个被接受答案的成本 | 候选路由是否更便宜、更好，或者至少在预算内？ |
| 运维 | 回退尝试、熔断器触发、队列深度、支持工单、事故提及 | 值班的运维团队会信任这条路由吗？ |
| 可审计性 | 请求 ID、客户端追踪 ID、密钥标签、用户/工作区标签、模型、路由、成本、最终状态 | 工程、财务和支持团队之后能否审查同一请求？ |
不要仅凭汇总成功率就晋升 LLM 路由器金丝雀发布。候选路由在总请求上看起来没问题，但可能在某个工作流、某个客户层级、某个地区、某个长上下文提示词或某条工具调用路径上失败。在提高百分比之前，先按流量类别对比进行分段。
停止条件与回滚触发器
停止条件应在发布前写好。如果团队在仪表盘变红时才讨论回滚，那么金丝雀方案就是不完整的。
| 信号 | 停止条件 | 回滚操作 |
|---|---|---|
| 错误率 | 候选路由在回灌窗口内以约定的幅度超过稳定路由 | 将候选流量设为 0%，保留日志，并创建路由缺陷 |
| 延迟 | p95 或首个 token 输出时间突破该金丝雀切片的产品 SLO | 将流量返回稳定路由，并保留候选路由以供离线回放 |
| 质量 | 评测通过率或人工审核分数低于最低可接受分数 | 停止晋升；在下一次金丝雀之前修复提示词、模型或解析器 |
| 成本 | 每个已接受输出的成本超出预算，或 token 增长无法解释 | 回滚或仅将候选路由限制为低成本流量 |
| 回退循环 | 候选路由导致重复重试、回退尝试或队列增长 | 禁用到候选路由的回退，并恢复稳定路由策略 |
| 证据缺失 | 请求 ID、用量行、成本字段或关键标签缺失 | 即使响应看起来健康，也暂停发布 |
回滚并不是 LLM 路由器金丝雀发布 的失败。它正是你选择金丝雀而不是大规模切换的原因。在晋升后的窗口期结束之前，保持稳定路由处于配置状态，然后有计划地将其退役。
如何通过 Flatkey 运行金丝雀
Flatkey 在这个工作流中很有用，因为其公开站点为团队提供一个与 OpenAI 兼容的路由器基础 URL、一个密钥路径、模型健康上下文，以及用于用量、成本、路由和错误的仪表板审查。定价页面还说明，一个余额可以通过一个与 OpenAI 兼容的网关路由到 GPT、Claude、Gemini、DeepSeek、图像、音频和视频模型，使用量按模型、token 类型和请求日志计量。
这并不意味着每个账号都具有相同的路由标签、导出字段、配额控制、模型可用性或金丝雀自动化。在依赖之前，请先在你自己的账号中验证当前仪表板。一个安全的 Flatkey LLM 路由器金丝雀发布 看起来是这样的：
- 确认模型行：打开 Flatkey 定价，并验证你计划测试的当前模型、提供商、模态、价格单位和状态。
- 保持基础 URL 稳定：将你的 OpenAI 兼容客户端指向
https://router.flatkey.ai/v1，然后在金丝雀后面更改模型路由或策略，而不是一次性重写所有 SDK。 - 先运行迁移检查：使用 AI API 基础 URL 迁移测试，在生产流量迁移之前验证认证、端点、流式传输、超时、解析器和用量可见性。
- 定义路由策略：将金丝雀与 模型路由策略设计 模式配对，使候选路由、回退路径、负责人和停止条件都明确。
- 按故障类别监控：使用 OpenAI 兼容 API 故障排查、超时策略 和 速率限制处理 指南，将提供商错误、应用错误、预算限制和重试循环区分开来。
- 只根据证据晋升：按路由、模型、状态、延迟、token 用量、成本、回退次数和已接受输出率对比稳定流量与候选流量。
- 保持回滚简单：将候选流量改回 0%，保持旧路由预热，并准确记录哪些请求 ID 证明了回滚生效。
模板：LLM 路由器金丝雀发布运行手册
在迁移流量之前使用此模板。将示例值替换为你当前的路由名称和阈值。
LLM 路由器金丝雀发布记录
变更负责人：
稳定路由：
候选路由：
流量类别：
开始时间：
阶段梯度：0%、1%、5%、10%、25%、50%、100%
每个阶段的回灌窗口：
每个阶段的最少请求数：
所需证据
- 认证和端点冒烟测试通过：
- 解析器和输出模式通过：
- 已测试流式或非流式模式：
- 请求 ID 和客户端 trace ID 可见：
- 用量、token 和成本记录可见：
- 已审查超时和重试行为：
- 已测试回退路径：
- 产品评测通过率：
晋升门槛
- 错误率阈值：
- p95 延迟阈值：
- 每个已接受输出的成本阈值：
- 评测或人工审核阈值：
- 支持工单阈值：
回滚
- 谁可以回滚：
- 将候选路由设为 0% 的命令或配置：
- 如何验证稳定路由已恢复：
- 谁会收到事故说明：
该记录将 LLM 路由器金丝雀发布 变成可重复的变更，而不是一次性的迁移。把它放在部署工单旁边，不要埋在聊天线程里。
常见错误
- 跳过 0% 阶段：重放和影子测试会在用户看到之前发现 schema、解析器和评估失败。
- 仅以 HTTP 200 作为晋升依据：即使传输成功率很高，AI 输出质量、成本和支持影响仍可能退化。
- 同时更改模型、提示词、解析器和超时：变量太多会使金丝雀结果难以解释。
- 忽略每个已接受输出的成本：一个更便宜的模型在重试、更长输出或回退循环之后，可能反而更贵。
- 忘记请求 ID：没有请求 ID 和路由标签，支持团队就无法将事故与金丝雀阶段关联起来。
- 过早移除稳定路由：在回滚前，始终保留可用的回滚路径，直到晋升后的复核通过。
常见问题
什么是 LLM 路由器金丝雀发布？
LLM 路由器金丝雀发布是一种分阶段发布方式，它将受控比例的模型流量从稳定路由发送到候选路由，然后在晋升前比较可靠性、延迟、质量、使用量、成本和支持影响。
模型路由金丝雀应该从多少流量开始？
先以 0% 的用户可见流量进行重放或影子检查，然后使用非常小的内部或低风险流量切片，例如 1% 或 5%。只有在 bake 窗口结束且候选路由满足预定义停止条件后，才继续增加。
AI API 金丝雀部署中最重要的指标是什么？
跟踪错误率、超时率、限流响应、p95 延迟、首 token 时间、评估通过率、解析器成功率、token 使用量、每个已接受输出的成本、回退尝试、请求 ID 和支持影响。具体阈值应在金丝雀开始前设定。
模型路由金丝雀什么时候应该回滚？
当候选路由超出错误、延迟、质量、成本、回退或可观测性阈值时，就应回滚。缺少使用量或请求追踪证据也是回滚原因，因为团队无法安全地调查生产行为。
Flatkey 能帮助 LLM 网关发布吗？
Flatkey 可以通过为团队提供一个 OpenAI 兼容的基础 URL、模型访问、使用量和成本审查以及仪表板可见性，来支持整个运行闭环。在将生产流量迁移之前，请先在你自己的账户中验证当前模型行、仪表板字段、路由标签和回滚行为。
100% 之前的最终复核
在完全晋升之前，请与工程、产品、支持和财务团队一起复核金丝雀记录。确认稳定路由仍然可用，候选路由已通过峰值或代表性流量，使用量和成本可见，并且已测试回滚。这就是 LLM 路由器金丝雀发布 的实际价值：模型流量之所以迁移，是因为证据清晰，而不是因为迁移日历说现在该迁移了。
获取 key：从 Flatkey 注册开始，在 Flatkey 定价中验证当前模型和价格详情，并在迁移生产模型流量之前运行金丝雀检查清单。
