最近在搗鼓AI應(yīng)用接模型的時(shí)候我?guī)缀醴耆司屯扑]一個(gè)工具litellm?？赡芎芏嗤瑢W(xué)第一次看到這個(gè)名字會(huì)以為它是某個(gè)大模型的新版本其實(shí)它是一個(gè)Python庫(kù)。它的核心功能就一句話讓你用一套代碼、一套調(diào)用格式接入幾乎所有主流的大模型服務(wù)商包括OpenAI、Anthropic、Google Gemini、阿里、智譜等等。同時(shí)它還自帶代理服務(wù)、限流、重試、成本統(tǒng)計(jì)、密鑰管理這些功能相當(dāng)于給團(tuán)隊(duì)或項(xiàng)目加了一層“模型網(wǎng)關(guān)”。我第一次用litellm的場(chǎng)景特別樸素項(xiàng)目里原先只接了OpenAI后來(lái)要接Claude代碼里得寫(xiě)兩套請(qǐng)求邏輯還要處理完全不同的返回結(jié)構(gòu)改得頭大。后來(lái)在網(wǎng)上看到有人提到litellm說(shuō)可以把不同廠商的模型統(tǒng)一成OpenAI格式來(lái)調(diào)用我當(dāng)時(shí)就試了一下結(jié)果發(fā)現(xiàn)不只是“統(tǒng)一格式”這么簡(jiǎn)單它把重試、降級(jí)、負(fù)載均衡、甚至價(jià)格預(yù)算統(tǒng)計(jì)都一起做掉了完全超出預(yù)期。這篇博文我就把自己從接觸到深度使用litellm的過(guò)程、踩過(guò)的坑、以及一些配置細(xì)節(jié)完整寫(xiě)出來(lái)希望對(duì)正在做多模型接入或者想搭一個(gè)內(nèi)部AI網(wǎng)關(guān)的同學(xué)有幫助。1. 為什么需要統(tǒng)一接口從“模型混亂期”聊聊背景1.1 各家API的真實(shí)痛點(diǎn)現(xiàn)在大模型市場(chǎng)早就不是OpenAI一家獨(dú)大了。Anthropic有Claude系列、Google有Gemini、國(guó)內(nèi)有各種開(kāi)源的Qwen、DeepSeek等等。單看每一家的API文檔都寫(xiě)得很清楚但一旦你需要在同一個(gè)應(yīng)用里接入兩家以上問(wèn)題就來(lái)了。首先接口格式不統(tǒng)一。OpenAI用的是messages數(shù)組里面放role和contentClaude在某個(gè)版本里也是類(lèi)似的格式但參數(shù)細(xì)節(jié)不同比如max_tokens和max_tokens_to_sample這種命名的差異Gemini又有自己的一套管法。更麻煩的是同樣一個(gè)“讓模型寫(xiě)一段Python代碼”的請(qǐng)求在不同服務(wù)商那邊可能需要不同的頂層字段去控制溫度、隨機(jī)性、流式輸出等參數(shù)。其次是返回結(jié)構(gòu)不統(tǒng)一。OpenAI返回choices[0].message.contentClaude返回content[0].textGemini可能又是另一個(gè)字段路徑。這意味著你的業(yè)務(wù)代碼里得寫(xiě)大量的解析兼容邏輯。我見(jiàn)過(guò)一個(gè)項(xiàng)目光是一個(gè)“提取模型回復(fù)內(nèi)容”的函數(shù)就寫(xiě)了十來(lái)個(gè)if...else因?yàn)榭赡芤拥姆?wù)商太多了。第三是每個(gè)服務(wù)商的錯(cuò)誤處理邏輯不一樣限流返回的狀態(tài)碼不同、超時(shí)策略不同、鑒權(quán)方式也不同。這些“臟活累活”都堆在業(yè)務(wù)代碼里維護(hù)成本極高。1.2 litellm的定位與核心思路litellm的解法很聰明。它不搞自己的模型也不替代任何一家服務(wù)商它就做一個(gè)“中間層”。你按照OpenAI的格式把請(qǐng)求發(fā)給它它負(fù)責(zé)把請(qǐng)求翻譯成目標(biāo)服務(wù)商能理解的樣子然后發(fā)出去等目標(biāo)服務(wù)商返回之后它再統(tǒng)一轉(zhuǎn)成OpenAI的格式還給你。這樣你的業(yè)務(wù)代碼從頭到尾只認(rèn)識(shí)一種接口。它還有一個(gè)Agent叫Proxy Server也就是代理模式。你可以把litellm當(dāng)作一個(gè)小型的API網(wǎng)關(guān)獨(dú)立跑起來(lái)業(yè)務(wù)服務(wù)只需要配置一個(gè)base_url指向它然后用OpenAI的SDK去調(diào)用剩下的事情litellm全部接管。這種設(shè)計(jì)的價(jià)值在于業(yè)務(wù)開(kāi)發(fā)不用關(guān)心底下的模型是哪一家只關(guān)心模型名。比如你今天用的gpt-4o明天想換claude-3-5-sonnet在你的代碼里只需要改一個(gè)字符串甚至不改也可以通過(guò)配置中心動(dòng)態(tài)切換。同時(shí)服務(wù)的穩(wěn)定性提升了一個(gè)層級(jí)因?yàn)橹卦?、降?jí)這些策略都在網(wǎng)關(guān)層完成了。2. 環(huán)境準(zhǔn)備與基礎(chǔ)接入2.1 安裝與環(huán)境檢查litellm的安裝很簡(jiǎn)單直接用pippip install litellm如果你的項(xiàng)目對(duì)包大小敏感它依賴(lài)的東西也不多核心調(diào)用只需要httpx和pydantic這一類(lèi)的庫(kù)。安裝完之后我建議先做一次快速驗(yàn)證。我需要確認(rèn)Python版本在3.8以上我在3.9、3.10、3.11都跑過(guò)沒(méi)遇到兼容性問(wèn)題。然后設(shè)置環(huán)境變量。如果你要調(diào)OpenAI的模型export OPENAI_API_KEYsk-xxxx如果要調(diào)Anthropic就設(shè)置ANTHROPIC_API_KEYGemini就設(shè)置GEMINI_API_KEY。litellm通過(guò)讀取這些環(huán)境變量來(lái)找密鑰。注意如果你的Key是存在本地的.env文件里記得在使用litellm之前先加載。我習(xí)慣用一個(gè)很小的工具庫(kù)python-dotenv來(lái)做這件事。2.2 一次調(diào)用從OpenAI格式到全模型兼容接下來(lái)寫(xiě)最簡(jiǎn)單的一次調(diào)用。在litellm里核心函數(shù)是completion基本用法長(zhǎng)這樣import litellm response litellm.completion( modelgpt-4o, messages[ {role: user, content: 給我講一個(gè)三句話的笑話} ], temperature0.7 ) print(response.choices[0].message.content)這個(gè)寫(xiě)法跟OpenAI官方SDK幾乎一樣因?yàn)閘itellm就是故意保持這個(gè)格式的。但神奇的地方在這里我把model參數(shù)換成下面任意一個(gè)上面的代碼都不用改modelclaude-3-5-sonnet-20241022 modelgemini-1.5-pro modelanthropic/claude-3-opus modelollama_chat/llama3.1它會(huì)根據(jù)你傳入的模型名自動(dòng)判斷要調(diào)用哪一家服務(wù)商自動(dòng)切換鑒權(quán)方式、接口格式、返回解析。如果你在model前面加上服務(wù)商前綴比如anthropic/或者openai/可以強(qiáng)制指定走某條路線這在某些場(chǎng)景下很有用可以避免模型名沖突。我實(shí)測(cè)最順手的用法是直接把環(huán)境變量配置好然后用統(tǒng)一格式調(diào)通再慢慢試各種模型。說(shuō)句實(shí)話第一眼看到response對(duì)象的時(shí)候我心里想的是“這不就是把OpenAI的response結(jié)構(gòu)抄了一遍嘛”但后來(lái)發(fā)現(xiàn)它里面對(duì)不同供應(yīng)商的“方言”處理是真的到位。3. 核心功能拆解路由、重試與觀測(cè)3.1 模型路由與負(fù)載均衡單模型調(diào)用只是入門(mén)litellm真正有價(jià)值的是“模型路由”能力。你可以把多個(gè)模型組成一組讓litellm自動(dòng)選擇用哪個(gè)模型來(lái)處理請(qǐng)求。這在兩種場(chǎng)景下特別有用一是想省錢(qián)優(yōu)先用便宜的模型二是想保穩(wěn)定主模型掛了自動(dòng)切備用模型。我經(jīng)常寫(xiě)的一個(gè)路由配置長(zhǎng)這樣import litellm router litellm.Router(model[gpt-4o, claude-3-5-sonnet, gemini-1.5-pro]) response router.completion( modelgpt-4o, messages[{role: user, content: 你好}], fallback_models[claude-3-5-sonnet, gemini-1.5-pro] )這里有兩個(gè)重點(diǎn)值得展開(kāi)。第一個(gè)是Router可以通過(guò)routing_strategy參數(shù)指定策略比如simple-shuffle是隨機(jī)挑一個(gè)least-busy是挑當(dāng)前負(fù)載最低的usage-based-routing是根據(jù)模型成本去選。第二個(gè)是fallback_models它定義了主模型失敗后的降級(jí)名單。litellm如果發(fā)現(xiàn)主模型因?yàn)橄蘖鳌⒊瑫r(shí)或5xx報(bào)錯(cuò)會(huì)自動(dòng)按順序去試備用模型業(yè)務(wù)方幾乎無(wú)感。3.2 重試與降級(jí)的參數(shù)設(shè)計(jì)重試參數(shù)方面litellm的默認(rèn)行為我覺(jué)得對(duì)大多數(shù)場(chǎng)景是合理的遇到網(wǎng)絡(luò)抖動(dòng)、500錯(cuò)誤、429限流會(huì)自動(dòng)重試默認(rèn)最多重試2次。但我建議你在生產(chǎn)環(huán)境顯式配置一下因?yàn)槟J(rèn)策略不一定適合所有供應(yīng)商。response litellm.completion( modelgpt-4o, messages[{role: user, content: 你好}], num_retries3, retry_after5, fallback_models[claude-3-5-sonnet], )num_retries是最大重試次數(shù)retry_after是重試前等待的秒數(shù)這個(gè)等待時(shí)間我一般設(shè)成5秒起步。注意如果對(duì)方服務(wù)商返回的是400這種客戶(hù)端錯(cuò)誤重試也沒(méi)用litellm會(huì)直接放棄它主要對(duì)429、5xx和網(wǎng)絡(luò)異常做重試。降級(jí)時(shí)要關(guān)注模型的能力差異如果主模型是gpt-4o備用模型至少也得是同等級(jí)的推理能力否則業(yè)務(wù)結(jié)果質(zhì)量會(huì)有明顯下降。3.3 可觀測(cè)性與日志AI網(wǎng)關(guān)最重要的就是能看清楚“誰(shuí)在什么時(shí)候用了哪個(gè)模型花了多少錢(qián)”。litellm自帶了日志記錄和成本估算功能。它有幾種日志輸出方式控制臺(tái)日志、寫(xiě)入文件、甚至回調(diào)到自定義函數(shù)。我常用的是把調(diào)用記錄打進(jìn)日志文件簡(jiǎn)單配置就行import litellm litellm.success_callback [my_logging_function] litellm.failure_callback [my_error_logging_function]然后在自己的回調(diào)里可以取到kwargs里的模型名稱(chēng)、提示詞長(zhǎng)度、輸出長(zhǎng)度、花費(fèi)的錢(qián)數(shù)。這里有一個(gè)細(xì)節(jié)litellm計(jì)算成本用的價(jià)格表來(lái)源于litellm/model_prices_and_context_window.json它會(huì)定期更新。如果你接的是私有化部署模型或極新的模型價(jià)格可能查不到此時(shí)返回的cost字段會(huì)是0或者空。別慌可以手動(dòng)維護(hù)價(jià)格或者忽略成本字段。提示在生產(chǎn)項(xiàng)目里我把litellm的日志和公司內(nèi)部的監(jiān)控系統(tǒng)打通了每次調(diào)用的延遲、token消耗、成本都會(huì)記錄到數(shù)據(jù)表里。這樣月底跟財(cái)務(wù)對(duì)賬的時(shí)候特別方便不用再?gòu)母鱾€(gè)平臺(tái)單獨(dú)拉賬單。4. 實(shí)操搭建一個(gè)本地AI網(wǎng)關(guān)4.1 快速啟動(dòng)代理服務(wù)如果你想在團(tuán)隊(duì)內(nèi)部搭建一個(gè)“所有模型統(tǒng)一入口”的API服務(wù)litellm提供了Proxy模式這也是它最強(qiáng)大的用法之一。啟動(dòng)方式非常簡(jiǎn)單在命令行里執(zhí)行l(wèi)itellm --model gpt-4o --port 8000這樣會(huì)在本地8000端口起一個(gè)類(lèi)似OpenAI的API服務(wù)支持/chat/completions、/completions、/models這些端點(diǎn)。業(yè)務(wù)側(cè)只要把OpenAI SDK的base_url指過(guò)來(lái)就行from openai import OpenAI client OpenAI( api_keysk-anything, # 代理模式下這個(gè)Key不校驗(yàn)也可以 base_urlhttp://localhost:8000 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)注意這里有點(diǎn)小坑代理模式下如果api_key隨便填是能過(guò)去的但如果你在后面加了虛擬密鑰功能api_key就要填你自己生成的虛擬Key不能隨便寫(xiě)了。這一點(diǎn)我在后面會(huì)重點(diǎn)講。4.2 接入多個(gè)提供商并配置限流命令行啟動(dòng)適合快速測(cè)試生產(chǎn)環(huán)境肯定不能這么裸奔而是用配置文件來(lái)管理。我一般用一個(gè)config.yaml里面定義好可用的模型列表、每個(gè)模型的限流參數(shù)、以及密鑰信息model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY rpm: 100 tpm: 100000 - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY rpm: 80 tpm: 80000 - model_name: gemini-1.5-pro litellm_params: model: gemini/gemini-1.5-pro api_key: os.environ/GEMINI_API_KEY rpm: 50 tpm: 50000然后啟動(dòng)litellm --config config.yaml --port 8000model_name是外部暴露的名字litellm_params.model是真實(shí)要調(diào)用的遠(yuǎn)端模型名rpm是每分鐘請(qǐng)求數(shù)上限tpm是每分鐘token數(shù)上限。限流參數(shù)設(shè)置好之后當(dāng)請(qǐng)求頻率超出閾值litellm會(huì)返回429錯(cuò)誤給調(diào)用方但不會(huì)去瘋狂打上游服務(wù)商。如果配了重試和降級(jí)它還有可能自動(dòng)換一個(gè)沒(méi)有超限的模型來(lái)響應(yīng)。4.3 密鑰管理與權(quán)限控制前面提到虛擬密鑰這是litellm做的很好用的一個(gè)點(diǎn)。在生產(chǎn)環(huán)境我們不應(yīng)該把OpenAI的原始Key下發(fā)給每個(gè)服務(wù)或每個(gè)開(kāi)發(fā)者。litellm支持在代理服務(wù)上生成虛擬Keycurl http://localhost:8000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d {models: [gpt-4o]}返回結(jié)果里會(huì)帶上一個(gè)新的sk-開(kāi)頭的Key。這個(gè)Key是litellm自己生成的背后映射到真實(shí)的模型調(diào)用。這樣即使某個(gè)服務(wù)的Key泄露了你也可以在litellm這邊一鍵吊銷(xiāo)而不需要去上游服務(wù)商那邊重新生成密鑰。只有持有Master Key的人才能管理這些虛擬Key。安全提示Master Key默認(rèn)是sk-master-key如果不改會(huì)很危險(xiǎn)。建議啟動(dòng)時(shí)用環(huán)境變量LITELLM_MASTER_KEY指定一個(gè)強(qiáng)密碼。我第一次部署時(shí)忘了改結(jié)果內(nèi)網(wǎng)里所有人都能創(chuàng)建虛擬Key雖然不會(huì)直接看到上游Key但也能調(diào)接口燒錢(qián)后來(lái)老老實(shí)實(shí)加了權(quán)限控制。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 模型名傳錯(cuò)導(dǎo)致調(diào)用失敗最常碰到的問(wèn)題就是模型名字對(duì)不上。比如你在供應(yīng)商那邊用的是claude-3-5-sonnet-20241022結(jié)果在litellm里只寫(xiě)了claude-3-5-sonnet有些時(shí)候它能正確解析有些時(shí)候會(huì)報(bào)找不到。解決方法是查詢(xún)litellm支持的模型列表我習(xí)慣用代碼列出import litellm all_models litellm.model_list print([m for m in all_models if claude in m])也可以直接看官方文檔里的model map。如果你接的是自定義的模型在model參數(shù)里直接寫(xiě)完整路徑會(huì)更穩(wěn)妥。注意在config.yaml里配置模型時(shí)litellm_params.model盡量寫(xiě)全名不要偷懶。5.2 上游限流與并發(fā)突刺429錯(cuò)誤是家常便飯尤其是多個(gè)服務(wù)共用一個(gè)上游Key的時(shí)候。litellm的重試機(jī)制能解決一部分問(wèn)題但如果并發(fā)實(shí)在太高光靠重試反而會(huì)加劇限流。我在配置里會(huì)這樣處理第一給每個(gè)模型設(shè)置合理的rpm/tpm第二啟用cooldown_time當(dāng)某個(gè)模型連續(xù)報(bào)錯(cuò)時(shí)litellm可以自動(dòng)把該模型拉入“冷卻期”暫時(shí)不用直接走備用模型從而保護(hù)上游。router_settings: cooldown_time: 30 routing_strategy: usage-based-routing5.3 成本統(tǒng)計(jì)與實(shí)際賬單對(duì)不上這個(gè)坑很多人會(huì)遇到。litellm的成本估算是通過(guò)它內(nèi)置的價(jià)格表完成的但價(jià)格表更新有延遲。比如某家供應(yīng)商大規(guī)模調(diào)價(jià)之后litellm可能還沒(méi)來(lái)得及更新導(dǎo)致它預(yù)估的費(fèi)用和真實(shí)賬單差距很大。解決思路如下一是手動(dòng)覆蓋價(jià)格在代碼里改litellm.model_cost_map。二是在做對(duì)賬時(shí)以供應(yīng)商后臺(tái)賬單為準(zhǔn)litellm的成本只做參考。三是把litellm的每次調(diào)用日志記錄下來(lái)用日志里的token數(shù)去乘價(jià)格表這樣可以自己重算。建議不要完全依賴(lài)litellm的cost字段特別是在用了新模型或高端模型的時(shí)候。5.4 日志亂碼與編碼問(wèn)題在使用OpenAI兼容接口返回內(nèi)容時(shí)如果響應(yīng)里的中文出現(xiàn)亂碼多半是項(xiàng)目本身沒(méi)有設(shè)置UTF-8編碼。litellm本身對(duì)編碼處理是沒(méi)問(wèn)題的但如果你在Windows控制臺(tái)跑可能會(huì)因?yàn)槟J(rèn)編碼是GBK而看到亂碼。我的建議是代碼文件開(kāi)頭聲明# -*- coding: utf-8 -*-或者在運(yùn)行環(huán)境中設(shè)置PYTHONIOENCODINGutf-8。這類(lèi)問(wèn)題不算大但排查起來(lái)很煩人。5.5 排查綜合技巧litellm支持一個(gè)Debug模式打開(kāi)后它會(huì)打印出內(nèi)部的請(qǐng)求和響應(yīng)細(xì)節(jié)這比猜錯(cuò)因高效得多import litellm litellm.set_verbose(True)還有一個(gè)很實(shí)用的方法開(kāi)啟litellm.suppress_debug_info False能看到它實(shí)際發(fā)送給上游服務(wù)商的請(qǐng)求體長(zhǎng)什么樣。當(dāng)你懷疑某家供應(yīng)商大模型返回內(nèi)容被截?cái)嗷蛘?qǐng)求參數(shù)沒(méi)傳全時(shí)用這個(gè)辦法一眼就能看出來(lái)。6. 進(jìn)階玩法與生態(tài)整合6.1 與主流框架結(jié)合現(xiàn)在很多AI應(yīng)用都用LangChain或LlamaIndex這類(lèi)框架做編排。litellm在這些框架里的定位是把“模型調(diào)用”這層完全替換。比如在LangChain里你可以直接用ChatLiteLLM模塊接入只要配置好model_name即可from langchain_community.chat_models import ChatLiteLLM from langchain_core.messages import HumanMessage chat ChatLiteLLM(modelgpt-4o, temperature0.7) resp chat([HumanMessage(content你好)]) print(resp.content)在LlamaIndex里也可以用LiteLLM作為L(zhǎng)LM后端。這樣原本基于OpenAI開(kāi)發(fā)的應(yīng)用只需要替換類(lèi)名和微調(diào)參數(shù)就能切換到litellm極其順暢。6.2 自定義模型接入與擴(kuò)展如果你用的是開(kāi)源模型自己部署想接入litellm也很方便。它的設(shè)計(jì)本來(lái)就支持第三方兼容端點(diǎn)。比如你本地跑著一個(gè)Ollama上的模型可以通過(guò)ollama_chat/llama3.1這樣的前綴來(lái)指定走Ollama通道。如果你接的是某企業(yè)內(nèi)部系統(tǒng)只要它提供OpenAI兼容接口你也可以直接通過(guò)自定義api_base接進(jìn)來(lái)。以下是我用過(guò)的一個(gè)簡(jiǎn)單自定義配置例子import litellm litellm.openai_settings[MY_CUSTOM_SERVICE] { api_base: https://my-internal-service.example.com/v1, api_key: os.environ[MY_SERVICE_KEY] } resp litellm.completion( modelopenai/gpt-4o, # 這里只是占位真實(shí)服務(wù)由api_base接管 messages[{role: user, content: test}], api_basehttps://my-internal-service.example.com/v1 )6.3 多節(jié)點(diǎn)部署的可能性litellm的代理模式是支持多節(jié)點(diǎn)橫向擴(kuò)展的這意味著你可以做一個(gè)小型的高可用網(wǎng)關(guān)集群。多個(gè)litellm實(shí)例共享同一套配置與虛擬密鑰存儲(chǔ)存儲(chǔ)在Redis或數(shù)據(jù)庫(kù)里上游負(fù)載被分散到多個(gè)網(wǎng)關(guān)節(jié)點(diǎn)上。這也是它被很多創(chuàng)業(yè)公司拿來(lái)當(dāng)作內(nèi)部AI基礎(chǔ)設(shè)施的原因之一。如果需要做多節(jié)點(diǎn)我建議把配置文件和密鑰存儲(chǔ)外部化再用容器編排工具管理litellm實(shí)例的生命周期。實(shí)例本身是無(wú)狀態(tài)的可以隨意增減。不過(guò)這一塊牽扯到運(yùn)維非必要不折騰單節(jié)點(diǎn)對(duì)你的小型項(xiàng)目完全夠了。我的幾點(diǎn)總結(jié)性體會(huì)用litellm大半年下來(lái)我最深的感覺(jué)是“它把多模型接入這件事從噩夢(mèng)變成了日?！?。以前我接新模型平均要花半天到一天去讀文檔、調(diào)參數(shù)、寫(xiě)適配代碼現(xiàn)在用litellm只需要在配置里加一行模型名跑一下回歸測(cè)試基本就能上線。特別是把代理模式跑起來(lái)之后連業(yè)務(wù)方的SDK都不用改這種體驗(yàn)相當(dāng)爽。如果你還沒(méi)有試過(guò)litellm我的建議是從最簡(jiǎn)單的completion調(diào)用開(kāi)始把它當(dāng)作一個(gè)“兼容性工具”來(lái)用。跑通之后再逐步加上路由、重試、降級(jí)和虛擬密鑰。不要一上來(lái)就搭完整網(wǎng)關(guān)那樣容易淹沒(méi)在配置細(xì)節(jié)里。litellm的文檔我建議優(yōu)先看“Proxy”那部分那才是它在生產(chǎn)環(huán)境發(fā)揮真正價(jià)值的地方。另外litellm的版本更新比較快如果你用的是舊版本有些新模型可能查不到升級(jí)前記得看一下官方變更記錄。做好版本鎖定是長(zhǎng)期使用最省心的方式。