#AI 应用为什么需要 Gateway 层

很多 AI 功能的第一个版本，都是在业务接口里直接调用模型 Provider。

用户点一个按钮，前端请求后端接口，后端把 prompt 发给模型，再把结果返回给前端。这个路径很短，也很适合验证想法。

但当 AI 功能进入真实产品，问题会很快变多：不同功能要用不同模型，不同用户有不同额度，Provider 会限流或失败，成本需要按租户统计，日志要能追踪一次生成，模型升级不能影响所有业务，安全策略也不能散落在每个接口里。

这时就需要一个 AI Gateway。

AI Gateway 是应用和模型 Provider 之间的工程边界。它不是简单代理，也不是把模型 API 包一层 SDK，而是把模型调用相关的基础能力集中管理，让上层业务可以稳定、可控、可替换地使用 AI。

#为什么直接调用模型会失控

直接调用模型在 Demo 阶段很自然，但在产品阶段会遇到几个典型问题。

第一，模型调用逻辑会散落在各个业务接口里。

写作助手有一套调用代码，客服总结有一套调用代码，代码解释又有一套调用代码。每个接口都要处理 API key、timeout、retry、错误映射、token 统计和日志。久而久之，AI 能力会变成一堆重复但不完全一致的实现。

第二，前端和业务后端会被 Provider 差异绑住。

不同 Provider 的消息格式、模型名、错误码、streaming 协议、工具调用结构、token 统计字段都可能不同。如果业务代码直接依赖这些细节，后续切模型、加 fallback、做 A/B 测试都会很痛。

第三，成本和用量很难统一观测。

如果每个功能自己调用模型，就很难回答这些问题：

• 哪个功能最贵？
• 哪个租户消耗最多？
• 哪个模型错误率最高？
• 哪个 prompt 版本导致 token 上升？
• 哪个入口的首 token 时间变慢？

第四，安全边界会变得模糊。

模型密钥不能暴露给前端，敏感信息需要脱敏，用户权限需要在注入上下文前校验，工具调用需要审计。把这些逻辑放在每个业务接口里，迟早会出现遗漏。

AI Gateway 的价值，就是把这些横切问题收拢到一个清晰的边界里。

#AI Gateway 在系统里的位置

AI Gateway 通常位于业务后端和模型 Provider 之间。前端不直接访问 Gateway，也不直接访问模型 Provider。前端仍然调用业务 API，业务 API 决定任务语义，Gateway 负责执行模型调用。

这张图里，业务 API 仍然知道“用户想做什么”，例如总结文档、生成回复、改写文案、分析表格。AI Gateway 不应该变成万能业务层，它更关注“如何可靠地调用模型”。

一个常见分工是：

• 前端负责交互、streaming 展示、中断、重试入口和用户可见状态。
• 业务 API 负责用户权限、业务对象、会话归属、任务类型和上下文来源。
• Context Builder 负责组装 prompt、历史消息、检索片段、工具定义和 token 预算。
• AI Gateway 负责 provider 抽象、模型路由、密钥、限流、超时、重试、fallback、日志和用量统计。
• Provider 负责实际推理。

这样拆分后，业务层不需要关心每个 Provider 的细节，Gateway 也不需要理解所有业务规则。

#Gateway 应该负责什么

AI Gateway 的职责可以分成七类。

第一，统一模型调用接口。

上层业务最好用稳定的内部协议调用 Gateway，而不是直接使用某个 Provider 的 SDK 参数。内部协议可以包含：

• task type。
• tenant id。
• user id。
• model policy。
• messages 或 structured prompt。
• tools。
• response format。
• streaming mode。
• metadata。

Gateway 再把内部协议转换成具体 Provider 的请求格式。

第二，管理模型和 Provider 路由。

不同任务适合不同模型。分类、标题生成、轻量改写可以使用便宜模型；复杂推理、长上下文分析、代码任务可以使用更强模型。Gateway 可以根据任务类型、用户套餐、成本预算、区域、实时健康状态选择模型。

第三，处理 timeout、retry 和 fallback。

模型调用是外部依赖，外部依赖一定会失败。Gateway 应该统一处理：

• 请求超时。
• Provider 5xx。
• 限流。
• 网络错误。
• streaming 中断。
• 输出格式不合法。

有些错误可以重试，有些错误应该快速失败，有些错误可以 fallback 到备用模型。业务接口不应该每个都重新实现一遍。

第四，保护密钥和权限边界。

Provider API key 应该只存在后端安全环境。Gateway 还可以按租户、用户、功能和模型做访问控制，例如免费用户不能使用高成本模型，某些敏感业务不能发到特定 Provider。

第五，做限流、配额和预算控制。

AI 请求成本高、耗时长，不能像普通查询接口一样完全放开。Gateway 可以统一实现：

• per user rate limit。
• per tenant quota。
• per feature token budget。
• per model concurrency。
• daily 或 monthly usage cap。

第六，记录可观测数据。

每次请求至少应该能追踪模型、Provider、耗时、首 token 时间、输入输出 token、状态、错误、重试次数和成本估算。没有 Gateway，这些字段很容易分散、缺失或口径不一致。

第七，屏蔽 Provider 差异。

不同 Provider 对 tool call、JSON 输出、streaming delta、错误结构和 token usage 的表示不同。Gateway 应该把它们归一成应用内部能稳定消费的事件和结果。

#Gateway 不应该负责什么

AI Gateway 很重要，但它不应该吞掉所有 AI 逻辑。

它不应该替代业务权限。用户能不能读取某个文档，应该由业务层和数据层判断，而不是 Gateway 通过 prompt 猜。

它不应该随意拼业务上下文。某个任务应该注入哪些订单、文档、页面状态和用户偏好，通常属于业务 API 和 Context Builder 的职责。

它不应该把所有功能变成一个通用 chat 接口。总结、分类、抽取、改写、Agent step 是不同任务，应该有清晰的任务语义和约束。

它不应该保存所有业务结果。Gateway 可以保存 run、usage、request trace，但业务消息、文档、任务状态仍然应该落在对应业务模型里。

判断边界的一个简单方法是：如果逻辑和“怎么调用模型更可靠”有关，放 Gateway；如果逻辑和“用户在产品里想完成什么业务任务”有关，放业务层。

#面向前端的 API 影响

前端通常不直接调用 AI Gateway，但 Gateway 的设计会强烈影响前端体验。

首先，Gateway 应该输出稳定的 streaming 事件。

前端不应该处理每个 Provider 原始 delta。更合理的是后端返回应用自己的事件协议，例如：

• run.started
• message.delta
• tool.started
• tool.completed
• usage.updated
• run.completed
• run.failed

这样前端可以用统一状态机渲染不同模型和不同任务。

其次，错误要被映射成用户能理解的状态。

Provider 返回的错误可能是 429、rate_limit_exceeded、context_length_exceeded、invalid_request_error。前端真正需要的是：是否可重试、是否要缩短输入、是否额度不足、是否稍后再试、是否切换模型。

再次，Gateway 可以让前端获得一致的成本和进度反馈。

例如，一次生成结束后返回 token usage、模型名、是否发生 fallback。对于内部工具或开发者产品，这些信息可以直接展示；对于普通用户，则可以转化成额度、等待时间或“已使用更快模型”的体验提示。

最后，Gateway 让模型切换不影响 UI。

如果前端状态依赖的是内部事件协议，而不是 Provider 原始格式，那么从模型 A 切到模型 B，前端不需要重写 streaming 渲染。

#数据模型与流程设计

一个最小可用的 Gateway 数据模型，通常至少要记录 AI run 和 usage。

ai_runs 可以记录一次模型调用的生命周期：

ai_usage 可以记录用量和成本：

一次请求的流程可以这样设计：

这里有一个关键点：run_id 应该从请求开始就存在。前端报错、后端日志、Provider 调用、数据库记录都应该能用同一个 id 串起来。否则线上排查会非常困难。

#常见坑

坑一：把 Gateway 做成只有转发能力的代理。

如果只是把 /v1/chat/completions 原样代理出去，业务仍然会依赖 Provider 格式，日志、限流、路由和错误处理也没有真正统一。Gateway 的核心价值是应用内部协议和治理能力。

坑二：让前端直接选择具体 Provider 模型。

前端可以提供“快速 / 平衡 / 高质量”之类的产品选项，但具体模型选择最好由 Gateway 根据策略决定。否则模型升级、成本调整和区域合规都会被 UI 绑定。

坑三：所有错误都简单提示“生成失败”。

AI 错误需要分层处理。额度不足、上下文过长、模型限流、内容安全拦截、工具失败、Provider 超时，对用户的下一步引导完全不同。

坑四：重试不做幂等。

用户点击重试、网络断开重连、服务端自动 retry，都可能导致重复消息、重复扣费或重复执行工具。Gateway 和业务层要用 run_id、idempotency_key 或 message id 控制幂等。

坑五：fallback 改变输出协议。

从一个模型 fallback 到另一个模型后，输出格式、tool call 行为或 JSON 稳定性可能变化。Gateway 需要校验最终输出是否仍然满足业务契约。

坑六：只记录成功请求。

失败、取消、超时和中断同样重要。很多成本浪费和体验问题都藏在失败路径里。

#小结

AI Gateway 是 AI 应用从 Demo 走向产品的基础架构层。它把模型调用从散落的业务代码中抽出来，统一处理 Provider 抽象、模型路由、密钥、限流、超时、重试、fallback、日志、成本和错误映射。

对前端工程师来说，Gateway 的意义不是“后端多了一层”，而是 AI 交互终于有了稳定协议。前端可以基于统一的 run 状态、streaming 事件、错误语义和用量反馈构建体验，而不必被某个模型 Provider 的细节牵着走。

当一个 AI 产品需要多模型、可观测、可控成本和可演进架构时，Gateway 不是锦上添花，而是系统边界。