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