模型网关教程：统一API、供应商路由、降级、重试、计费和审计
摘要
模型网关不是把不同供应商的接口包装成同一个路径，而是把模型调用从业务代码中抽离为可治理的基础设施。统一 API、模型别名、供应商路由、降级、重试、超时、缓存、计费和审计应被放在同一条调用链中分析，因为网关的核心作用，是把“选哪个模型”转化为可版本化、可观测、可回滚的策略问题。任务语义在这里尤其关键：不同业务对延迟、成本、质量、数据出域和失败后果的约束不同，网关必须处理这些差异，而不是把所有请求压平成普通聊天调用。
关键词
模型网关；统一 API；模型路由；降级策略；重试；计费归因；审计；供应商治理
研究问题与方法
本文关注的问题是：在多供应商、多模型和多租户环境中，如何让业务服务表达任务约束，而不是直接依赖供应商模型名与 SDK 细节。方法上采用契约分层分析：先区分兼容层、任务层和策略层，再用失败分类与成本归因检验网关是否真的减少了业务系统对供应商变化的耦合。
这张图把网关从“转发器”变成“决策器”。真正的边界在调用前就发生：能力不匹配、预算不足、数据等级不允许出域时，不应等模型返回后再补救。后文用一个简化的路由目标函数描述这些约束如何同时进入策略。
其中 表示模型对任务的质量估计， 表示成本， 表示延迟， 表示合规、稳定性和降级风险； 是业务场景给出的权重。公式的作用不是自动替代评审，而是防止团队只用“便宜”或“强”单一维度做路由。
模型网关是 AI 应用从原型走向生产时绕不开的一层。早期项目常见做法，是在业务代码里直接接 OpenAI、Anthropic、Gemini、DeepSeek、Qwen、Kimi、GLM 或 MiniMax 的 SDK：哪个功能先上线，就把哪个供应商的调用写进哪个服务。这样做在第一个演示里很快，但当应用开始有多个模型、多个用户、多个功能、多个预算、多个地区、多个重试策略时，系统会迅速变得不可控。密钥散落在不同服务里，模型名写死在不同分支里，重试逻辑各写一套，账单只能按供应商总额看，故障时也很难知道是哪次请求、哪个用户、哪个模型、哪条业务链路出了问题。
生产级模型网关的价值，是把“模型调用”从业务代码里抽成可治理的基础能力。应用不应该关心每个供应商的鉴权细节、错误码差异、价格表变化、上下文限制、重试节奏和降级顺序。应用应该表达清楚任务意图、输入类型、质量要求、成本上限、延迟预算和风险等级；网关负责把这些要求翻译成一次可观测、可计费、可审计、可回退的模型调用。模型网关不是为了让调用路径看起来统一，而是为了让整个 AI 系统能在真实流量下持续演进。
截至 2026-05-22，主流模型供应商仍在高速更新。OpenAI 的 Responses API 已经把文本、图片、文件输入、工具调用、流式输出、会话状态和内置工具放到统一响应接口里；Anthropic 的 Claude API 继续强调 Messages、工具使用、长上下文和速率限制；Google Gemini API 在多模态、长上下文、缓存和搜索 grounding 上有独立体系；DeepSeek、Qwen、Kimi、GLM、MiniMax 也都提供 OpenAI 兼容或近似兼容接口，并在价格、上下文、工具调用、思考模式、多模态和本地部署上形成不同优势。模型网关的设计必须承认这种变化：供应商会变，模型名会变，价格会变，能力边界会变，业务代码不能被这些变化反复拉扯。
这篇教程不把模型网关讲成一个简单反向代理，而是按生产系统的视角拆开：统一 API 怎么定义，供应商路由怎么做，什么时候降级，哪些错误值得重试，计费如何归因，审计应该记录什么，如何把这些能力落到一个中文团队能维护的工程结构里。
引言：模型网关解决的不是接入问题，而是治理问题
“能接上模型”不是难点。今天大多数供应商都提供 HTTP API，很多还兼容 OpenAI Chat Completions 或 Responses 风格。真正难的是接上之后能否长期稳定运行。一个用户发起知识库问答，可能先做查询改写，再做向量检索，再做重排，再调用强模型生成答案，再用小模型做格式校验。一个代码助手可能在一次任务里连续读取文件、生成补丁、解释测试失败、重新规划。一个客服助手可能要根据会员等级、地区、工单类型和预算选择不同模型。只要这些调用进入生产，就会出现成本、限流、超时、降级、审计和质量回归问题。
模型网关的第一层目标是统一调用入口。业务服务只访问自己的网关，而不是直接访问十几个供应商。这样密钥不会散落，调用日志能集中，模型替换也不需要改动所有业务模块。统一入口并不等于把所有模型伪装成同一个模型。不同模型的上下文、工具调用、结构化输出、思考模式、图片输入和文件输入能力并不完全相同，网关要提供统一外壳，同时保留能力差异。
第二层目标是统一策略。哪些任务走强模型，哪些任务走便宜模型，哪些任务可以用缓存，哪些任务允许跨供应商降级，哪些任务必须同供应商重试，哪些请求超过预算后直接拒绝，这些都应该由网关策略控制。策略写在业务代码里，会变成散落的 if else；策略写在网关里，才能被灰度、观测、审批和复盘。
第三层目标是统一证据。AI 系统的问题往往不是“接口挂了”这么简单。一次差回答可能来自提示词版本、模型版本、上下文截断、缓存误命中、供应商降级、工具结果错误、请求被限流、输出被截断，也可能来自用户输入本身不清楚。网关至少要保存请求摘要、模型选择、token 用量、价格、耗时、错误类别、重试次数、降级路径和业务关联标识。没有这些证据，团队只能凭感觉争论模型好坏。
从直连接口到模型网关的分水岭
一个项目什么时候需要模型网关？不是等到规模很大才需要。只要满足下面任意三条，就应该尽早引入：业务里已经有两个以上模型供应商；同一供应商下有多个模型规格；需要按用户、团队、功能或项目统计费用；出现过 429、超时、余额不足、输出截断等生产问题；模型密钥被多个服务或多人共享；需要按任务质量切换模型；需要记录 AI 调用证据以便复盘。
直连接口的最大问题，是业务代码会吸收供应商差异。OpenAI Responses API 支持 previous_response_id、内置工具、结构化输出和响应对象管理；Anthropic Messages API 有自己的消息格式、工具块和速率限制；Gemini API 的模型名、缓存、search grounding 和多模态输入方式不同；DeepSeek、Kimi、MiniMax 虽然兼容 OpenAI SDK，但思考模式、上下文长度、工具调用细节和计费字段仍有差别。把这些差异都写进业务服务，会让业务服务变成供应商适配层。
模型网关要把适配责任移走。业务服务提交的是一个“任务请求”：例如“低成本中文摘要”“高准确合同审查”“可调用工具的代码分析”“需要图片理解的客服工单”“必须保留审计证据的财务解释”。网关根据任务类型和策略选择实际模型。这样业务代码只认识稳定的内部模型别名，例如 fast_chinese_summary、strong_reasoning、vision_qa、coding_agent、safe_finance_answer，而不直接写死 gpt-5.2、glm-5、kimi-k2.6 或 MiniMax-M2.7。
分水岭还体现在失败处理上。直连时，开发者通常会在调用失败后简单重试三次；生产网关则需要区分错误类型。用户输入超出上下文，是请求设计问题，不该盲目重试。供应商返回 429，是限流问题，可能要排队、等待或切换同能力备用模型。供应商 5xx 或网络超时，可能适合同供应商重试或跨供应商降级。内容安全拒绝、鉴权失败、余额不足、模型不存在、参数不支持，都有不同处理方式。
统一 API：不要只统一路径，要统一语义
很多团队把模型网关理解为“统一成 OpenAI 格式”。这有用，但远远不够。OpenAI 兼容格式解决的是客户端生态问题，不能自动解决任务语义问题。一个中文长文改写任务、一个财务解释任务、一个代码修复任务、一个图片质检任务，即使都能塞进同一个 /chat/completions 请求，它们的质量要求、失败后果和成本结构也完全不同。
更合理的统一 API 应该分成两层。第一层是兼容层，为现有 SDK 和第三方工具提供 OpenAI 或 Anthropic 风格接口。MiniMax 文档就同时提供 OpenAI SDK 和 Anthropic SDK 兼容接口；DeepSeek 和 Kimi 也提供 OpenAI 格式入口；LiteLLM、Portkey 这类网关工具也强调通用接口。兼容层的价值是迁移成本低，能让工具快速接入。
第二层是任务层，面向自己的业务系统。任务层不暴露供应商模型名，而暴露业务含义。例如请求体可以包含 task_type、quality_tier、latency_budget_ms、max_cost_cents、requires_citations、allow_fallback、data_classification、tenant_id、end_user_id、workflow_id。这些字段不应该出现在最终用户界面里，但在后端治理中很关键。它们让网关知道这次调用是普通润色、严肃审查、长文分析还是工具型 Agent 步骤。
统一语义还包括输出契约。若业务需要 JSON，就不能只在提示词里写“请输出 JSON”。OpenAI 的结构化输出、DeepSeek 的 JSON Output、不同供应商的 tool calls 或 response schema 能力都应进入网关能力表。网关可以为每个任务声明输出类型：自然语言、严格 JSON、带引用答案、工具调用计划、流式文本、嵌入向量、图片理解结果。模型不支持某种契约时，网关应该拒绝或换模型，而不是让业务在后处理阶段碰运气。
统一 API 的原则是：入口尽量稳定，能力显式声明，供应商差异由适配器承担，业务只依赖内部任务契约。这样即使某个模型名废弃、某个接口升级、某个供应商限流，业务层也不需要在多个服务里同步改代码。
模型别名：把“用哪个模型”变成可治理配置
模型别名是模型网关最实用的设计之一。不要让业务代码直接写供应商模型 ID，而是定义一组内部别名。比如 chat_fast 表示低延迟通用对话，chat_strong 表示强推理，cn_long_context 表示中文长文，code_agent 表示代码智能体，vision_doc 表示图片和文档理解，cheap_batch 表示低成本批处理。每个别名背后可以配置多个候选模型、路由权重、成本上限和降级顺序。
别名要按任务能力命名，而不是按供应商品牌命名。deepseek_main、qwen_backup 这种名字会把策略和供应商绑死。更好的命名是 reasoning_economy、long_context_cn、agent_coding_high。当 DeepSeek、Qwen、Kimi、GLM、MiniMax 某一方价格或质量变化时，可以在配置层调整，而业务系统仍然请求相同别名。
别名还要有版本。chat_strong:v1 和 chat_strong:v2 可能对应不同模型组合、不同系统提示词和不同降级策略。灰度发布时，可以让 5% 流量走 v2，同时保留 v1 回滚。没有版本的别名会让团队无法解释质量变化：今天这个别名背后的模型换了，但历史日志只记录别名，无法复盘实际差异。
LiteLLM 的虚拟密钥和模型别名能力说明了一个方向：可以通过网关控制 key 能访问哪些模型，也可以把用户请求中的模型名映射到不同后端模型。生产系统应进一步把别名和业务策略结合起来：同一个别名对免费用户、付费用户、内部员工、重要客户可以有不同候选池；同一个别名在白天高峰和夜间批处理可以有不同成本策略。
模型别名不是为了掩盖模型差异，而是为了让差异可控。每个别名都应该有说明：适用场景、不可用场景、默认模型、备用模型、最大上下文、最大输出、是否支持工具、是否支持图片、是否允许跨境供应商、默认预算、质量评测集和负责人。这样模型选择才是工程资产，而不是某个开发者的一次临时判断。
供应商路由：从静态选择到策略选择
供应商路由不是“随机挑一个能用的模型”。路由应该基于任务、成本、延迟、质量、配额、地区、数据等级和供应商健康状态综合判断。最简单的路由是静态路由：某个别名固定对应某个模型。它适合早期上线和高风险任务，因为行为可预测。但静态路由无法处理限流和成本波动。
第二种是权重路由。比如 chat_fast 的 80% 流量走低成本模型，20% 走新模型，用于灰度比较。权重路由适合新模型评估和供应商迁移。要注意，权重路由必须记录实际命中的模型，否则业务看到的只是同一个别名，无法解释为什么某些用户体验不同。
第三种是约束路由。网关根据请求约束过滤模型：输入长度超过 200K 时，短上下文模型被排除；请求包含图片时，只保留视觉模型；需要严格工具调用时，只保留工具能力可靠的模型；数据等级为敏感时，只允许指定地区或本地部署模型；预算低时，排除旗舰模型。约束路由是生产系统最重要的一类，因为它把模型能力和业务规则对应起来。
第四种是健康路由。供应商出现 429、5xx、超时、排队变长或成功率下降时，网关临时降低权重或熔断。LiteLLM 路由文档提到负载均衡、cooldown、fallback、timeout、retry 和按 RPM/TPM 管理；Portkey 也把 fallback、load balancing、automatic retries、circuit breaker、request timeout 和 budget limits 放在网关策略里。这些能力的核心不是“多试几次”，而是让故障不扩散到业务层。
第五种是评测路由。网关可以按历史反馈和离线评测调整默认模型。例如中文长文摘要在 Kimi 或 Qwen 上表现稳定，代码智能体在 GLM、MiniMax 或 Claude 上表现更好，低成本推理在 DeepSeek 上性价比高。评测路由不应该完全自动黑箱化。生产系统更稳的方式，是把评测结果提交给模型策略评审，再通过版本化配置发布。
降级：不是越便宜越好，而是保持任务可接受
降级是模型网关最容易被误用的能力。很多团队把降级理解为“主模型失败就换便宜模型”。这可能导致结果质量突然下降，甚至造成业务错误。正确的降级目标不是省钱，而是在主路径不可用时保持任务的最低可接受结果。
降级前要先定义任务等级。普通文案润色、标签生成、低风险摘要可以允许跨模型降级，只要输出格式满足要求即可。合同审查、医疗解释、财务建议、合规判断、对外承诺等高风险任务，不应随意降级到能力更弱或行为不同的模型。代码自动修改、数据库操作、真实业务工具调用，也要谨慎降级，因为不同模型的工具调用稳定性和指令遵循能力可能差异很大。
降级还要区分横向降级和纵向降级。横向降级是换同等能力的备用供应商，例如从某个强推理模型切到另一个强推理模型。纵向降级是从强模型切到较弱但更快或更便宜的模型。横向降级适合可用性故障，纵向降级适合预算超限或低风险任务。不要在没有提示用户和业务验收的情况下，把高风险任务从强模型纵向降级到轻量模型。
降级路径要显式记录。最终答案应该在后台可追溯：原计划使用哪个别名，命中了哪个模型，失败了几次，因为什么错误降级，备用模型是谁，是否降低了质量等级，是否触发人工复核。面向最终用户的界面不需要展示这些实现细节，但运营和工程团队必须能查到。
降级也可以是能力降级，而不只是模型降级。比如长上下文模型不可用时，可以先做文档切块摘要，再让中等上下文模型回答；视觉模型不可用时，可以提示用户稍后处理图片任务，而不是用纯文本模型胡乱猜图；工具调用模型不稳定时，可以生成草稿建议，取消自动执行。生产级降级应保护结果边界，而不是假装一切正常。
重试：只重试值得重试的失败
重试看似简单，实际是成本和可靠性的交叉点。每一次重试都会增加延迟和费用，若请求本身不可成功，重试只会放大事故。模型网关必须把错误分成可重试、可等待、可降级、可修正和不可继续几类。
可重试错误通常包括短暂网络错误、供应商 5xx、连接重置、网关超时、偶发流式中断。对这类错误，可以用指数退避和随机抖动，避免所有请求同时重试造成雪崩。若供应商返回 Retry-After 或速率限制头，应优先尊重供应商建议。OpenAI、Anthropic、Gemini 等官方文档都强调速率限制和配额行为，网关应把这些限制翻译成自己的排队和熔断策略。
可等待错误主要是 429 和配额拥塞。若业务允许等待，可以进入短队列；若用户正在交互，则应该尽快返回可理解的状态，让用户稍后继续。对低价值批处理任务，等待比降级更合适；对实时对话，降级到备用模型可能更合适。
可修正错误包括参数不支持、输入超长、输出 JSON 不合法、工具参数不符合 schema。输入超长不该盲目重试，而应触发压缩、分块或拒绝。JSON 不合法可以尝试一次“修复输出”或改用更严格的结构化输出能力。工具参数不合法可以让模型重新生成参数，但必须限制次数，避免 Agent 循环消耗。
不可继续错误包括鉴权失败、余额不足、模型不存在、用户无权限、数据不允许出域、内容安全拒绝。对这些错误，重试没有意义。网关应该返回明确的业务错误，并记录审计证据。尤其是余额不足和模型不存在，说明配置或运营问题，不能通过反复请求解决。
一个好重试策略通常包含：每类错误的最大重试次数，总耗时上限，是否允许跨供应商，是否允许降低模型等级，是否计入用户费用，是否写入告警，是否触发熔断。重试不是在异常处理里写三行代码，而是一套成本明确、边界明确的运行策略。
超时和流式输出：别让用户等一个永远不会结束的回答
模型调用有两种常见延迟：首 token 延迟和完整响应耗时。普通问答更关心首 token，批处理更关心总耗时，工具型 Agent 更关心每一步是否卡住。模型网关要分别设置连接超时、首 token 超时、总输出超时和工具调用超时。
流式输出能改善用户感知，但也会增加网关复杂度。网关要记录流式开始时间、最后事件时间、输出 token 数、是否完整结束、是否中途断开。若流式中断发生在输出很早阶段，可以重试或降级；若已经输出大量内容，再重新生成可能导致用户看到两套答案。对于关键任务，网关可以把流式展示和后台最终记录分开：前端看到流，后台保存最终完整响应和结束状态。
超时设置要按任务类型不同而不同。标题生成和分类任务总耗时可以设得很短；长文分析、代码修复、深度推理可以给更长预算；多模态视频理解和长上下文任务需要单独策略。统一一个 60 秒超时会让简单任务拖太久，也会让复杂任务过早失败。
流式输出还涉及计费。若用户中途取消，供应商已经生成的 token 仍可能计费。网关应该记录取消时间、已生成 token、供应商返回 usage 情况和最终扣费口径。对用户体验来说，取消按钮意味着“不再等待”；对成本系统来说，它不一定意味着“没有花费”。
计费：从供应商账单变成业务账单
供应商账单只能告诉你总共花了多少钱，不能告诉你哪个产品功能、哪个团队、哪个客户、哪个工作流花了钱。模型网关要把供应商计费转换成业务计费。每次调用至少要归属到租户、用户、应用、功能、工作流、任务、模型别名和实际模型。
计费单位通常从 token 开始，但不能停在 token。OpenAI、Anthropic、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax 的价格表都按输入、缓存输入、输出、图片、视频、音频、搜索工具或特殊工具分别计价。DeepSeek 文档还把缓存命中和未命中输入区分计费；MiniMax 的 Pay as You Go 页面区分普通输入、输出、缓存读和缓存写；Z.AI 的价格表包含文本、视觉、图片、视频、音频和内置工具；Gemini 的定价也涉及缓存、批处理和 grounding。网关要保留供应商原始 usage，同时计算自己的标准成本。
标准成本应有两层。第一层是实际供应商成本，用于财务核算。第二层是业务内部分摊成本，用于产品预算和用户额度。内部成本可以加上一定管理系数，用于覆盖缓存、网关、日志、向量检索和后台任务。不要让业务团队只看到供应商 token 价格，否则会低估整条 AI 链路的真实成本。
预算控制要前置。每次调用前，网关可以根据输入 token 估算最大成本，根据 max_output_tokens 或任务类型估算输出上限。如果请求可能超过用户、团队或功能预算，应在调用前拒绝、压缩、降级或要求确认。等供应商账单出来后再发现费用异常，已经太晚。
成本报表要能回答几个问题：今天哪个功能最贵，哪个用户异常调用，哪个模型别名成本增长最快，缓存命中率是否下降，重试造成了多少额外费用，降级节省了多少费用，强模型是否被低价值任务滥用。模型网关如果不能回答这些问题，就只是转发层，不是治理层。
审计：记录足够证据，但不要泄露敏感内容
AI 审计不是把完整提示词和完整回答全部写进日志就完事。很多请求包含用户隐私、商业机密、合同、代码、财务数据、客户信息。审计需要证据，也需要最小化。网关应把审计记录分成元数据、摘要、可选密文和业务证据。
元数据包括请求时间、租户、用户、应用、功能、工作流、模型别名、实际供应商、实际模型、路由策略版本、提示词版本、输入 token、输出 token、缓存命中、费用、耗时、状态、错误类别、重试次数、降级路径。元数据通常可以长期保存，用于统计和复盘。
摘要用于快速理解请求，但应避免保存完整敏感文本。可以保存由业务系统生成的任务标题、文档 ID、片段哈希、检索引用 ID、工具调用名称、输出结构状态。若必须保存完整输入输出，应加密存储、设置访问权限和保留期限。不要把用户原文混入普通应用日志，更不要让日志平台成为新的数据泄露面。
审计还要记录策略决策。为什么这次用了某模型？为什么允许降级？为什么拒绝请求？为什么工具调用被拦截？这些不是供应商返回的内容，而是网关自己的决策证据。未来用户投诉、成本争议、合规检查、质量回归都需要这些记录。
对高风险任务，审计应和人工确认联动。比如模型生成退款建议、合同修改建议、权限变更建议，网关可以记录模型建议，但最终执行必须由业务系统保存确认人、确认时间、确认内容和执行结果。模型网关负责 AI 调用证据，业务系统负责真实业务动作证据，两者不能混为一谈。
安全：网关是密钥边界，不是全部安全边界
模型网关必须承担密钥隔离。前端应用不应直接持有供应商 API key，普通业务服务也不应保存主密钥。业务服务拿到的是网关签发的内部凭证或服务账号，网关再使用供应商密钥调用外部 API。这样供应商密钥可以集中轮换、集中权限控制、集中审计。
但模型网关不是全部安全系统。用户是否有权查看某份文档，是否能调用某个业务工具，是否能读取某个客户数据，必须由业务系统或权限服务判断。不要把权限规则只写进系统提示词。模型可能遵守，也可能误解；工具层必须强制校验。
数据出域策略也要在网关层体现。某些数据可以发给境外供应商，某些数据只能使用国内 API，某些数据只能本地模型处理，某些数据需要脱敏后才能调用。网关的路由策略必须能读取数据等级，并在候选模型中过滤不合规供应商。否则“统一路由”会变成数据治理风险。
安全还包括供应商可信度。中文开发者常遇到各种低价中转和聚合服务。价格低并不代表适合生产。模型替换、日志留存、密钥来源、合规承诺、故障响应、数据使用条款都要清楚。生产系统优先直连官方平台或可信云平台；若使用第三方网关，也要明确它是否记录请求、是否可自托管、是否支持审计导出、是否能证明模型没有被替换。
缓存：只缓存可缓存的任务
模型缓存能显著降低成本，但错误缓存会伤害质量。缓存分为精确缓存、前缀缓存和语义缓存。精确缓存适合完全相同的请求，例如固定说明文、重复 FAQ、标准分类。前缀缓存适合长系统提示词、固定文档前缀或多轮会话中重复上下文。语义缓存适合相似问题，但风险也更高，因为相似不等于相同。
DeepSeek 的 Context Caching 文档说明了硬盘缓存和 prompt_cache_hit_tokens、prompt_cache_miss_tokens 等 usage 字段；OpenAI、Anthropic、Gemini、GLM、MiniMax 等也有各自缓存或缓存计费方式。网关应统一记录缓存命中、缓存类型、缓存键、节省成本和命中后的输出来源。
不要缓存高风险个性化回答。财务、法律、医疗、合同、权限、订单、实时库存、价格和用户私有数据都不适合粗暴语义缓存。一个用户问“我的订单能否退款”和另一个用户问“这个订单能否退款”语义相似，但业务事实可能完全不同。语义缓存必须结合租户、权限、数据版本和任务类型。
缓存还要有版本。提示词变了、模型变了、知识库版本变了、业务规则变了，旧缓存可能不再适用。缓存键应包含任务版本、提示词版本、模型别名版本、知识版本和重要输入哈希。否则团队会遇到“明明改了提示词，用户还看到旧答案”的问题。
统一错误模型：把供应商差异翻译成业务能理解的状态
不同供应商的错误码和错误消息差异很大。生产网关应定义自己的错误分类，例如 AUTH_FAILED、MODEL_NOT_FOUND、RATE_LIMITED、QUOTA_EXCEEDED、INPUT_TOO_LARGE、OUTPUT_TOO_LARGE、UNSUPPORTED_PARAMETER、SAFETY_BLOCKED、PROVIDER_TIMEOUT、PROVIDER_5XX、STREAM_INTERRUPTED、INVALID_TOOL_ARGUMENTS、BUDGET_EXCEEDED、POLICY_DENIED。
业务服务不应该解析供应商原始错误文本。它只需要知道是否可重试、是否可稍后继续、是否需要用户修改输入、是否需要管理员处理、是否产生费用。网关可以保留原始错误供工程排查，但对业务层返回稳定错误码和用户可理解信息。
错误模型还决定告警策略。单个用户输入过长不需要打扰值班人员；全局 429 增加需要观察配额；某个供应商 5xx 激增需要熔断；鉴权失败可能说明密钥过期；余额不足是运营事故；MODEL_NOT_FOUND 可能是模型废弃或配置错误。统一错误分类能让告警更准。
对最终用户的提示要克制。不要把供应商错误码、模型名、token、栈信息暴露到页面。用户只需要知道：请求太长、当前繁忙、暂时不可用、需要重新提交、该内容无法处理或余额不足。实现细节留给后台审计和运维视图。
工具调用和 Agent：网关要控制模型能做什么
随着模型从单次回答走向工具调用，网关的责任变重。OpenAI Responses API、Anthropic Messages、Gemini Function Calling、DeepSeek Tool Calls、GLM Function Call、Kimi 和 MiniMax 的工具调用能力，都让模型可以选择外部函数。模型网关不能只转发工具定义，还要管理工具权限和调用证据。
工具应按风险分级。低风险工具如查询公开文档、搜索知识库、读取只读资料，可以自动调用。中风险工具如创建草稿、生成报告、更新临时状态，需要记录证据。高风险工具如发送邮件、退款、删除数据、提交审批、修改权限，必须经过业务系统确认。模型网关可以根据任务和用户权限过滤工具列表，不让模型看到不该调用的工具。
工具调用还要有限额。一次请求最多调用多少工具，单个工具最多耗时多久，总成本上限是多少，循环多少轮后停止，都应该由网关或编排层控制。OpenAI Responses API 中有 max_tool_calls 这类控制项，很多 Agent 框架也会设置步数上限。没有上限的工具调用会把一次用户请求变成不可预测的长任务。
网关需要记录工具调用链：模型提出的工具名、参数摘要、业务系统校验结果、工具返回状态、模型是否基于工具结果继续生成。不要只记录最终回答。Agent 出错时，问题常常发生在中间某个工具结果，而不是最终自然语言。
模型能力表：路由前先知道每个模型能做什么
模型网关需要一张持续更新的能力表。能力表不是营销对比表，而是工程路由依据。字段可以包括：供应商、模型 ID、内部别名、上下文长度、最大输出、文本输入、图片输入、视频输入、文件输入、工具调用、结构化输出、思考模式、缓存、流式输出、批处理、embedding、地区、价格、速率限制、数据保留条款、上线状态、废弃日期、评测分数。
能力表必须从官方资料和实测共同得出。官方资料告诉你模型支持什么；实测告诉你在自己的任务里是否可靠。比如某模型文档写着支持工具调用，不代表它在复杂中文业务工具里稳定；某模型上下文很长，不代表它能准确利用长文档末尾证据；某模型价格便宜，不代表在需要多次修复输出的任务里总成本更低。
能力表要支持“硬约束”和“软偏好”。硬约束包括必须支持图片、必须支持工具、必须在指定地区、必须不超过预算。软偏好包括更低延迟、更高中文质量、更好代码能力、更高缓存命中、更低历史失败率。路由时先满足硬约束，再按软偏好排序。
能力表还要记录生命周期。DeepSeek 文档中提到 deepseek-chat 和 deepseek-reasoner 将废弃并映射到新模型；各家供应商也会不断推出 preview、latest、stable、legacy。生产系统不要无限依赖 latest。对关键业务，应使用明确版本或内部别名版本，并为迁移设灰度窗口。
一个最小可用模型网关架构
一个小团队的最小模型网关可以拆成七个组件。第一是接入层，提供 OpenAI 兼容接口和内部任务接口。第二是鉴权层，识别应用、租户、用户和服务账号。第三是策略层，根据任务、预算、权限和健康状态选择模型。第四是适配层，把统一请求转换成不同供应商请求。第五是执行层，处理超时、重试、流式转发和降级。第六是计费层，记录 usage、成本和预算。第七是审计层，保存元数据、错误、路由和证据。
这七个组件不一定是七个服务。早期可以在一个后端服务里实现，配合 Postgres 存配置和日志，Redis 做限流和短期状态。等流量增长后，再把执行层和日志管道拆出去。关键是边界清楚：策略不要散在业务代码里，适配不要散在多个应用里，计费不要依赖人工对账。
如果团队不想从零做，可以使用 LiteLLM Proxy、Portkey、Kong AI Gateway、Cloudflare AI Gateway、Envoy AI Gateway 或自研薄网关组合。LiteLLM 适合快速统一多模型调用、虚拟 key、预算、路由、fallback 和 spend tracking；Portkey 提供 AI Gateway、fallback、retry、budget、observability 和配置策略；Kong 更适合已有 API 网关体系的企业；Envoy Gateway 的扩展和限流观测适合云原生团队。选择工具时不要只看模型数量，要看是否能满足自己的审计、权限、计费和部署要求。
最小架构上线前，应至少跑通四条路径：一次成功调用，一次供应商 429 后排队或降级，一次输入超长后返回可理解错误，一次预算超限后拒绝。很多网关只验证成功路径，结果生产事故都发生在失败路径。
配置示例：用策略描述模型选择
生产配置可以用数据库、YAML 或管理后台维护。核心不是格式，而是字段完整。一个模型别名应包含候选模型、权重、约束、重试、降级、预算和审计等级。例如中文长文任务可以配置为：首选支持长上下文且中文稳定的模型，允许同等级备用，禁止降级到短上下文模型，最大输出固定，必须记录引用和文档版本。
代码智能体任务则不同。它需要强工具调用、较高输出上限、长任务容忍、较严格循环次数、完整工具链审计。若主模型不可用，可以降级到另一个代码能力强的模型，但不应降级到普通聊天模型。模型返回补丁后，还应由业务编排层跑测试或静态检查，不能只相信模型回答。
低成本批量摘要任务可以更激进。它可以使用便宜模型，启用缓存，允许排队，允许夜间执行，允许多次小重试，但不需要强模型。若预算不足，可以跳过低优先级任务而不是影响实时用户请求。
配置应支持灰度。新模型进入候选池时，先从 1% 低风险流量开始，记录质量、成本、延迟和错误。通过评测后再扩大。不要在某个模型发布当天把所有生产流量切过去。新模型可能很强，但接口、限流、输出风格、工具调用细节都需要验证。
案例：知识库问答网关怎么设计
一个中文知识库问答系统通常包含查询改写、检索、重排、答案生成、引用校验和质量反馈。模型网关在其中不是只负责最终生成，也可以负责每个模型步骤的路由。查询改写可以走低成本中文模型；重排可以走专门 reranker 或轻量模型；最终生成根据问题复杂度走强模型或普通模型；引用校验可以走规则加小模型。
路由策略可以这样设计：短问题、命中高置信资料、无敏感数据，走低成本生成模型；长问题、多文档、多约束，走长上下文模型；用户要求生成可对外发布答案，走更强模型并启用引用校验；资料等级敏感时，只允许指定供应商或本地模型；模型返回引用不完整时，不直接输出，而是触发补证据或提示资料不足。
降级策略要保护引用。若强模型不可用，备用模型必须同样支持足够上下文和引用格式。若备用模型无法保证引用，则可以返回“当前只能提供资料摘要，暂不生成确定结论”，而不是生成没有依据的完整答案。对知识库问答来说，低质量完整回答比诚实的不完整回答更危险。
计费报表要按知识库、用户、问题类型和模型步骤分摊。很多团队只统计最终生成成本，忽略查询改写、重排、校验和失败重试。真实成本应覆盖整条链路。只有看清每一步费用，才能决定是优化分块、减少召回、换模型、加缓存，还是减少不必要的校验。
案例：代码助手网关怎么设计
代码助手对模型网关提出更高要求。它不只是问答，还涉及文件读取、补丁生成、命令执行、错误解释、测试反馈和多轮修复。模型选择要考虑代码能力、长上下文、工具调用、输出稳定性、成本和速度。GLM、MiniMax、Kimi、Qwen、Claude、OpenAI Codex 系列等都可能进入候选池，但不能用品牌印象替代任务评测。
网关应把代码任务分层。代码解释、注释生成、简单重构建议，可以走中等模型。多文件重构、复杂错误修复、长程 Agent 任务，应走代码能力强、工具调用稳定、输出上限足够的模型。批量代码文档可以走低成本模型，但写入仓库前需要差异审查。
工具权限必须严格。模型可以读取允许范围内的文件，可以生成补丁，可以请求运行测试，但不能无限制执行任意命令。高风险命令、删除文件、修改配置、推送代码、生产部署，都应由业务编排层或人工确认控制。网关记录模型请求工具的意图和参数，执行权限由工具服务决定。
代码助手的重试策略也要特殊。模型生成补丁失败，不一定要换供应商；有时把测试错误反馈给同一模型更有效。接口超时可以降级，补丁质量差则应进入评测反馈，不应靠重试刷出一个看似可用答案。代码任务的完成标准必须是测试、构建或审查证据，而不是模型说“已完成”。
案例：多供应商客服助手怎么设计
客服助手通常有高并发、低成本、强权限和高可用要求。大多数问题是低风险重复问答，可以用便宜模型加知识库；少数问题涉及退款、投诉、合同、隐私和升级工单，需要更强模型和人工确认。模型网关要把这些任务分开。
入口先做意图分类和风险分级。普通 FAQ 走 support_fast，复杂投诉走 support_strong，包含图片凭证走 support_vision，涉及退款动作走 support_draft_only。模型可以生成建议和草稿，但真实退款、补偿、改订单、改会员等级必须由客服系统确认。
高峰期可以降级普通问题，但不能让高风险问题悄悄走弱模型。比如促销期间请求量暴增，网关可以把普通咨询切到低成本模型，把答案长度限制得更短，把非实时总结任务排队；但退款审核仍应保留强模型或人工路径。可用性策略要服务业务优先级。
客服场景的审计尤其重要。用户之后追问“为什么这样答复”，系统要能查到当时使用的资料版本、模型建议、客服是否修改、最终发送内容和业务动作结果。网关记录 AI 调用，客服系统记录最终对话和操作，两者通过工单 ID 关联。
常见误区
第一个误区是把网关做成纯代理。纯代理只能隐藏供应商 URL，不能解决路由、预算、审计、降级和质量问题。若业务仍然直接传供应商模型名，仍然自己处理错误，仍然自己算成本，网关价值很有限。
第二个误区是过度追求“完全兼容”。不同模型能力本来就不同。把所有模型强行压成同一接口，容易丢失能力，也容易制造假兼容。正确做法是统一常用入口，同时暴露能力声明和任务约束。
第三个误区是无条件降级。主模型失败后换任意便宜模型，可能让高风险任务输出低质量答案。降级必须受任务等级、能力要求和数据策略约束。
第四个误区是重试没有成本意识。三次重试看似稳，若一次请求本来就很贵，重试会把费用放大数倍。重试要按错误分类、预算和总耗时控制。
第五个误区是只看 token 单价。便宜模型如果需要更长提示词、更多修复、更低缓存命中、更高失败率，真实成本可能并不低。模型网关要统计端到端成本，而不是只看价格表。
第六个误区是日志保存过多。完整保存所有输入输出会带来隐私和合规风险。审计要可用，但要最小化、加密和分权。
第七个误区是把模型网关当作评测替代品。网关能记录结果，不能自动证明哪个模型更好。模型选择仍需要离线评测、线上灰度、用户反馈和业务验收。
落地路径：从一天可用到生产可控
第一天要先做统一出口。所有 AI 调用先经过一个后端服务，供应商密钥集中放置，业务服务不再直连外部模型。这个阶段先记录请求 ID、应用、用户、模型、token、耗时和错误。即使路由还很简单，也要先让流量可见。
第一周要做模型别名和基础预算。把业务里的模型 ID 替换成内部别名，建立任务类型和模型候选配置。按应用和用户设置每日或每月预算，超出后拒绝或降级。同步建立基础报表：调用量、费用、错误率、平均延迟、最贵功能。
第一个月要做重试、降级和审计。按错误分类实现可重试策略；为核心别名配置备用模型；为高风险任务记录完整路由证据和业务关联 ID。此时不要追求复杂自动路由，先确保失败路径可解释。
第二个月开始做评测和灰度。为主要任务建立小型评测集，记录不同模型在中文长文、代码、推理、工具调用、多模态上的表现。新模型先进入灰度别名，观察质量、延迟、成本和失败类型，再逐步替换默认模型。
长期要把网关和产品运营连起来。产品经理能看到功能成本，工程团队能看到错误和延迟，财务能看到供应商账单和内部分摊，安全团队能看到数据出域和审计记录。模型网关不只是基础设施，也是 AI 产品运营的控制台。
检查清单
上线前检查：所有业务 AI 调用是否经过统一出口；前端是否完全不接触供应商密钥；业务代码是否不再写死供应商模型名；每个内部模型别名是否有负责人、候选模型、上下文上限、输出上限、价格和降级策略。
路由检查：是否按任务类型选择模型；是否按数据等级过滤供应商；是否按上下文、图片、工具调用和结构化输出能力过滤模型；是否支持灰度；是否记录实际命中模型和策略版本。
失败检查：是否区分 429、5xx、超时、输入超长、参数不支持、鉴权失败、余额不足、内容拒绝；是否限制最大重试次数和总耗时；是否有熔断；是否能在降级后记录完整路径。
计费检查：是否记录输入 token、输出 token、缓存命中、工具费用和最终成本；是否能按租户、用户、功能、任务、模型别名和供应商汇总；是否有预算上限和告警；是否能解释重试带来的额外费用。
审计检查：是否记录请求元数据、路由决策、模型版本、提示词版本、错误、重试、降级和工具调用；是否避免在普通日志中保存敏感原文；是否支持加密、权限控制和保留期限；是否能用业务 ID 追溯最终结果。
质量检查：是否有每个核心任务的评测集；是否能比较模型切换前后的通过率、成本和延迟；是否有用户反馈入口；是否把失败样本沉淀到评测集中；是否能快速回滚模型别名版本。
结语
模型网关的本质，是把不可控的模型调用变成可治理的生产能力。统一 API 只是起点，真正重要的是路由、降级、重试、计费、审计、安全、缓存、评测和回滚。模型越多，供应商变化越快，业务越依赖 AI，这一层就越重要。
好的模型网关不会让团队忘记模型差异，而是让差异变得可配置、可观察、可验证。它让业务应用专注用户任务，让模型策略独立演进，让成本和风险有据可查。对中文 AI 应用团队来说，这也是从“能调用模型”走向“能长期运营 AI 能力”的关键一步。
参考资料
- OpenAI API Pricing：https://platform.openai.com/docs/pricing/
- OpenAI Responses API Reference：https://platform.openai.com/docs/api-reference/responses
- OpenAI Function Calling Guide：https://developers.openai.com/api/docs/guides/function-calling
- OpenAI Rate Limits Guide：https://developers.openai.com/api/docs/guides/rate-limits
- Anthropic API Rate Limits：https://docs.anthropic.com/en/api/rate-limits
- Anthropic Claude Pricing：https://docs.claude.com/en/docs/about-claude/pricing
- Google Gemini API Pricing：https://ai.google.dev/gemini-api/docs/pricing
- LiteLLM Router and Load Balancing：https://docs.litellm.ai/docs/routing
- LiteLLM Virtual Keys：https://docs.litellm.ai/docs/proxy/virtual_keys
- LiteLLM Fallbacks：https://docs.litellm.ai/docs/proxy/reliability
- Portkey AI Gateway：https://portkey.ai/docs/product/ai-gateway
- Portkey Fallbacks：https://portkey.ai/docs/product/ai-gateway/fallbacks
- Kong AI Gateway：https://docs.konghq.com/gateway/latest/ai-gateway/
- Envoy Gateway Rate Limit Observability：https://gateway.envoyproxy.io/latest/tasks/observability/rate-limit-observability/
- DeepSeek 模型与价格：https://api-docs.deepseek.com/zh-cn/quick_start/pricing
- Kimi K2.6 API Guide：https://platform.kimi.ai/docs/guide/kimi-k2-6-quickstart
- Z.AI Pricing：https://docs.z.ai/guides/overview/pricing
- MiniMax API Pay as You Go：https://platform.minimax.io/docs/guides/pricing-paygo