Reliability and Routing2026年6月22日Big Y

LLM API 网关的熔断器：保护应用免受提供商故障循环影响

使用 LLM API 网关熔断器来阻止提供商故障循环、分类错误、保护重试，并路由到备用、队列或失败关闭。

一个LLM API gateway circuit breaker会阻止应用反复把流量发送到一个已经在失败的路由中。没有这个保护，超时会触发重试，重试会触发回退尝试，回退尝试会触发更多提供商错误，应用就可能把一次上游故障变成一个提供商失败循环。

目标不是取代重试或模型回退。目标是判断某条路由何时已经不健康到应由网关在一小段时间内停止继续尝试，稍后发送一次受控探测，并在断路器打开时选择更安全的结果：回退、排队、降级或关闭失败。

Flatkey之所以相关，是因为flatkey.ai公开将该产品定位于单一 API key、OpenAI 兼容的基础 URL https://router.flatkey.ai/v1、路由、统一计费、使用分析、仪表板控制、自动切换、负载均衡和配额限制。这些都是可靠性工作的有用中心点。它们并不能消除为你自己的应用工作流定义清晰的LLM API gateway circuit breaker策略的需要。

LLM API 网关断路器应该做什么：快速回答

一个实用的 LLM API 网关断路器 具有三种路由状态和一条 fail-closed 路径。应保持策略足够简单，以便值班工程师在事故期间能够解释清楚。

状态	网关行为	触发变化的条件	需要记录的证据
关闭	流量可以使用该提供商、模型、端点族、账户或路由组。	错误率、超时率、延迟、过载响应或失败的健康检查探针超过阈值。	路由策略 ID、所选模型、提供商、端点族、延迟、状态码、重试次数和成本。
打开	网关会在一个冷却窗口内停止向不健康的路由发送正常流量。	冷却时间到期，或运维人员手动允许一次探测。	断路原因、打开时间、被阻止的尝试次数、回退路由、排队决策或 fail-closed 原因。
半开	网关在恢复流量之前允许有限数量的探测请求。	探测成功则关闭断路器；探测失败则再次打开。	探测样本量、探测工作流、探测结果、延迟、使用量和路由负责人批准。
fail closed	由于问题并非提供商健康问题，网关拒绝为该请求路由。	身份验证、策略、配额、安全、数据边界、无效请求或工具副作用风险。	停止原因、负责人、用户可见消息和修复路径。

为什么重试会造成提供方故障循环

当请求因暂时性原因失败时，重试是有用的。但当每个用户请求都会触发更多上游调用时，重试就变得危险了，尤其是在提供方故障或过载期间。重试循环会消耗速率限制、消耗配额、增加延迟，并且会把原始故障隐藏在最终错误之后。

断路器改变了重试问题的问法。网关不再问“这个单个请求是否应该再次重试？”，而是问“这条路由现在是否足够健康，可以接收更多流量？”。这种路由级视角对 LLM 工作负载很重要，因为每个请求都可能成本高、运行时间长、需要流式传输、使用工具，并且对客户可见。

微软关于断路器的云设计模式对远程服务描述了同样的核心思想：在连续失败后，电路打开，这样应用就不会继续尝试一个很可能失败的操作。对于 AI 路由，同样的模式需要 LLM 特定的边界：模型行为、端点族、token 消耗、流式状态、工具副作用、数据类别以及降级审批。

在错误到达断路器之前对其分类

构建一个糟糕的AI API 断路器最快的方法，就是把每一次失败都算作提供商健康状况问题。这样会产生误报，也可能掩盖应用所有者必须修复的问题。

错误或事件	断路器决策	原因	默认结果
提供商 500、503、过载、不可用、连接失败、重复的上游超时	计入路由健康状况。	这些是合理的提供商、路由、容量或网络健康信号。	在严格预算内重试，然后在超过阈值时打开路由断路器。
429 请求速率限制	谨慎分类。	提供商全局过载信号与应用创建的突发流量需要不同处理。	限流、退避，或者只打开实际已饱和的特定路由。
429 月度配额、信用额度耗尽或支出限额	不要计入提供商健康状况。	这是预算或账户所有者条件。	关闭失败，通知预算所有者，或者仅在存在预先批准的预算时才路由。
401 身份验证、密钥错误、组织成员资格、IP 白名单、不支持的区域	不要计入提供商健康状况。	该请求不被允许使用该路由。	关闭失败并修复凭据、账户、IP 或区域策略。
无效请求、不支持的参数、不支持的模型、格式错误的 schema	不要计入提供商健康状况。	应用发送了该路由无法处理的请求形状。	在路由前修复请求或选择兼容的模型。
安全、审核、DLP、合规或未经批准的数据分类阻断	绝不要用回退绕过。	路由到另一个模型可能会跨越策略边界。	关闭失败并记录该策略决定。
工具已执行、部分流已显示、用户已取消请求	不要静默重放。	应用可能会产生重复副作用或合并两个模型输出。	标记为不完整，要求用户明确重试，或使用幂等恢复路径。

OpenAI 的错误代码指南很好地说明了为什么这种分类法很重要：它区分了身份验证和 IP 白名单问题、不支持的区域问题、速率限制、配额耗尽、服务器错误、过载以及突发的请求速率放缓。Anthropic 和 Google Gemini 文档也对速率限制、过载/不可用条件、无效请求以及权限或配额问题作了类似区分。你的LLM API 网关断路器应在打开路由之前将这些类别分开。

将断路器限定到能解释故障的最小路由范围

过于宽泛的断路器会导致不必要的停机。过于狭窄的断路器则会让同一提供商故障循环继续影响附近路径。应将断路器限定到能解释该事件的最小路由维度。

范围	何时使用	范围设定错误的风险
提供商	来自同一提供商的多个模型不可用或过载。	如果只有一个模型、账户或端点系列出问题，则范围过于宽泛。
模型	某个模型系列反复出现 5xx、超时或不支持路由错误。	如果上游账户或提供商已饱和，则范围过于狭窄。
端点系列	Chat 正常，但 Responses、image、video、Anthropic Messages 或 Gemini 路由表现不同。	混合端点系列可能掩盖协议特定故障。
账户、组、区域或供应商路径	只有一个上游账户、路由组、区域或供应商路径失败。	未能隔离可能会消耗其他地方的健康容量。
工作流	工具调用、流式传输、批处理作业或面向客户的聊天具有不同的安全和重放规则。	对批量增强安全的路由，可能不适用于实时用户流。

对于 Flatkey 用户，这意味着你应当从你实际计划使用的工作流和路由进行测试。本文所用的当前 Flatkey 定价 API 快照返回了 638 行模型数据、23 家供应商，以及 OpenAI chat completions、OpenAI Responses、Anthropic messages、Gemini generateContent、图像生成和 OpenAI video 的端点系列。应将其视为截至 2026 年 6 月 18 日的过时证据，而不是永久的路由契约。

设置与 LLM 流量相匹配的阈值

LLM API gateway circuit breaker 不应因为一次孤立故障就打开。它也不应一直等到每个客户请求都失败才动作。请使用结合最小流量、失败率、延迟和冷却时间的阈值。

Threshold	Practical Starting Point	Why It Matters
Minimum sample size	仅在观察到足够多的请求或探测后才打开。	防止一次昂贵的 completion 打开全局路由。
Failure ratio	将可重试的上游失败与应用自身的失败分开跟踪。	阻止认证、配额和格式错误请求错误污染路由健康状态。
Latency or timeout threshold	为 chat、streaming、image 和 video 路径使用端点特定的超时预算。	适用于 chat 的良好阈值，可能并不适用于 video 或批量生成。
Open cooldown	让路由保持打开足够长的时间，以停止重试风暴，然后再进行探测。	同时保护提供方和你自己的请求队列。
Half-open probe limit	在关闭前允许少量、受控的测试请求。	当提供方只部分恢复时，可防止流量突然全面涌入。
Cost ceiling	为重试、fallback 和探测设置最大预估支出。	防止可靠性恢复演变成计费事故。

速率限制也是阈值讨论的一部分。OpenAI's rate-limit guide 解释了速率限制如何防止滥用、确保公平访问，并帮助管理整体负载。如果你的应用不断对受限路由进行重试，你自己的流量模式就可能成为事故。LLM API gateway circuit breaker 应当与客户端节流、排队和配额控制协同工作，而不是与之对抗。

决定断路器打开时会发生什么

打开断路器只有在网关有明确的后续动作时才有意义。不要让每条打开的路由都自动回退到任何可用模型。

打开状态动作	适用场景	所需护栏
回退路由	备用模型或提供商已经获批用于该工作流。	在生产前运行相同的评估、模式、工具、数据边界和成本检查。
排队	任务是异步的，或者用户体验可以容忍延迟。	保留负责人、客户、模型、成本和重试元数据。
降级	可接受较低风险的部分结果，例如缓存响应或减少的功能。	让应用和日志都能看到降级状态。
关闭失败	请求存在策略、预算、安全、认证、区域或副作用风险。	返回清晰的错误，并提醒正确的负责人，而不是尝试另一个模型。

公开的 Vercel AI Gateway 文档将模型回退描述为一种网关模式，包含有序的备用模型。这里只把它作为类别证据。对于你自己的技术栈，回退是一个独立的审批决策。断路器决定某条路由当前是否健康；回退决定是否允许另一条路由为同一请求提供服务。

流式输出和工具调用需要额外停止点

流式输出会让供应商故障循环更容易被掩盖。如果应用在部分输出后悄悄重启请求，用户可能会看到由两次尝试合并而成的答案。工具调用带来第二个问题：重试或回退可能会重复执行退款、工单更新、邮件发送、数据库写入或其他外部操作。

在 LLM API gateway circuit breaker 策略中使用以下规则：

首次输出之前： 如果路由已获批准，且断路器处于关闭或半开状态，则可以允许重试或回退。
首次输出之后： 将流标记为不完整，并要求用户显式重试，而不是静默回退。
工具执行之后： 除非工具是幂等的且操作带有重放键，否则不要重放。
策略阻止之后： 失败即关闭。不要通过路由到其他模型来绕过阻止。

这与 AI API retry strategy、model fallback checklist 和 AI API load balancing and failover 指南相配合。断路器应与这些操作手册共享相同的故障分类体系。

熔断器审查的可观测性字段

如果某个请求之所以成功，仅仅因为网关静默地跳过了一个损坏的路由，那么这起事故仍然需要被看见。Cloudflare 的 AI Gateway 文档提供了一个 AI 网关可观测性模式的公开示例：请求日志可以包含提供商、状态、令牌、成本和持续时间，而自定义元数据可以为请求打标签，以便后续筛选。你的网关日志应为熔断器决策提供同等级别的路由证据。

字段	运维人员为什么需要它
熔断策略 ID 和版本	显示是哪条规则打开、关闭或绕过了该路由。
决策时的熔断状态	说明路由是关闭、打开、半开，还是故障关闭。
请求的模型、选定的模型、提供商、账户、组和端点族	将用户意图与网关路由决策区分开来。
每次尝试的错误类别	区分上游故障、认证、配额、无效请求、策略和工具错误。
延迟、超时、重试次数和探测结果	显示路由是缓慢失败、快速失败，还是在半开探测期间恢复。
部分输出标志和工具副作用状态	防止隐藏的混合输出或重复操作事件。
用量、成本、配额所有者和最终处置	将可靠性恢复与支出、预算和责任关联起来。

配套的AI API 可观测性日志文章更深入地讨论了事件日志记录。对于熔断器，应优先记录路由状态，以及请求被阻止、被探测、被路由、排队或故障关闭的确切原因。

针对断路器策略的 Flatkey 上线计划

在通过 Flatkey 或任何兼容 OpenAI 的网关将流量用于客户请求之前，请先采用这种分阶段方法，再依赖 LLM API 网关断路器。

创建预发布密钥：将断路器测试与生产客户流量分开。
确认基础路由：让兼容 OpenAI 的客户端指向 https://router.flatkey.ai/v1，并验证模型、端点系列、用量行以及仪表板可见性。
保存路由目录快照：在上线日期保存 Flatkey 定价页面和定价 API 响应，以便对路由和定价假设进行审计。
定义错误分类法：决定哪些错误计入路由健康状态，哪些在断路器看到之前就直接失败关闭。
从一个工作流开始：先将断路器应用于一个模型路由、一个端点系列和一种流量类别，再逐步扩展。
强制失败测试：模拟提供商超时、500、503、请求速率 429、配额耗尽、身份验证失败、格式错误的请求、部分流以及工具副作用。
验证开启状态行为：确认回退、排队、降级或失败关闭操作与审批矩阵一致。
检查日志和计费：确认每次测试后都能看到断路器状态、所选路由、用量、成本和配额所有者。
设置回滚：如果策略开放范围过大、隐藏了应用自有错误或导致非预期支出，则禁用该策略。

断路器策略模板

此模板不是 Flatkey API 合同。请将其视为工程、产品、财务和安全负责人用于审查的产物。

{
  "policy_id": "support-chat-provider-breaker-v1",
  "workflow": "customer-support-chat",
  "environment": "production",
  "route_scope": {
    "provider": "primary-provider",
    "model": "primary-approved-model",
    "endpoint_family": "openai-chat-completions",
    "traffic_class": "customer-visible-stream"
  },
  "count_toward_breaker": [
    "upstream_5xx",
    "provider_overloaded",
    "provider_unavailable",
    "upstream_timeout",
    "connection_reset"
  ],
  "fail_closed_before_breaker": [
    "auth_error",
    "ip_allowlist_error",
    "unsupported_region",
    "quota_exhausted",
    "invalid_request",
    "schema_incompatible",
    "safety_or_policy_block",
    "unapproved_data_class",
    "tool_side_effect_already_committed"
  ],
  "thresholds": {
    "window_seconds": 60,
    "minimum_requests": 20,
    "failure_ratio_to_open": 0.5,
    "timeout_ratio_to_open": 0.4,
    "open_cooldown_seconds": 90,
    "half_open_probe_requests": 3,
    "max_total_attempts_per_request": 2
  },
  "open_state_action": {
    "default": "fail_closed",
    "allowed_fallback_policy_ids": [
      "support-chat-fallback-v1"
    ],
    "allow_after_partial_output": false,
    "allow_after_tool_side_effect": false
  },
  "logging": {
    "record_breaker_state": true,
    "record_route_scope": true,
    "record_error_class_per_attempt": true,
    "record_probe_results": true,
    "record_usage_cost_and_quota_owner": true
  }
}