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