如果你的应用只调用一个 AI 模型，集成看起来可能出人意料地简单：存储 API 密钥、发送请求，然后显示响应。
当产品增加第二个提供商、备用模型、使用限制、成本报告，或者需要避免将提示词写入日志时，复杂性就会随之而来。很快，每个服务处理模型访问的方式都会不同。
LLM gateway 在你的应用与一个或多个模型提供商之间建立一个受控的单一入口点。它可以集中管理身份验证、路由、重试、速率限制、可观测性和策略执行，这样这些问题就不必在每个应用中重复构建。
本新手指南将解释什么是 LLM gateway、请求如何通过它流转、哪些功能很重要，以及在什么情况下值得添加 gateway。
LLM gateway 定义
LLM gateway 是一种基础设施层，它接收来自应用的请求，应用共享控制，将每个请求发送到合适的大语言模型端点，并以一致的格式返回响应。
它也被称为 AI gateway、GenAI gateway 或 LLM API gateway。不同供应商对这些标签的使用方式各不相同，但核心思想是一样的：将特定于提供商的访问和运维控制移到一个共享接口之后。
一个有用的思维模型是：
你的应用
↓
LLM gateway
├─ 身份验证和策略
├─ 路由和备用机制
├─ 速率和预算控制
└─ 日志、指标和追踪
↓
模型提供商和模型端点
gateway 并不会取代模型。它管理的是你的应用如何访问模型。
团队为什么使用 LLM gateway
直接集成提供商通常是推出首个原型最快的方式。问题在于，随着产品增长，运维逻辑往往会不断扩散。
如果没有共享的 gateway，不同服务可能各自实现自己的：
- API 密钥和密钥轮换
- 提供商 SDK 配置
- 超时和重试行为
- 备用规则
- 速率限制处理
- 请求日志
- token 和成本计算
- 安全或数据处理检查
这种重复会导致行为不一致。某个服务可能会对超时重试三次，而另一个则立即失败。某个服务可能会记录 token 使用量，而另一个则不会。模型变更可能需要跨多个代码仓库进行修改。
LLM gateway 为团队提供了一个集中地点来标准化这些决策。应用调用 gateway，而 gateway 根据约定的策略处理提供商访问。
LLM gateway 的工作原理：逐步说明
具体流程会因产品而异，但典型请求会经过六个阶段。
1. 应用发送模型请求
客户端将提示词、消息、模型名称、工具定义或多媒体输入发送到 gateway。某些 gateway 提供自己的 API。另一些则提供与 OpenAI 兼容的接口，这样现有客户端只需更改基础 URL，而不必采用完全不同的请求格式。
2. gateway 验证调用方身份
gateway 会检查应用密钥、用户身份、工作负载身份、租户或项目。它还可能验证该调用方是否被允许使用所请求的模型、区域或消费层级。
3. 共享策略运行
在转发请求之前，网关可以应用以下控制措施：
- 请求大小限制
- 令牌配额
- 模型允许列表
- 内容或数据丢失检查
- 提示注入筛查
- 按用户或按项目预算
- 缓存规则
并非每个网关都支持每一项策略。应将每项控制视为需要验证的能力，而不是定义的一部分。
4. 网关选择路由
最简单的路由是将一个命名模型发送到一个已配置的端点。更高级的路由可能会根据地区、可用性、延迟、价格、容量或工作负载类型选择端点。
路由规则应当明确。“选择最便宜的模型”还不够，除非团队同时定义了可接受的质量、上下文长度、工具支持、数据驻留和延迟。
5. 提供方返回响应
网关接收提供方响应，并可能将字段规范化为通用架构。对于流式请求，它会在保留首个令牌时间和完成事件的同时转发部分输出。
6. 网关记录运行数据
一个有用的网关会记录请求状态、路由、模型、提供方、延迟、令牌使用量、重试、回退原因和成本归属。敏感提示和响应不应自动成为必需的日志字段。
有关生产环境遥测设计，请参见 LLM API 可观测性指南。
最重要的 LLM gateway 功能
LLM gateway 可以是一个轻量代理，也可以是一个完整的控制平面。以下是初学者最可能遇到的功能。
统一身份验证
应用使用一个网关凭据，而提供方凭据保留在网关后面。这减少了在各个服务之间分发的提供方密钥数量。
这并不意味着可以省去密钥管理工作。网关密钥仍需要安全存储、范围控制、轮换、撤销和泄露响应。API 密钥管理指南会详细介绍这些控制。
模型路由
路由会将传入请求映射到某个模型端点。常见的路由维度包括：
- 应用请求的模型
- 地理位置或数据驻留要求
- 提供方可用性
- 延迟目标
- 工作负载类型
- 容量和配额
- 成本或预算策略
当有多个端点都能提供同一产品能力时，路由就会变得特别有用。
回退和故障切换
回退是在发生已定义故障后，将请求发送到另一个已批准路由。触发条件可能是超时、容量错误、提供方中断或速率限制响应。
回退并不自动安全。替代模型可能具有不同的输出质量、工具行为、安全特性、上下文限制或结构化输出可靠性。团队应定义哪些故障允许回退，并针对相同的应用契约验证回退模型。
负载均衡
负载均衡会将流量分配到多个符合条件的部署或端点。它可以减轻某个配额池的压力，并提高弹性。
对于 LLM 流量，简单的轮询分配可能并不足够。请求在输入长度、预期输出、流式传输时长和 token 成本方面差异很大。优秀的负载均衡策略会考虑容量和工作负载特征，而不是只统计请求数量。
速率限制和配额
网关可以在请求到达提供商之前强制执行限制。控制措施可以按应用、用户、团队、模型或时间窗口应用。
提供商限制仍然重要。网关无法创造上游提供商未授予的容量。不过，它可以一致地排队、拒绝、重新路由或整形流量。了解底层单位，请参阅LLM 速率限制详解。
可观测性
可观测性将应用行为与网关和提供商尝试连接起来。有用的信号包括：
- 经验证的成功率
- 端到端延迟
- 首个 token 到达时间
- 提供商延迟
- 重试和回退率
- 输入、输出和缓存 token
- 每次请求或已接受任务的成本
OpenTelemetry 项目为生成式 AI 的 span、事件和指标维护语义约定，这可以帮助团队避免发明一套不兼容的遥测词汇。
使用情况和计费控制
网关可以汇总不同提供商的使用记录，并将其分配给项目、团队、功能或客户。根据网关不同，它还可能提供共享余额、预算提醒、硬性配额或发票导出。
不要假设“统一计费”意味着所有成本都可以直接比较。请检查平台如何处理提供商价格、平台费用、缓存 token、失败请求、重试、货币、税费以及价格变动。AI 网关定价指南提供了一个比较框架。
缓存
完全匹配缓存可以在输入和相关设置完全相同时复用之前的结果。语义缓存则尝试在输入足够相似时复用结果。
缓存可以降低可重复工作负载的延迟和成本，但也会带来新鲜度、隐私、多租户隔离和正确性问题。请定义哪些内容可以缓存、键如何构造、条目保留多久，以及何时必须使其失效。
安全与策略执行
网关是一个方便的策略执行点，因为流量会经过它。可能的控制包括内容过滤、提示注入检测、敏感数据检查、模型允许名单和区域限制。
不过，网关检查不能替代应用级授权或输出验证。应用仍然比通用基础设施层更了解用户权限和业务规则。
LLM 网关 vs. API 网关 vs. 模型路由器
这些术语有重叠，但并不相同。
| 层 | 主要职责 | 典型关注点 |
|---|---|---|
| 传统 API 网关 | 管理对通用 API 和服务的访问 | 身份验证、路由、配额、转换、API 分析 |
| LLM gateway | 管理对生成式 AI 模型的访问 | 模型路由、感知 token 的限制、故障切换、提示词策略、模型使用情况和成本 |
| 模型路由器 | 选择模型或端点 | 质量、价格、延迟、能力、容量、可用性 |
LLM gateway 可能在底层使用传统 API 网关，并将模型路由器作为其中一个组件。两者的区别在于专业化：LLM gateway 能理解模型特有的关注点，例如 token、流式传输、上下文窗口、工具调用、模型故障切换以及提示词数据。
OpenAI 兼容性：它的含义以及它不代表什么
与 OpenAI 兼容的 LLM gateway会暴露常见 OpenAI 客户端可以使用的请求和响应结构。在简单迁移中，应用只需更改 API key、base URL 和模型标识符，同时保留大部分客户端代码。
一个最小的 Python 模式如下：
from openai import OpenAI
client = OpenAI(
api_key="YOUR_FLATKEY_API_KEY",
base_url="https://router.flatkey.ai/v1",
)
response = client.chat.completions.create(
model="YOUR_SELECTED_MODEL",
messages=[
{"role": "user", "content": "用通俗易懂的英语解释这个错误。"}
],
)
print(response.choices[0].message.content)
兼容性可以减少集成工作，但不能保证不同模型之间的行为完全一致。不同提供商在支持的参数、工具调用格式、结构化输出、流式事件、token 计量、错误和安全行为方面可能存在差异。
在迁移生产流量之前，请使用 OpenAI 兼容网关迁移检查清单 和可重复的 多模型提示测试工作流。
什么时候应该使用 LLM gateway？
如果以下条件中至少有一项成立，就可以考虑使用网关：
- 你的产品使用或评估多个模型提供商。
- 提供商密钥和 SDK 设置在各个服务之间重复配置。
- 你需要为重要工作流提供经过测试的故障切换。
- 团队需要共享速率限制、预算或模型允许列表。
- 工程和财务无法一致地对模型使用情况进行核对。
- 你需要路由级别的延迟、重试和成本可见性。
- 你希望在不重写每个集成的情况下更换提供商。
- 你需要一个统一的模型访问策略执行点。
随着协调成本上升，网关会变得更有价值。触发因素不一定是请求量很高。如果多提供商访问已经难以解释或控制，即使是小团队也会受益。
什么时候你可能还不需要它？
在以下情况下，直接集成可能更简单：
- 产品只使用一个提供商和一个模型端点
- 只有一个服务发起模型调用
- 现有的提供商日志和限制已满足需求
- 当前没有对故障切换或统一计费的即时需求
- 网关带来的运维复杂性将多于它减少的部分
网关也是另一个生产依赖项。它引入了自身的身份验证、可用性、延迟、配置和数据处理面。不要仅仅因为架构图看起来更整洁就添加它。
如何评估 LLM gateway
请使用测试工作负载，而不是只看功能清单。
1. 定义你的应用契约
写下必须始终成立的行为：
- 所需的模型能力
- 最大延迟
- 可接受的输出格式
- 工具调用或结构化输出规则
- 数据驻留要求
- 质量阈值
- 成本预算
- 允许的故障切换行为
2. 验证协议兼容性
测试应用实际使用的端点和 SDK 功能。除了基础聊天请求之外，还要包括流式输出、工具调用、错误、超时、大输入和取消。
3. 测试故障行为
强制触发超时、速率限制、无效凭证、不可用的模型以及格式错误的响应。确认哪些错误会被重试，哪些路由可以进行故障切换，以及最终错误如何到达应用。
4. 检查遥测和计费
确认你是否可以追踪一条用户请求在每次网关和提供商尝试中的完整路径。将 token 数和费用与受控样本进行对账。验证重试和故障切换是可见的，而不是悄悄地抬高成本。
5. 审查安全性和数据处理
询问提示词和输出在哪里处理、记录了什么、数据保留多久、谁可以访问、凭证如何受到保护，以及哪些控制可以被禁用或限定范围。
6. 评估开销
比较直连和网关路径在首个 token 时间、总延迟、成功率和输出正确性方面的表现。运行足够多的请求以观察波动，而不只是一次成功演示。
适合新手的实用检查清单
在采用网关之前，你应该能够回答这些问题：
- 哪些应用和用户可以调用它？
- 批准了哪些模型和提供商？
- API 是否与我们使用的客户端功能兼容？
- 超时、429 或提供商中断时会发生什么？
- 哪些模型变更可以在不经过应用批准的情况下进行？
- 提示词、响应和凭证如何被记录或保留？
- 使用情况能否归因到某个团队、功能或客户？
- 计费记录能否与提供商行为对账？
- 网关增加了多少延迟？
- 如果有必要，我们如何退出或绕过网关？
如果供应商无法清晰回答这些问题，那么即使市场上拥有最长的模型目录，也无法弥补这种运维不确定性。
Flatkey 的定位
Flatkey 被定位为面向开发者的统一访问层：一个 API key、一张账单，以及一个兼容 OpenAI 的端点，可用于多个文本、图像和视频模型。
对于已经在使用 OpenAI 客户端的开发者来说，预期的接入模式很简单：
- 创建一个 Flatkey 密钥。
- 将客户端 base URL 更改为
https://router.flatkey.ai/v1。 - 为该工作负载选择一个可用模型。
- 在将生产流量迁移之前，测试兼容性、质量、限制和故障行为。
先从当前模型和定价目录开始，然后评估您的应用所需的确切路由。即使是适合新手的集成，也是一个生产依赖项，因此同样的安全性、测试和可观测性标准也应适用。
常见问题
LLM gateway 和 AI gateway 是同一个东西吗？
通常是。 “AI gateway”、“GenAI gateway”和“LLM gateway”经常用于指代控制应用访问生成式 AI 模型的共享层。产品范围各不相同，因此应比较能力，而不是标签。
LLM gateway 会托管这些模型吗？
不一定。有些 gateway 只会代理或路由请求到外部提供商。另一些则是推理平台的一部分，也会托管模型。应询问每个模型由哪个实体提供服务，以及请求在何处被处理。
LLM gateway 能让每个模型都可互换吗？
不能。通用 API 可以统一传输层，但模型在质量、上下文限制、工具、结构化输出、安全行为、延迟和价格方面仍然不同。更换模型需要评估。
LLM gateway 能防止提供商宕机吗？
不能。它可以通过路由和回退减轻某些故障的影响，但前提是存在经批准的替代方案，并且 gateway 本身保持健康。
gateway 会降低 LLM 成本吗？
它可以提高成本可见性，并支持路由、配额或缓存，但节省并非自动实现。应按可接受的应用结果来衡量每次成本，包括重试、回退尝试和质量失败。
OpenAI-compatible gateway 可以直接替换吗？
它可以尽量减少代码更改，但“兼容”并不等同于行为完全一致。请测试应用所依赖的每个功能和模型。
结论
LLM gateway 是应用与模型提供商之间的共享访问和控制层。它的职责是随着产品 AI 使用的增长，让身份验证、路由、回退、限制、可观测性和策略更加一致。
对于单个原型，直接集成提供商可能就足够了。对于多模型产品，或者需要可靠控制的团队，gateway 成为一种实用方式，可避免在每个服务中反复重建相同的基础设施。
正确的第一步不是选择功能最多的 gateway。应定义您的应用契约，测试故障路径，验证数据和计费模型，并确认 gateway 带来的复杂性少于它增加的复杂性。
