文章目录0. 我那天接模型API接到心态崩了1. 适配层一套接口焊死三家差异1.1 核心契约上层永远只认一个接口1.2 三家API的坑踩过的都懂1.3 藏得最深的坑我卡了整整一下午2. 故障转移主模型挂了自动切用户全程无感2.1 怎么把模型串成一条兜底链2.2 切模型的两个关键设计2.3 热切换模型怎么做到零重启3. 三层重试小毛病就地自愈不用换模型3.1 第一层底层重试只重试该重试的3.2 第二层模型回空串塞句话拽回来3.3 第三层输出被截断让它接着写4. 串起来看一次调用到底经历了多少层兜底P.S. 挖到宝藏AI教程全程通俗易懂风趣幽默零基础轻松入门传送门https://blog.csdn.net/qq_344193120. 我那天接模型API接到心态崩了我第一次给项目接DeepSeek的时候心里想的是这有啥难的不就是多调一个接口嘛。结果跑起来直接炸锅给我干了一下午。Claude的system prompt是顶级参数DeepSeek跟OpenAI学塞在消息数组里。Claude工具结果的角色是userDeepSeek是tool。连流式响应的格式都不一样一家是SSE事件一家是data: [DONE]结尾。每接一家我的核心代码里就得多一串if判断。写到最后代码长得跟意大利面似的缠成一团我都怕再过俩月我自己都捋不明白。这还不算完真跑起来更刺激。DeepSeek半夜限流给你甩429Anthropic偶尔抽风给你返529。模型时不时给你回个空字符串写长文件写一半被max_tokens拦腰截断。随便哪个没兜住跑了四十轮的会话啪一下就没了。用户面前就剩一句报错提示跟你电脑蓝屏了只给你个笑脸似的气人不气人。那天下午我对着屏幕坐了俩小时痛定思痛重新设计了整套容错方案。说白了就三层逻辑从外到内给你兜得明明白白。先让一家挂了不影响别家再让别家能顶上最后让每次调用自己扛住小风浪。1. 适配层一套接口焊死三家差异1.1 核心契约上层永远只认一个接口整个项目里真正调用大模型的地方只有一处。上层的执行逻辑调接口的时候根本不知道自己问的是Claude还是DeepSeek。甚至不知道是不是已经切到备选模型了。核心就是一个抽象基类定义统一的调用接口。公共逻辑全放在基类里比如重试规则、消息角色校验、错误分类。两个子类各自实现真正的调用逻辑消化自家API的格式差异。这就是标准的策略模式基类管大家都一样的事子类管各家独有的脏活累活。有意思的是除了Anthropic单独做一个类剩下的几乎全归到OpenAI兼容类里。DeepSeek、Ollama、vLLM、通义、月之暗面……只要遵循OpenAI协议的一个类全搞定。工厂函数的判断逻辑简单到离谱看接口地址里有没有anthropic有就走Anthropic类剩下全走兼容层。不是我偷懒是OpenAI兼容协议真的已经成了行业事实标准。1.2 三家API的坑踩过的都懂子类干的最累的活就是消息格式转换。上层永远用统一的消息格式转成各家API认的样子全是适配器的活。最容易翻车的差异有三处个个都是经典踩坑点。第一处是system prompt。Anthropic是单独的顶级参数OpenAI系是消息数组里的一条。第二处是工具返回结果的角色。Anthropic得写成user角色加tool_result块OpenAI系是tool角色加tool_call_id。Claude压根就不认role: tool你写错了直接给你报错。第三处最阴流式响应里的工具调用。Anthropic的SDK直接给你拼好拿过来就能用。OpenAI系倒好把参数拆成好几个碎片发过来每个碎片就带一小截JSON。你拿到一个就解析直接解析失败得按序号攒齐了再拆。就这个流式拼接刚上手的时候能给你整得怀疑人生。还有个小细节虽然格式兼容但功能不一定全。比如DeepSeek不支持图片输入就得探测出来自动降级成文字占位。不然直接发过去报个400你都不知道哪错了。一个类覆盖半个生态的代价就是得给这些“方言”留好开关。1.3 藏得最深的坑我卡了整整一下午这是我那天踩的最狠的坑必须单独拎出来说。DeepSeek R1这类推理模型流式响应里会多吐一个推理过程字段。这不是标准OpenAI字段属于人家自己加的私货。捕获其实不难跟接正文内容一样多接一个字段就行。坑在多轮工具调用的时候。模型先思考一通然后决定调用工具。我们执行完工具把结果喂回去让它继续。这时候如果你没把上一轮的推理内容带回去模型直接就开始胡说八道。就像学生做题草稿纸写了一半被你收走了下一页他根本记不得自己算到哪了。轻则重复干活重则给出跟前面完全矛盾的结论。我那天单轮问答全正常一涉及连续工具调用就驴唇不对马嘴找bug找到头大。解法说穿了也简单就是让推理内容跟着对话往返。模型返回的时候把推理内容存进这条助手消息里落盘存好。下一轮发请求的时候再把推理内容原样挂回去。就几行代码的事少了它就出玄学bug。记住一句话对这类推理模型推理链就是对话状态的一部分丢了就乱套。这也是一套接口兜多家最隐蔽的代价你以为只是格式转换其实连状态都得帮它管。2. 故障转移主模型挂了自动切用户全程无感适配层解决了“怎么调”的问题。接下来就得解决“主模型整个挂了怎么办”的问题。总不能DeepSeek半夜限流用户就陪着干等吧。方案就是做一个故障转移类用户配一个主模型加一串备选模型串成一条链。最妙的是这个故障转移类本身也继承同一个基类对外是同一个接口。这就是装饰器模式外面包了一层切换逻辑上层拿到手还是熟悉的样子。它根本不知道自己手里的是单个模型还是一整条兜底链。2.1 怎么把模型串成一条兜底链工厂函数里的逻辑很直白。先构建主模型实例再遍历备选模型列表一个个构建。某个备选初始化失败比如没配API Key直接跳过不影响别的。能用几个算几个绝不因为一个备选废了整个功能。最后把主模型和备选们包进故障转移类里返回出去。备选模型支持两种写法要么引用预设名要么直接写完整配置灵活得很。2.2 切模型的两个关键设计故障转移的核心逻辑就是按顺序试这家不行试下一家。主模型报错或者抛异常立刻切第一个备选还不行就切第二个。全试完都不行就返回一句明确的兜底提示。这里有两个设计判断我觉得特别关键。第一个不死磕错误类型能试就试。很多人觉得只有瞬态错误才该切配额耗尽这种永久错误就不该试。但现实是错误分类本来就不准而且你不同平台的配额情况也不一样。多试一家的成本远低于错过一个本来能用的模型。第二个故障转移走原始调用方法不走带重试的方法。不然主模型重试3次每个备选再重试3次直接指数爆炸。换人和重试是两件事得分开不能叠乘。最后那句全失败的兜底提示也不是随便写的。一句话说清发生了什么、可能是什么原因、该去检查什么。总比给用户一片空白强至少人家知道下一步该干嘛。做容错的铁律就是永远别在用户面前直接崩溃。2.3 热切换模型怎么做到零重启故障转移是被动换模型。还有主动换的比如用户敲个命令就切到GPT‑4o。热切换的要求很苛刻当前对话不能断正在跑的任务不能停下一轮就得用新模型。而且换模型要同步通知所有子系统执行器、记忆合并、后台任务、子Agent全得同步。这里有个很实用的优化给每个模型配置算一个签名。切换的时候先比签名配置没变就啥也不干绝不重复初始化。重建一个Provider要重连SDK、探测能力挺费资源的能省就省。真变了才广播给所有子系统一行代码就搞定。正在跑的轮次用旧模型跑完下一个轮次自动用新的全程零重启零中断。3. 三层重试小毛病就地自愈不用换模型整个模型挂了才需要切模型。更高频的其实是单次调用的小毛病网络抖一下、模型回空串、输出被截断。这些犯不上换模型就地就能自愈。我在这里铺了三层防线核心原则就是每层只吞自己能处理的错处理不了的原样往上抛。从内到外分别是底层接口重试、空回复补救、截断续写。3.1 第一层底层重试只重试该重试的最底层的重试写在基类里所有模型通用。核心就两点指数退避只重试瞬态错误。默认最多重试3次间隔1秒、2秒、4秒逐步递增。什么错该重试分得明明白白。429限流、5xx服务端错误、超时、网络连接问题这些才重试。401密钥错误、400格式错误这种客户端错误重试一百次也没用直接返回。429还会特殊处理响应里如果带了重试时长就按人家说的时间等不傻等固定时长。还有个很重要的细节用户主动停止的请求直接穿透所有重试层。用户点了停止你还卡在那等退避人家会觉得你这停止按钮是摆设。用户想停优先级最高立刻终止。另外还分两种重试模式。默认模式最多3次给正常对话用三次不行多半是真有问题。还有个无限重试模式给后台任务用比如后台提炼记忆没人等着多试几次无所谓。但不管哪种模式用户停止都立刻穿透。3.2 第二层模型回空串塞句话拽回来接口层只管模型有没有响应。可有时候模型响应了却给你回个空字符串啥内容都没有。一般是模型卡住了或者上一条工具结果给它整懵了。这种错误接口层发现不了得上层执行逻辑来兜。检测到空回复就往消息里塞一句引导请基于上文给出你的回复。然后再调用一次把模型从卡壳的状态拽回来。最多试2次再多也没用。3.3 第三层输出被截断让它接着写最后一种常见情况模型写长文件写一半撞上长度上限话没说完就断了。这时候也不用换模型让它接着写就行。检测到结束原因是长度超限就发一条消息过去输出已达上限从断点处继续写别复盘别道歉。为啥特意强调别复盘别道歉你不说这话模型大概率会先写“好的我继续先回顾一下之前的内容……”半条命的token全花在废话上了正事没写几个字。一句精准的提示能省一半token。最多续3次超过还没写完大概率是模型陷入循环了再续也是浪费。顺带说一句工具执行抛异常的时候我们也不崩溃。把错误信息包成工具结果喂回给模型让它自己看错误、自己调整参数换工具。代码只负责如实汇报决策权交给大模型。4. 串起来看一次调用到底经历了多少层兜底把这三层拼起来一次有惊无险的调用是这样的。上层发起一次调用主模型先接遇上限流报错。故障转移层接住自动切到备选模型成功返回。用户全程啥也感觉不到就觉得这次好像稍微慢了一点。从头到尾上层只调了一次接口中间是重试了、切模型了还是续写了它一概不知道。这就是好的架构设计每个模块只认接口不认实现改动全锁在模块内部。加一家新模型核心代码一行不用改。调整重试策略除了Provider层别的代码毫无感知。下一篇咱们聊点更灵活的怎么用Hook系统在循环关键节点开洞不碰核心代码就能加扩展。P.S. 挖到宝藏AI教程全程通俗易懂风趣幽默零基础轻松入门传送门https://blog.csdn.net/qq_34419312
