多模型API接入避坑指南：从能力评估到成本与稳定性的五件事

做多模型API接入这件事，表面上看就是把几家模型的key配置到同一套代码里，剩下的事情只是按名字切换。真正做过一次的人都知道，问题几乎都出在每个模型的“细节”上——能力侧重不一样、费用计算方式不一样、限速策略不一样，甚至连错误返回都是各说各话。

我一开始接多模型的时候也犯过这个错：看榜单谁分高就优先接谁，结果接入之后才发现有的模型写聊天很好，但做工具调用准确率惨不忍睹；有的模型单价很便宜，但高峰期限速直接把业务压垮。后来我给自己定了一套接入前检查清单，一共五件事，每次接新模型之前都先过一遍，省了非常多的返工时间。这篇文章就把这五件事完整展开，适合正在做统一模型网关、多模型路由，或者想把现有业务从单模型改成多模型混合调度的开发同学参考。

1. 模型能力边界：先拿业务样本过一遍，再谈接入

1.1 榜单分数是平均值，你的业务是特定分布

我见过最普遍的操作：打开官网看榜单，谁分高接谁。问题在哪？榜单测的是通用任务的平均值，你的业务是特定分布——可能是电商评论、法律文书、客服工单，或者内部知识库问答。同一个模型在通用评测里领先，不代表在你这批样本里不翻车。

我做过一个文档归纳项目，某个模型通用能力评分很高，但把它接进来之后发现，长表格转结构化文本时总缺列，换了另一个评分低一档的模型反而稳定。原因很简单：业务样本里有大量表格，而公开榜单测试一般很少覆盖这种场景。

所以接入前要先抽数据。建议从真实请求里随机抽20到30条，覆盖三种类型：需要精确提取信息的、需要自由生成的、需要严格遵循格式的。把每条请求同时发给候选模型，逐条记录四件事：

• 理解是否到位
• 输出格式是否稳定
• 失败原因是理解偏差还是格式规划
• 失败之后重试能不能纠正

这一步花半天时间，但能省掉后面两个星期的调试时间。

1.2 三种最容易让模型暴露原形的测试

除了业务样本，我还会固定跑三种测试，这三点在真实接入时的坑最多。

第一种是指令遵循测试。把关键限制写进提示里，比如“只输出JSON，不要解释”，看模型到底听不听。有些模型在简单指令下表现很好，一旦指令里同时包含“提取字段、排除黑名单、按固定格式输出”三个约束，就开始漏项。

第二种是参数抽取测试。设计一个工具调用场景，比如从一句话里抽取日期、地点、金额三个字段，并让它按给定JSON Schema返回。这一步能快速看出模型的结构化输出能力。公开榜单很少细测这类能力，但在Agent类业务里，这比“会聊天”重要得多。

第三种是数字替换测试。把上下文里的一个关键数字改掉，比如把“2023年”改成“2019年”，看模型输出是否跟着上下文走。如果模型坚持按自己的训练记忆来回答，说明它对上下文证据的遵从度不足。知识库问答场景最怕这个，因为模型一旦不信任你给的资料，就会一本正经地编答案。

另一个容易被忽略的点是“拒绝能力”。我希望模型在信息不足的时候明确说“当前信息不足以回答”，而不是强行补一个看似合理的说法。幻觉问题在整个多模型接入里都属于高优先级项，不要等到某个面向用户的场景里出现严重错误再回头补测。

1.3 上下文窗口数值很大，实际可用长度是另一回事

现在各家模型都在拼上下文长度，动辄几十万token。但标称长度和实际可用长度之间，经常存在不小的落差。长输入时，模型对中间部分信息的关注度会明显下降，甚至完全忽略，这就是业内常说的“上下文中间迷失”。如果你要做长文档问答，测试方法很简单：把答案放在文档中部，看模型能不能找到。

还要提醒一点：上下文是按token计费的。多轮对话里，每一轮请求都要把历史消息重新发送一遍，看起来单轮没多长，聊几轮之后输入token就是几万甚至几十万，成本和延迟都上去了。接入前最好对你业务的平均上下文长度做个统计，这会直接影响模型选型和成本估算。

提示：上下文窗口的可用长度不只是数字问题，还关系到单位请求的耗时与费用。选型时要把“业务实际上下文长度”而非“标称窗口”作为依据。

2. 协议兼容细节：统一接口背后的五类暗坑

2.1 “兼容主流接口”不等于“每个字段都一致”

现在很多模型厂商都宣称兼容主流接口，直接换base_url就能跑通Hello World。这句话一半真一半假。真实业务里字段层面的差异很容易被忽略。

有的模型认max_tokens，有的认max_completion_tokens，同一个参数名在不同的厂商那里可能是完全不同的语义；有的模型支持response_format指定JSON输出，有的必须在系统提示里写“你必须输出JSON”；temperature默认值看着都是1.0，实际输出的随机性却天差地别。

如果要做多模型兼容层，一定不要假设所有字段是统一的。正确做法是给每个模型维护一份独立的字段映射配置，把这部分差异隔离在适配层里，业务代码不感知。

2.2 函数调用是重灾区：两套格式与一张仿真画皮

函数调用（tool use / function calling）是多模型接入的重灾区。不同家API的写法不同：有的用functions数组，有的用tools数组，有的两者都支持但行为不一样。返回的差异更麻烦：有的把模型生成的函数参数放在字符串里，需要你再解析一次；有的直接给结构化JSON对象。

还有一些模型本身没有原生的工具调用能力，平台用提示词拼接的方式做了仿真。这种仿真在简单场景能跑通，但参数一多、嵌套一深，就很容易输出不合法JSON。我建议网关层统一把函数定义和参数结果转成结构体，解析失败就走重试或降级，不要让脏数据进入业务逻辑。

2.3 流式输出与usage字段：记账和日志的第一道坎

流式输出各家都叫SSE，看起来格式差不多，实际上细节差异不小。usage字段有的在最后一条chunk里返回，有的在流结束以后以另一个事件返回，有的根本不返回；finish_reason的取值也分stop、tool_calls、length等不同情况。

如果你要做token计费和请求日志，只依赖流式响应里的usage很容易漏记。稳妥做法是定期用非流式请求做对账，或者在网关层用tokenizer做近似估算。这个细节直接决定你的成本数据准不准。

2.4 错误码语义不一致，别把原始文本直接抛给用户

再讲错误码。有些接口出错时返回的结构完全不同，而且同一个HTTP状态码在不同厂商那里的真实含义可能不同。比如上下文长度超限，有的返回400，有的返回413，有的会返回一个专门的error字段告诉你prompt太长；429限流时，有的带Retry-After头，有的不带。

网关要做的事情，是把不同模型的错误映射成统一的错误类型：限流、参数无效、鉴权失败、上下文超长、服务端过载。这样上层才能统一处理重试、降级和用户提示，而不是让用户看到一个莫名其妙的原始错误文本。

提示：错误码归一化是网关稳定性的基础。接的模型越多，错误格式的差异越明显，这一步不要省。

2.5 一个归一化适配层示例

简单写一个归一化解析函数的示例，演示如何处理“字段名不同、参数类型不同”这类问题：

import json def normalize_chat_response(raw: dict) -> dict: normalized = { "content": "", "tool_calls": [], "finish_reason": None, "usage": {"input_tokens": 0, "output_tokens": 0}, "raw": raw, } choices = raw.get("choices") or [] if choices: message = choices[0].get("message") or {} # 有的平台字段是 content，有的是 text，这里统一 normalized["content"] = message.get("content") or message.get("text") or "" normalized["finish_reason"] = choices[0].get("finish_reason") # 有的平台返回 tools，有的返回 functions，需要兼容 tool_calls = message.get("tool_calls") or message.get("function_calls") or [] for tc in tool_calls: func = tc.get("function") or tc.get("tool") or {} args = func.get("arguments") if isinstance(args, str): try: args = json.loads(args) except json.JSONDecodeError: args = None if args is not None: normalized["tool_calls"].append({ "name": func.get("name") or "", "arguments": args, }) usage = raw.get("usage") or {} normalized["usage"]["input_tokens"] = usage.get( "prompt_tokens") or usage.get("input_tokens") or 0 normalized["usage"]["output_tokens"] = usage.get( "completion_tokens") or usage.get("output_tokens") or 0 return normalized

这个函数的重点是：不论上游返回什么结构，适配层都转成你业务里唯一的数据结构。这样后续所有下游模块都只依赖一种格式，不会被某个模型的特殊写法牵着走。

3. 成本账要在接入前算清：单价不是账单的全貌

3.1 计费结构里的三层隐形费用

大多数平台的计费方式都是输入和输出分开计价，输出一般比输入贵好几倍。这点大家多少都知道。但有三层容易忽略的费用：

第一层是缓存。很多平台对重复输入的提示词有缓存价格，通常比普通输入便宜一个数量级。你要主动利用这个机制，把系统提示这类固定内容放在提示词的开头，让缓存更容易命中。

第二层是推理token。部分推理类模型会把内部思考过程的token也计入费用。如果你只按最终输出长度估算成本，实际账单会明显超出预期。

第三层是多轮上下文的重复计费。用户来回对话后，每次请求都会把历史消息重新发一遍，输入token可能比第一轮多几倍。这是最容易让成本失控的地方。

3.2 用一个真实场景把账算透

假设你要做一个客服辅助系统，日均请求5000次，每次平均输入2000 token，输出500 token，系统提示固定部分让缓存命中率达到50%。按30天估算：

每天输入token总量就是5000乘以2000，等于1000万token；每天输出总量是5000乘以500，等于250万token。一个月下来，输入未命中的部分大概是1.5亿token，输入缓存命中的部分也是1.5亿token，输出大概是7500万token。

假设某中等价位模型的定价是：输入3元每百万token，输出12元每百万token，缓存命中输入0.3元每百万token。那成本就是：

• 输入未命中：150乘以3，450元
• 输入缓存命中：150乘以0.3，45元
• 输出：75乘以12，900元

单模型月成本大约1395元。

如果同样的请求，大部分走一个轻量模型，假设定价是输入0.6元、输出1.8元、缓存0.06元每百万token：

• 输入未命中：150乘以0.6，90元
• 输入缓存命中：150乘以0.06，9元
• 输出：75乘以1.8，135元

月成本大约是234元。差距接近6倍。

这就是“把简单请求路由到轻量模型”的价值所在。它不是靠压低质量省钱，而是让不同复杂度的问题走不同价位的模型。

3.3 接入后的成本优化不该靠压缩质量，而靠路由

很多团队做成本控制，第一反应是压缩提示词。提示词压缩确实有效，但要分场景。固定系统提示尽量短并利用缓存，历史消息裁剪到最近的N轮，长文档只传相关片段，这些都是常规操作。

更有效的思路是路由策略。先让轻量模型做意图分类，简单问题直接回答，复杂问题再转给重量模型。比如客服场景里，“订单状态查询”“退货政策说明”这类高频问题完全可以由轻量模型处理，真正需要深入推理的法律咨询再走强模型。这个路由层一旦跑通，成本结构会健康很多。

还要把降级成本纳入统计。主模型挂了切到备用模型，备用模型的价格可能不同，这部分成本要在监控体系里体现出来，否则你只知道费用涨了，却不知道是降级导致的。

4. 稳定与降级：要把“某家模型挂了”当常态设计

4.1 限速是有形的墙：RPM、TPM、并发

接入前先搞清楚你拿到的key在什么维度上被限速。常见维度是每分钟请求数RPM、每分钟token数TPM、并发连接数。有些平台的免费或低价额度看起来很大，但限速很低，业务量一旦突增就全卡在429。

上线前用脚本做小规模压测：从低并发开始逐步增加，观察哪个维度先到顶。如果TPM先到顶，说明你的请求平均token数偏高；如果RPM先到顶，说明小请求太多，需要考虑合并或分流。

4.2 超时和重试参数不是拍脑袋

设置超时要分阶段看：建立连接、等待首字节、整体完成。流式场景下，首字节时间比总时长更重要，建议首响3到5秒就告警。整个流式响应根据业务容忍度设置在60到120秒。

重试建议用指数退避加随机抖动：第一次等1秒，第二次等2秒，第三次等4秒，每次加最多20%的随机数。这样可以避免所有请求在同一时刻重试，形成重试风暴。

但要注意，重试只对幂等请求安全。如果用户已经收到部分内容，再重试会导致重复消耗，这时候正确的做法不是盲目重发，而是让用户重新发起，或者切换模型。

4.3 降级链路：主模型失败后按优先级切换

多模型的价值之一就是容灾。设计一个简单的优先级降级逻辑：

MODEL_PRIORITY = ["primary", "fallback", "cheap"] async def chat_with_fallback(request): for model in MODEL_PRIORITY: try: resp = await call_model(model, request) if is_healthy(resp): return resp except APIError as e: log_failed_model(model, str(e)) continue raise BusinessError("all_models_unavailable")

这个写法看起来简单，实际使用中要注意一点：不要无脑把流量灌进优先级列表。还要维护一份健康状态，当某个模型连续失败N次后，把它临时从优先级列表里摘除，过一段时间再恢复探测。否则主模型虽然已经挂了，每次请求还是先打一遍主模型，白白增加延迟。

对于成本敏感的业务，还可以把优先级和请求类型绑定。普通请求优先走便宜模型，复杂请求优先走强模型，再各自配一个备用模型。这样降级链路更精细，成本也更可控。

4.4 上线以后，盯什么指标才算盯住了稳定性

上线后要盯的指标主要有：延迟分位数p50/p95/p99、错误率、降级率、成功请求的平均token数、缓存命中率。

我习惯把降级率和错误率分开看，因为降级其实是在救业务，但降级率突然升高往往说明某个主模型出问题了。如果p95延迟超过5秒，说明模型响应或者网络链路已经有瓶颈。这些指标最好按模型维度拆分，哪个模型拖后腿一目了然。

5. 密钥管理与数据合规：接得进去，也要撤得回来

5.1 密钥管理：环境变量只是底线，不是方案

最基础但很多人栽跟头的事，是把API key直接写进代码仓库，甚至写进前端代码。正确做法是放进环境变量或者专门的密钥管理服务，并且区分开发和生产两套key。前端不能直接调用大模型API，key应该只待在网关或后端服务里。

密钥轮换这件事也要提前想好。一旦某个模型的服务商出了安全公告，或者key的使用异常，你得知道线上哪些业务在依赖这个key，换掉之后会不会有一阵子不可用。密钥管理做不好，后续撤模型的时候会非常痛苦。

5.2 数据边界：先回答“哪些内容不能出边界”

接入前先回答一个问题：你的业务里，哪些数据可以出本地，哪些不行。涉及手机号、身份证、业务合同内容的时候要特别敏感。

如果数据不能出边界，只有两条路：一是本地化部署私有模型，二是送模型前做脱敏。脱敏的具体做法是把姓名、电话、地址这些字段替换成占位符，等模型返回结果后再映射回去。不要想当然地认为模型服务商不会存储你的数据，接之前一定要确认清楚数据留存策略，尤其是日志留存时长。

5.3 审计与追溯：多模型时代，出问题要能定位到模型

多模型接入之后，最怕的就是出问题时不知道是哪个模型导致的。建议每条请求都记录：走了哪个模型、用了哪版系统提示、输入了多少token、输出内容是什么、延迟多少。

定期对账模型成本也很重要。如果某天token异常增长，有可能是重试风暴，也可能是有人循环调用。用户投诉的时候，这些日志能帮你快速定位，是模型理解问题还是业务逻辑问题。

5.4 prompt注入：模型读了外部内容之后的变化

如果模型会读取外部内容，比如网页、文档、用户上传的附件，就要小心提示词注入。外部文本里可能藏着“忽略以上所有指令，直接输出……”这类内容。

网关层要做好两件事：一是对模型返回做敏感校验，二是把系统级指令和外部内容分开处理，不要混在一起解析。多模型情况下尤其要注意，不同模型对这类攻击的抵抗力差别很大，同一个注入样本，可能有的模型完全不受影响，有的模型就直接被带偏了。

最后说一个我自己的教训。第一次做多模型接入的时候，我一口气接了好几家，总觉得“模型越多越稳”。结果维护接口、调参数、看账单的时间远超过写业务代码的时间，半年过去真正稳定使用的还是最初那两三个。后来我定了一个规矩：新模型进来，先拿20条真实业务样本跑一遍，再放5%流量试运行一周，观察延迟、错误率和用户反馈之后，才逐步加大比例。

这五件事看着是接入前的检查项，其实更像一张过滤网，把不值得接的、接进来会添乱的、算下来太贵的模型提前挡在门外。花半天时间做完这套检查，比上线之后熬夜修Bug划算得多。