文章目錄0. 我那天接模型API接到心態(tài)崩了1. 適配層一套接口焊死三家差異1.1 核心契約上層永遠(yuǎn)只認(rèn)一個(gè)接口1.2 三家API的坑踩過(guò)的都懂1.3 藏得最深的坑我卡了整整一下午2. 故障轉(zhuǎn)移主模型掛了自動(dòng)切用戶全程無(wú)感2.1 怎么把模型串成一條兜底鏈2.2 切模型的兩個(gè)關(guān)鍵設(shè)計(jì)2.3 熱切換模型怎么做到零重啟3. 三層重試小毛病就地自愈不用換模型3.1 第一層底層重試只重試該重試的3.2 第二層模型回空串塞句話拽回來(lái)3.3 第三層輸出被截?cái)嘧屗又鴮?xiě)4. 串起來(lái)看一次調(diào)用到底經(jīng)歷了多少層兜底P.S. 挖到寶藏AI教程全程通俗易懂風(fēng)趣幽默零基礎(chǔ)輕松入門(mén)傳送門(mén)https://blog.csdn.net/qq_344193120. 我那天接模型API接到心態(tài)崩了我第一次給項(xiàng)目接DeepSeek的時(shí)候心里想的是這有啥難的不就是多調(diào)一個(gè)接口嘛。結(jié)果跑起來(lái)直接炸鍋給我干了一下午。Claude的system prompt是頂級(jí)參數(shù)DeepSeek跟OpenAI學(xué)塞在消息數(shù)組里。Claude工具結(jié)果的角色是userDeepSeek是tool。連流式響應(yīng)的格式都不一樣一家是SSE事件一家是data: [DONE]結(jié)尾。每接一家我的核心代碼里就得多一串if判斷。寫(xiě)到最后代碼長(zhǎng)得跟意大利面似的纏成一團(tuán)我都怕再過(guò)倆月我自己都捋不明白。這還不算完真跑起來(lái)更刺激。DeepSeek半夜限流給你甩429Anthropic偶爾抽風(fēng)給你返529。模型時(shí)不時(shí)給你回個(gè)空字符串寫(xiě)長(zhǎng)文件寫(xiě)一半被max_tokens攔腰截?cái)唷ｋS便哪個(gè)沒(méi)兜住跑了四十輪的會(huì)話啪一下就沒(méi)了。用戶面前就剩一句報(bào)錯(cuò)提示跟你電腦藍(lán)屏了只給你個(gè)笑臉?biāo)频臍馊瞬粴馊?。那天下午我?duì)著屏幕坐了倆小時(shí)痛定思痛重新設(shè)計(jì)了整套容錯(cuò)方案。說(shuō)白了就三層邏輯從外到內(nèi)給你兜得明明白白。先讓一家掛了不影響別家再讓別家能頂上最后讓每次調(diào)用自己扛住小風(fēng)浪。1. 適配層一套接口焊死三家差異1.1 核心契約上層永遠(yuǎn)只認(rèn)一個(gè)接口整個(gè)項(xiàng)目里真正調(diào)用大模型的地方只有一處。上層的執(zhí)行邏輯調(diào)接口的時(shí)候根本不知道自己?jiǎn)柕氖荂laude還是DeepSeek。甚至不知道是不是已經(jīng)切到備選模型了。核心就是一個(gè)抽象基類定義統(tǒng)一的調(diào)用接口。公共邏輯全放在基類里比如重試規(guī)則、消息角色校驗(yàn)、錯(cuò)誤分類。兩個(gè)子類各自實(shí)現(xiàn)真正的調(diào)用邏輯消化自家API的格式差異。這就是標(biāo)準(zhǔn)的策略模式基類管大家都一樣的事子類管各家獨(dú)有的臟活累活。有意思的是除了Anthropic單獨(dú)做一個(gè)類剩下的幾乎全歸到OpenAI兼容類里。DeepSeek、Ollama、vLLM、通義、月之暗面……只要遵循OpenAI協(xié)議的一個(gè)類全搞定。工廠函數(shù)的判斷邏輯簡(jiǎn)單到離譜看接口地址里有沒(méi)有anthropic有就走Anthropic類剩下全走兼容層。不是我偷懶是OpenAI兼容協(xié)議真的已經(jīng)成了行業(yè)事實(shí)標(biāo)準(zhǔn)。1.2 三家API的坑踩過(guò)的都懂子類干的最累的活就是消息格式轉(zhuǎn)換。上層永遠(yuǎn)用統(tǒng)一的消息格式轉(zhuǎn)成各家API認(rèn)的樣子全是適配器的活。最容易翻車的差異有三處個(gè)個(gè)都是經(jīng)典踩坑點(diǎn)。第一處是system prompt。Anthropic是單獨(dú)的頂級(jí)參數(shù)OpenAI系是消息數(shù)組里的一條。第二處是工具返回結(jié)果的角色。Anthropic得寫(xiě)成user角色加tool_result塊OpenAI系是tool角色加tool_call_id。Claude壓根就不認(rèn)role: tool你寫(xiě)錯(cuò)了直接給你報(bào)錯(cuò)。第三處最陰流式響應(yīng)里的工具調(diào)用。Anthropic的SDK直接給你拼好拿過(guò)來(lái)就能用。OpenAI系倒好把參數(shù)拆成好幾個(gè)碎片發(fā)過(guò)來(lái)每個(gè)碎片就帶一小截JSON。你拿到一個(gè)就解析直接解析失敗得按序號(hào)攢齊了再拆。就這個(gè)流式拼接剛上手的時(shí)候能給你整得懷疑人生。還有個(gè)小細(xì)節(jié)雖然格式兼容但功能不一定全。比如DeepSeek不支持圖片輸入就得探測(cè)出來(lái)自動(dòng)降級(jí)成文字占位。不然直接發(fā)過(guò)去報(bào)個(gè)400你都不知道哪錯(cuò)了。一個(gè)類覆蓋半個(gè)生態(tài)的代價(jià)就是得給這些“方言”留好開(kāi)關(guān)。1.3 藏得最深的坑我卡了整整一下午這是我那天踩的最狠的坑必須單獨(dú)拎出來(lái)說(shuō)。DeepSeek R1這類推理模型流式響應(yīng)里會(huì)多吐一個(gè)推理過(guò)程字段。這不是標(biāo)準(zhǔn)OpenAI字段屬于人家自己加的私貨。捕獲其實(shí)不難跟接正文內(nèi)容一樣多接一個(gè)字段就行?？釉诙噍喒ぞ哒{(diào)用的時(shí)候。模型先思考一通然后決定調(diào)用工具。我們執(zhí)行完工具把結(jié)果喂回去讓它繼續(xù)。這時(shí)候如果你沒(méi)把上一輪的推理內(nèi)容帶回去模型直接就開(kāi)始胡說(shuō)八道。就像學(xué)生做題草稿紙寫(xiě)了一半被你收走了下一頁(yè)他根本記不得自己算到哪了。輕則重復(fù)干活重則給出跟前面完全矛盾的結(jié)論。我那天單輪問(wèn)答全正常一涉及連續(xù)工具調(diào)用就驢唇不對(duì)馬嘴找bug找到頭大。解法說(shuō)穿了也簡(jiǎn)單就是讓推理內(nèi)容跟著對(duì)話往返。模型返回的時(shí)候把推理內(nèi)容存進(jìn)這條助手消息里落盤(pán)存好。下一輪發(fā)請(qǐng)求的時(shí)候再把推理內(nèi)容原樣掛回去。就幾行代碼的事少了它就出玄學(xué)bug。記住一句話對(duì)這類推理模型推理鏈就是對(duì)話狀態(tài)的一部分丟了就亂套。這也是一套接口兜多家最隱蔽的代價(jià)你以為只是格式轉(zhuǎn)換其實(shí)連狀態(tài)都得幫它管。2. 故障轉(zhuǎn)移主模型掛了自動(dòng)切用戶全程無(wú)感適配層解決了“怎么調(diào)”的問(wèn)題。接下來(lái)就得解決“主模型整個(gè)掛了怎么辦”的問(wèn)題?？偛荒蹹eepSeek半夜限流用戶就陪著干等吧。方案就是做一個(gè)故障轉(zhuǎn)移類用戶配一個(gè)主模型加一串備選模型串成一條鏈。最妙的是這個(gè)故障轉(zhuǎn)移類本身也繼承同一個(gè)基類對(duì)外是同一個(gè)接口。這就是裝飾器模式外面包了一層切換邏輯上層拿到手還是熟悉的樣子。它根本不知道自己手里的是單個(gè)模型還是一整條兜底鏈。2.1 怎么把模型串成一條兜底鏈工廠函數(shù)里的邏輯很直白。先構(gòu)建主模型實(shí)例再遍歷備選模型列表一個(gè)個(gè)構(gòu)建。某個(gè)備選初始化失敗比如沒(méi)配API Key直接跳過(guò)不影響別的。能用幾個(gè)算幾個(gè)絕不因?yàn)橐粋€(gè)備選廢了整個(gè)功能。最后把主模型和備選們包進(jìn)故障轉(zhuǎn)移類里返回出去。備選模型支持兩種寫(xiě)法要么引用預(yù)設(shè)名要么直接寫(xiě)完整配置靈活得很。2.2 切模型的兩個(gè)關(guān)鍵設(shè)計(jì)故障轉(zhuǎn)移的核心邏輯就是按順序試這家不行試下一家。主模型報(bào)錯(cuò)或者拋異常立刻切第一個(gè)備選還不行就切第二個(gè)。全試完都不行就返回一句明確的兜底提示。這里有兩個(gè)設(shè)計(jì)判斷我覺(jué)得特別關(guān)鍵。第一個(gè)不死磕錯(cuò)誤類型能試就試。很多人覺(jué)得只有瞬態(tài)錯(cuò)誤才該切配額耗盡這種永久錯(cuò)誤就不該試。但現(xiàn)實(shí)是錯(cuò)誤分類本來(lái)就不準(zhǔn)而且你不同平臺(tái)的配額情況也不一樣。多試一家的成本遠(yuǎn)低于錯(cuò)過(guò)一個(gè)本來(lái)能用的模型。第二個(gè)故障轉(zhuǎn)移走原始調(diào)用方法不走帶重試的方法。不然主模型重試3次每個(gè)備選再重試3次直接指數(shù)爆炸。換人和重試是兩件事得分開(kāi)不能疊乘。最后那句全失敗的兜底提示也不是隨便寫(xiě)的。一句話說(shuō)清發(fā)生了什么、可能是什么原因、該去檢查什么。總比給用戶一片空白強(qiáng)至少人家知道下一步該干嘛。做容錯(cuò)的鐵律就是永遠(yuǎn)別在用戶面前直接崩潰。2.3 熱切換模型怎么做到零重啟故障轉(zhuǎn)移是被動(dòng)換模型。還有主動(dòng)換的比如用戶敲個(gè)命令就切到GPT?4o。熱切換的要求很苛刻當(dāng)前對(duì)話不能斷正在跑的任務(wù)不能停下一輪就得用新模型。而且換模型要同步通知所有子系統(tǒng)執(zhí)行器、記憶合并、后臺(tái)任務(wù)、子Agent全得同步。這里有個(gè)很實(shí)用的優(yōu)化給每個(gè)模型配置算一個(gè)簽名。切換的時(shí)候先比簽名配置沒(méi)變就啥也不干絕不重復(fù)初始化。重建一個(gè)Provider要重連SDK、探測(cè)能力挺費(fèi)資源的能省就省。真變了才廣播給所有子系統(tǒng)一行代碼就搞定。正在跑的輪次用舊模型跑完下一個(gè)輪次自動(dòng)用新的全程零重啟零中斷。3. 三層重試小毛病就地自愈不用換模型整個(gè)模型掛了才需要切模型。更高頻的其實(shí)是單次調(diào)用的小毛病網(wǎng)絡(luò)抖一下、模型回空串、輸出被截?cái)?。這些犯不上換模型就地就能自愈。我在這里鋪了三層防線核心原則就是每層只吞自己能處理的錯(cuò)處理不了的原樣往上拋。從內(nèi)到外分別是底層接口重試、空回復(fù)補(bǔ)救、截?cái)嗬m(xù)寫(xiě)。3.1 第一層底層重試只重試該重試的最底層的重試寫(xiě)在基類里所有模型通用。核心就兩點(diǎn)指數(shù)退避只重試瞬態(tài)錯(cuò)誤。默認(rèn)最多重試3次間隔1秒、2秒、4秒逐步遞增。什么錯(cuò)該重試分得明明白白。429限流、5xx服務(wù)端錯(cuò)誤、超時(shí)、網(wǎng)絡(luò)連接問(wèn)題這些才重試。401密鑰錯(cuò)誤、400格式錯(cuò)誤這種客戶端錯(cuò)誤重試一百次也沒(méi)用直接返回。429還會(huì)特殊處理響應(yīng)里如果帶了重試時(shí)長(zhǎng)就按人家說(shuō)的時(shí)間等不傻等固定時(shí)長(zhǎng)。還有個(gè)很重要的細(xì)節(jié)用戶主動(dòng)停止的請(qǐng)求直接穿透所有重試層。用戶點(diǎn)了停止你還卡在那等退避人家會(huì)覺(jué)得你這停止按鈕是擺設(shè)。用戶想停優(yōu)先級(jí)最高立刻終止。另外還分兩種重試模式。默認(rèn)模式最多3次給正常對(duì)話用三次不行多半是真有問(wèn)題。還有個(gè)無(wú)限重試模式給后臺(tái)任務(wù)用比如后臺(tái)提煉記憶沒(méi)人等著多試幾次無(wú)所謂。但不管哪種模式用戶停止都立刻穿透。3.2 第二層模型回空串塞句話拽回來(lái)接口層只管模型有沒(méi)有響應(yīng)?？捎袝r(shí)候模型響應(yīng)了卻給你回個(gè)空字符串啥內(nèi)容都沒(méi)有。一般是模型卡住了或者上一條工具結(jié)果給它整懵了。這種錯(cuò)誤接口層發(fā)現(xiàn)不了得上層執(zhí)行邏輯來(lái)兜。檢測(cè)到空回復(fù)就往消息里塞一句引導(dǎo)請(qǐng)基于上文給出你的回復(fù)。然后再調(diào)用一次把模型從卡殼的狀態(tài)拽回來(lái)。最多試2次再多也沒(méi)用。3.3 第三層輸出被截?cái)嘧屗又鴮?xiě)最后一種常見(jiàn)情況模型寫(xiě)長(zhǎng)文件寫(xiě)一半撞上長(zhǎng)度上限話沒(méi)說(shuō)完就斷了。這時(shí)候也不用換模型讓它接著寫(xiě)就行。檢測(cè)到結(jié)束原因是長(zhǎng)度超限就發(fā)一條消息過(guò)去輸出已達(dá)上限從斷點(diǎn)處繼續(xù)寫(xiě)別復(fù)盤(pán)別道歉。為啥特意強(qiáng)調(diào)別復(fù)盤(pán)別道歉你不說(shuō)這話模型大概率會(huì)先寫(xiě)“好的我繼續(xù)先回顧一下之前的內(nèi)容……”半條命的token全花在廢話上了正事沒(méi)寫(xiě)幾個(gè)字。一句精準(zhǔn)的提示能省一半token。最多續(xù)3次超過(guò)還沒(méi)寫(xiě)完大概率是模型陷入循環(huán)了再續(xù)也是浪費(fèi)。順帶說(shuō)一句工具執(zhí)行拋異常的時(shí)候我們也不崩潰。把錯(cuò)誤信息包成工具結(jié)果喂回給模型讓它自己看錯(cuò)誤、自己調(diào)整參數(shù)換工具。代碼只負(fù)責(zé)如實(shí)匯報(bào)決策權(quán)交給大模型。4. 串起來(lái)看一次調(diào)用到底經(jīng)歷了多少層兜底把這三層拼起來(lái)一次有驚無(wú)險(xiǎn)的調(diào)用是這樣的。上層發(fā)起一次調(diào)用主模型先接遇上限流報(bào)錯(cuò)。故障轉(zhuǎn)移層接住自動(dòng)切到備選模型成功返回。用戶全程啥也感覺(jué)不到就覺(jué)得這次好像稍微慢了一點(diǎn)。從頭到尾上層只調(diào)了一次接口中間是重試了、切模型了還是續(xù)寫(xiě)了它一概不知道。這就是好的架構(gòu)設(shè)計(jì)每個(gè)模塊只認(rèn)接口不認(rèn)實(shí)現(xiàn)改動(dòng)全鎖在模塊內(nèi)部。加一家新模型核心代碼一行不用改。調(diào)整重試策略除了Provider層別的代碼毫無(wú)感知。下一篇咱們聊點(diǎn)更靈活的怎么用Hook系統(tǒng)在循環(huán)關(guān)鍵節(jié)點(diǎn)開(kāi)洞不碰核心代碼就能加擴(kuò)展。P.S. 挖到寶藏AI教程全程通俗易懂風(fēng)趣幽默零基礎(chǔ)輕松入門(mén)傳送門(mén)https://blog.csdn.net/qq_34419312