AI API Gateway 架构：一个密钥、模型路由与故障转移

AI API 网关为应用提供一个稳定的端点，而该端点背后的基础设施可以使用多个模型、提供商、账户或区域。其价值并不仅仅是用一个密钥隐藏多个 API 密钥。真正有价值的是为每个请求创建一个受控的决策点。

这个决策点可以在流量到达模型提供商之前回答一些运维问题：

• 这个客户端是否被允许调用所请求的模型？
• 当前哪个上游最能满足请求的能力、延迟和成本要求？
• 该上游是否健康到足以接收更多流量？
• 这个请求是否可以安全重试？
• 哪个回退方案能够保持响应契约？
• 团队之后将如何解释路由、成本和失败？

本指南将这些职责映射到生产架构中。它还展示了单一 API 密钥在哪些地方有帮助、在哪些地方没有帮助，以及如何迁移 OpenAI 兼容客户端，而不让网关变成一个隐形的路由惊喜来源。

单次请求路径中的参考架构

一个实用的 AI 网关请求会经过五层：

1. 客户端契约：应用向一个稳定的基础 URL 发送经过身份验证的请求。
2. 准入控制：网关验证身份、配额、模型权限、负载限制和请求元数据。
3. 路由策略：策略引擎将请求的模型或能力转换为可用的上游目标。
4. 执行控制：健康状态、并发、超时、重试、回退和流式传输规则决定如何调用所选目标。
5. 遥测与计费：网关记录所选路由、响应状态、延迟、token 或媒体使用量，以及成本归属。

Application / agent
        |
        |  one API key + stable request schema
        v
AI API gateway
  ├─ authentication and tenant policy
  ├─ model alias and capability registry
  ├─ routing policy and budget rules
  ├─ health, timeout, retry, and fallback controls
  └─ logs, traces, usage, and cost attribution
        |
        ├────────> Provider or deployment A
        ├────────> Provider or deployment B
        └────────> Provider or deployment C

因此，网关既是控制平面，也是数据平面。控制平面存储策略、凭证、别名、配额和路由配置。数据平面处理实时请求、流式响应、重试和遥测。从概念上将这些职责分离，会让变更更安全：运维人员可以更新路由策略，而不必要求每个应用团队都发布新的客户端代码。

“一个密钥”应该意味着什么

“一个密钥”应当意味着一个面向应用的凭证契约，而不是所有人、所有服务和所有环境共用的一个凭证。

合理的设计会为生产、预发布、本地开发、CI 和独立工作负载分别签发网关凭证。每个密钥都应具有有限的范围、所有者、配额和撤销路径。然后，网关将提供商凭证保留在服务端，并将传入身份映射到其被允许使用的上游凭证。

这就建立了一个有用的安全边界：

网关密钥绝不应被视为降低密钥卫生要求的理由。应将其放在密钥管理器中，绝不要放在浏览器代码或公共仓库里，定期轮换，并按环境隔离。更深入的运维清单请参见AI 产品的安全 API 密钥管理。

模型别名将客户端契约与提供方分离

第一个路由抽象是模型别名。应用程序不会在各处硬编码某个特定提供方的模型标识符，而是请求一个稳定名称，例如：

support-fast
reasoning-high
code-review-default
image-generation-standard

每个别名背后的注册表定义了一份能力契约。文本别名可能会指定工具调用、结构化输出、最小上下文大小、流式支持以及获准的回退家族。图像或视频别名则需要不同的字段，例如可接受的输入类型、输出尺寸、异步任务行为以及安全约束。

别名不应承诺每个候选模型都表现完全一致。它应定义应用程序可以依赖的最低行为。

alias: support-fast
contract:
  modality: text
  streaming: true
  tools: optional
  structured_output: required
  maximum_latency_ms: 3500
routes:
  - target: provider-a/model-fast
    priority: 1
  - target: provider-b/model-balanced
    priority: 2

这种间接层正是稳定基础 URL 的价值所在。应用程序与别名契约集成；平台所有者可以在评估、提供方故障、价格变动或区域要求之后更改目标集合。

路由决策应当是显式的

生产环境中的路由通常结合硬性过滤和软性排序。

1. 应用硬性可用性过滤

移除任何无法满足请求的目标。常见过滤条件包括：

• 所需的模态和输入类型
• 上下文窗口或输出大小要求
• 工具调用或结构化输出支持
• 数据驻留或区域可用性
• 租户或项目允许名单
• 安全或合规策略
• 当前配额、速率限制或并发状态
• 流式兼容性

任何不满足硬性要求的目标都不应仅仅因为更便宜而胜出。

2. 对符合条件的目标排序

过滤之后，对剩余路由进行评分。简单的策略可能比不透明的优化器更易于运维：

route score =
  质量权重 × 评估分数
  - 延迟权重 × 预测延迟
  - 成本权重 × 估算成本
  - 风险权重 × 最近错误率

这些权重应因工作负载而异。交互式聊天可能更看重首个 token 的生成时间。夜间抽取作业可能更看重每条成功的结构化记录成本。编码代理可能比微小的价格差异更重视工具可靠性和长上下文行为。

3. 记录原因

每个路由决策都应生成机器可读的元数据，例如：

{
  "requested_alias": "support-fast",
  "selected_target": "provider-a/model-fast",
  "policy_version": "support-fast-2026-07-29.3",
  "selection_reason": "healthy_primary_within_latency_budget",
  "fallback_count": 0
}

如果团队无法重建路由为何被选中，就无法调试成本漂移、质量回归或提供方事故。

健康检查需要的不只是 HTTP 200

上游服务可以返回成功的健康探测，但在真实模型流量上却失败。因此，AI 网关的健康状态需要多个信号：

• 传输健康： 连接失败、TLS 错误、DNS 错误以及上游超时
• API 健康： 限流响应、身份验证失败、提供方错误和格式错误的响应
• 模型健康： 空输出、无效的结构化输出、损坏的工具调用，或不兼容的流式分块
• 性能健康： 首个 token 的时间、总延迟、排队时间和吞吐量
• 容量健康： 并发请求数、每分钟 token 压力、账户余额或部署配额

应使用滚动窗口，而不是一次失败。熔断器可以在目标超过其失败或延迟阈值后临时将其移除，然后在恢复全部流量前允许有限探测。异常值检测也可以剔除一个不健康的部署，同时保留同一提供方下健康的部署可用。

这一原则在网关和服务网格基础设施中早已得到确立：重试、熔断和异常值检测是彼此独立的控制，每一种都需要有边界的策略。Envoy 在其 HTTP 重试、熔断 和 异常值检测 指南中分别记录了这些机制。

仅在请求安全时才重试

只有当重试不会放大工作量或产生重复副作用时，重试才会提升可靠性。

对于在任何响应字节到达之前就失败的非流式文本补全，对同一目标进行一次重试可能是合理的。对于会触发工具、启动图像或视频任务、向外部账户收费，或已经流式输出部分内容的请求，盲目重试可能会产生重复或破坏用户体验。

使用三个问题来定义是否允许重试：

1. 请求是否已在上游被接受？ 在被接受之前发生的连接失败，与提供方开始工作之后发生的超时是不同的。
2. 是否已有任何输出到达客户端？ 一旦开始流式传输，切换提供方可能会产生不连续的答案。
3. 是否存在幂等键或去重记录？ 长时间运行的媒体和代理工作流需要稳定的操作标识。

一个保守的重试矩阵如下：

保持一个端到端截止时间。如果客户端允许八秒，网关不能把七秒花在主目标上，然后再给回退目标八秒。每次尝试都消耗同一请求预算。

回退必须保持契约

回退不只是“再试另一个模型”。它是一种关于主路径失败时哪些内容可以改变的约定。

将回退定义为三个层级：

1. 同一模型，不同部署或账户： 行为风险最低；适用于配额或区域故障。
2. 等效模型家族： 中等风险；需要对 schema、工具、安全性和输出风格进行回归测试。
3. 降级能力： 风险最高；可能禁用工具、减少上下文，或返回排队响应而不是实时响应。

对于每个别名，记录：

• 哪些故障类别会触发回退
• 哪些目标与契约兼容
• 是否告知客户端发生了回退
• 最大尝试次数和总截止时间
• 如何衡量质量和成本变化
• 响应是否可以被缓存或重放

区域性提供方访问增加了另一个维度。某个提供方或模型可能在一个地理区域、账户类型或商业安排中可用，而在另一个中不可用。区域性 LLM 提供方路由解释了这些路由所需的独立访问、策略和故障转移检查。

流式传输是网关契约的一部分

与 OpenAI 兼容的请求形状可以简化客户端迁移，但流式兼容性需要有意识的转换。网关必须保留事件顺序、结束原因、使用量元数据、工具调用片段、错误信号以及连接取消。

在一个流式别名后面路由两个模型之前，请测试：

• 首个事件的到达时间和心跳行为
• 增量文本 delta 格式
• 工具调用参数组装
• 最终事件中的用量报告
• 客户端取消传播
• 首个事件之前和之后的超时行为
• 在头部已经发送后的错误格式

除非协议明确支持恢复，否则不要把流重启隐藏在一个响应中。对于大多数客户端来说，把某个模型的部分答案与另一个模型的第二个答案混在一起，比返回一个清晰的错误更糟。

可观测性将路由与结果连接起来

网关仪表盘很有用，但生产环境的诊断需要结构化遥测，能够把模型请求与周边应用追踪关联起来。

至少应捕获：

默认情况下，避免记录原始提示词和输出。只有在用例、保留策略和用户预期允许时，才记录内容。OpenTelemetry 项目维护着不断演进的生成式 AI 系统 语义约定，可帮助团队使用一致的 span 和指标名称，而不是为每个提供方都发明一套独立 schema。

成本控制应放在上游调用之前

事后支出报告无法阻止事故。准入和路由策略应在发送流量之前评估成本。

有用的控制包括：

• 按密钥和按项目的硬配额
• 预算软警报
• 最大输入或输出单位
• 按环境设置的模型允许列表
• 面向灵活工作负载的成本感知路由
• 用于可重复请求的缓存策略
• 用于昂贵媒体任务的并发限制
• 针对某个模型、提供方、租户或路由的熔断开关

路由引擎需要一份版本化价格表和一致的用量归一化层。否则，“最便宜模型”策略可能会比较不兼容的单位或过时的价格。有关将提供方费率、平台费用和运营控制分离的框架，请参见 AI 网关定价。

最小化的 OpenAI 兼容迁移

最小的客户端改动通常只是一个新的 API 密钥、基础 URL 和模型名称。借助 OpenAI 兼容网关，应用代码可以继续使用相同的客户端库：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="your-model-or-alias",
    messages=[
        {"role": "user", "content": "总结这份事件报告。"}
    ],
)

这段代码改动很简单。安全迁移分为四个阶段：

1. 盘点当前契约。 记录模型、参数、流式行为、工具、schema、超时和错误处理。
2. 运行影子测试或离线评估。 在有代表性的请求上比较输出质量、schema 有效性、延迟和成本。
3. 先对一个工作负载进行金丝雀发布。 从受限的流量比例开始，并准备立即回滚路径。
4. 分别启用路由功能。 先更改端点，再添加别名，然后启用基于健康状况的故障转移，最后再做成本或质量优化。

将这些变更分开进行，能让事故更容易定位。如果端点迁移、模型替换、重试策略和成本优化同时上线，团队就无法知道是哪一个变量导致了回归。Flatkey 集成入门更详细地介绍了 base URL 迁移模式。

生产就绪检查清单

在把网关当作共享基础设施之前，请使用这份检查清单。

客户端契约

• 稳定的 base URL 和版本化请求 schema
• 带有文档化最低能力要求的命名别名
• 一致的错误封装和请求 ID
• 经过测试的流式传输、工具调用和结构化输出

身份与安全

• 按服务和环境分别使用密钥
• 服务端的提供方凭证
• 密钥作用域、配额、轮换和吊销
• 提示词和响应日志要么禁用，要么明确受治理

路由与可靠性

• 成本排序之前的硬性资格过滤
• 版本化的路由策略和价格数据
• 基于真实请求行为的健康状态
• 有边界的重试，以及一个端到端截止时间
• 契约兼容的备用目标
• 熔断器和恢复探测

运维

• 路由原因、提供方错误、延迟和使用情况遥测
• 针对故障转移率、错误率、成本漂移和配额压力的告警
• 按模型和按路由的熔断开关
• 提供方故障和网关故障的运行手册
• 关键工作负载的直达或备用应急路径

Flatkey 如何融入这一架构

Flatkey 提供一个 API 密钥、一个与 OpenAI 兼容的 base URL，以及一个用于支持模型访问、用量和计费的仪表板。它的路由器旨在减少单独的提供方账户和碎片化的集成路径，同时支持上游切换和负载均衡。

对于应用团队来说，这种架构上的好处是稳定的客户端边界：将 OpenAI 兼容客户端指向 https://router.flatkey.ai/v1，选择一个受支持的模型，并将模型访问保持在同一个网关端点之后。团队仍应定义自己的应用层契约、评估阈值、密钥范围、故障预算和回退预期。

最佳的网关架构不会让路由变得不可见。它让路由变得可变、可控、可解释。

FAQ

什么是 AI API 网关？

AI API 网关是应用与模型提供商之间的中介。它在暴露稳定的面向客户端 API 的同时，集中管理身份验证、模型访问、路由、可靠性控制、使用跟踪和策略。

一个 API 密钥是否意味着所有服务共享同一个密钥？

不是。这意味着应用使用网关签发的凭证，而不是直接处理每个提供商的凭证。生产服务、环境和团队仍应获得单独的、带范围限制的密钥。

什么是模型路由？

模型路由是过滤符合条件的模型或部署，并根据能力、策略、健康状况、延迟、质量、成本、区域或容量选择目标的过程。

最安全的故障转移策略是什么？

先切换到另一个健康部署或账户上的同一模型。只有在测试表明备用目标能保持应用的 schema、工具、流式传输、安全和质量契约之后，才应进行跨模型故障转移。

网关能否将流式响应重试到另一个模型上？

通常不能在输出已经到达客户端之后这样做。中途切换可能会把不兼容的部分响应混合在一起。除非客户端和网关实现了明确的续传协议，否则应返回清晰的流错误。

OpenAI 兼容 API 是否足以实现零改动迁移？

它减少了 SDK 和请求形状的变化，但团队仍需要验证受支持的参数、错误、流式事件、工具调用、结构化输出、token 计量以及模型行为。