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