先交代一下背景吧。最近一年多我接手的幾個(gè)項(xiàng)目都繞不開(kāi)大模型調(diào)用這件事。有的模塊要用海外閉源模型做復(fù)雜推理有的要用國(guó)內(nèi)開(kāi)源模型走私有化部署還時(shí)不時(shí)有人提“能不能順手把某個(gè)本地小模型也接進(jìn)來(lái)做個(gè)兜底”。最讓我頭疼的不是模型效果而是每個(gè)服務(wù)都有自己的SDK、鑒權(quán)方式、請(qǐng)求體和響應(yīng)結(jié)構(gòu)。業(yè)務(wù)代碼里塞滿了針對(duì)不同供應(yīng)商的分支邏輯換一個(gè)模型要改好幾處日志格式也不統(tǒng)一線上出問(wèn)題根本沒(méi)法快速定位。后來(lái)我把這些調(diào)用全部收斂到一個(gè)開(kāi)源網(wǎng)關(guān)層來(lái)處理也就是標(biāo)題里寫的litellm。它做的事情可以用一句話說(shuō)清楚把各種模型提供方的API統(tǒng)一成同一個(gè)協(xié)議格式對(duì)外暴露一套標(biāo)準(zhǔn)接口。這樣一來(lái)業(yè)務(wù)端只需要對(duì)接一次后續(xù)換模型、加模型、做負(fù)載均衡和自動(dòng)重試全都在網(wǎng)關(guān)層完成不用再改業(yè)務(wù)代碼。這篇文章就圍繞這個(gè)工具把我從部署、配置到生產(chǎn)環(huán)境踩坑的完整過(guò)程梳理一遍給同樣被多模型調(diào)用折騰的人一個(gè)參考。1. 先搞清楚litellm到底解了什么難題1.1 多模型調(diào)用格式不統(tǒng)一的真實(shí)痛點(diǎn)先說(shuō)一個(gè)最常見(jiàn)的場(chǎng)景。很多團(tuán)隊(duì)一開(kāi)始只接了一家模型服務(wù)代碼寫得很順。等第二個(gè)項(xiàng)目要換另一家模型供應(yīng)商時(shí)就會(huì)發(fā)現(xiàn)事情遠(yuǎn)沒(méi)有想象中簡(jiǎn)單。表面上大家都是“發(fā)一個(gè)HTTP請(qǐng)求、傳一段提示詞、拿回一段生成結(jié)果”但細(xì)節(jié)上的差異非常磨人。我用一個(gè)表格來(lái)對(duì)照一下不同供應(yīng)商常見(jiàn)的差異點(diǎn)你就明白為什么需要一層統(tǒng)一的處理差異維度供應(yīng)商A的典型行為供應(yīng)商B的典型行為鑒權(quán)方式請(qǐng)求頭帶指定前綴的密鑰使用獨(dú)立的訪問(wèn)令牌過(guò)期需刷新請(qǐng)求地址路徑中包含版本號(hào)路徑中不區(qū)分版本靠參數(shù)區(qū)分請(qǐng)求體字段參數(shù)名較長(zhǎng)需要嵌套結(jié)構(gòu)參數(shù)平鋪命名更簡(jiǎn)潔模型參數(shù)溫度和采樣數(shù)等參數(shù)齊全部分參數(shù)不支持傳了會(huì)報(bào)錯(cuò)響應(yīng)體結(jié)構(gòu)生成內(nèi)容嵌在多層嵌套字段中生成內(nèi)容直接在頂層字段中返回報(bào)錯(cuò)信息返回標(biāo)準(zhǔn)錯(cuò)誤碼加說(shuō)明返回自定義錯(cuò)誤結(jié)構(gòu)錯(cuò)誤碼含義不同流式輸出數(shù)據(jù)幀格式統(tǒng)一數(shù)據(jù)幀格式有差異需要單獨(dú)解析這些差異一旦疊加在同一個(gè)代碼庫(kù)里就會(huì)變成大量適配代碼。比如我在一個(gè)項(xiàng)目里同時(shí)接了三家服務(wù)光是請(qǐng)求體的組裝函數(shù)就寫了六七個(gè)版本每個(gè)版本還帶自己的異常處理邏輯。后面為了排查一次“生成結(jié)果為空”的問(wèn)題我不得不分別打開(kāi)三套文檔對(duì)著三家不同的返回結(jié)構(gòu)做比對(duì)前前后后花了大半天。這些時(shí)間本來(lái)不應(yīng)該花在“連接口都調(diào)不通”這種體力活上。litellm這種工具的存在本質(zhì)上就是為了消除這層重復(fù)勞動(dòng)。它把“不同供應(yīng)商的差異”集中在一個(gè)配置層解決讓下游業(yè)務(wù)永遠(yuǎn)只面對(duì)一套穩(wěn)定的協(xié)議。1.2 它本身不是什么魔法請(qǐng)求代理的運(yùn)轉(zhuǎn)邏輯我第一次接觸litellm時(shí)一度以為它是個(gè)復(fù)雜的模型調(diào)度框架需要在項(xiàng)目里引入重型依賴。實(shí)際了解下來(lái)它的核心邏輯比我預(yù)想的簡(jiǎn)單直接它是一個(gè)請(qǐng)求代理。用一個(gè)生活化的比喻來(lái)說(shuō)它就像前臺(tái)接待員。你不需要知道公司里每個(gè)具體部門的人長(zhǎng)什么樣、坐在哪個(gè)工位只需要把需求告訴前臺(tái)前臺(tái)會(huì)根據(jù)你的需求去找對(duì)應(yīng)的部門溝通再把結(jié)果帶回來(lái)交給你。litellm扮演的角色就是那個(gè)前臺(tái)業(yè)務(wù)方永遠(yuǎn)用同一套方式“提需求”至于后面到底是哪家模型服務(wù)在真正響應(yīng)業(yè)務(wù)方完全不感知。這個(gè)“前臺(tái)”在技術(shù)實(shí)現(xiàn)上就是一個(gè)常駐的代理服務(wù)。啟動(dòng)后它會(huì)在本地監(jiān)聽(tīng)一個(gè)端口對(duì)外提供與主流模型服務(wù)高度兼容的HTTP接口。業(yè)務(wù)代碼只要把請(qǐng)求發(fā)到這個(gè)地址網(wǎng)關(guān)層會(huì)負(fù)責(zé)解析、鑒權(quán)、轉(zhuǎn)發(fā)、接收響應(yīng)再把響應(yīng)換算成統(tǒng)一格式返回給調(diào)用方。很多人可能會(huì)問(wèn)多加一層網(wǎng)絡(luò)請(qǐng)求是不是意味著性能損耗這個(gè)損耗確實(shí)存在但通常非常小。請(qǐng)求本身只有一次額外的本地轉(zhuǎn)發(fā)內(nèi)網(wǎng)環(huán)境下基本在毫秒級(jí)。相比它帶來(lái)的“業(yè)務(wù)代碼零適配”收益這點(diǎn)開(kāi)銷幾乎可以忽略。我在生產(chǎn)環(huán)境實(shí)際壓測(cè)過(guò)加了這層代理之后單次請(qǐng)求的延遲增加大約在個(gè)位數(shù)毫秒用戶體驗(yàn)上完全無(wú)感。2. 從零部署虛擬環(huán)境、配置文件和第一次代理啟動(dòng)2.1 安裝與最簡(jiǎn)單的啟動(dòng)方式litellm的安裝官方推薦使用Python環(huán)境安裝命令也很簡(jiǎn)單pip install litellm[proxy]這里要注意一個(gè)細(xì)節(jié)安裝包名稱后面帶了[proxy]后綴這表示要安裝帶代理功能的完整版本。如果只裝litellm本體你只能使用Python SDK的調(diào)用能力起不了代理服務(wù)。不少第一次上手的人就是在這踩了坑裝了之后發(fā)現(xiàn)沒(méi)有l(wèi)itellm --port這個(gè)命令。安裝完成后最簡(jiǎn)單的啟動(dòng)方式是這樣litellm --model 某海外大模型服務(wù)/某模型名 --port 8000直接通過(guò)命令行指定模型和端口litellm就會(huì)啟動(dòng)一個(gè)最基本的代理。這種模式適合快速驗(yàn)證工具本身好不好用。但說(shuō)實(shí)話我在項(xiàng)目里幾乎不會(huì)用這種方式跑生產(chǎn)因?yàn)樗信渲枚伎棵钚袇?shù)時(shí)間長(zhǎng)了根本記不住哪條命令對(duì)應(yīng)哪個(gè)環(huán)境。更推薦的做法是寫配置文件。還有一個(gè)比較重要的事我建議用虛擬環(huán)境來(lái)裝。因?yàn)閘itellm的依賴比較多而且和很多AI相關(guān)的Python庫(kù)存在版本交集直接裝到系統(tǒng)環(huán)境里很容易和項(xiàng)目里的其他庫(kù)相互干擾。我后來(lái)就把所有模型網(wǎng)關(guān)相關(guān)的東西統(tǒng)一放到了獨(dú)立的虛擬環(huán)境中需要升級(jí)或者排查依賴問(wèn)題時(shí)直接重建虛擬環(huán)境干凈利落。2.2 config.yaml里的關(guān)鍵字段說(shuō)明生產(chǎn)環(huán)境部署時(shí)我的習(xí)慣是把所有模型供應(yīng)商信息寫進(jìn)一個(gè)YAML配置文件。這樣做的好處是模型增刪改都只需要改配置文件然后重啟代理即可不需要改動(dòng)任何業(yè)務(wù)代碼。一個(gè)最基礎(chǔ)的配置文件長(zhǎng)這樣model_list: - model_name: gpt-like litellm_params: model: 某海外大模型服務(wù)/某模型名 api_key: os.environ/某海外服務(wù)密鑰 - model_name: gpt-like litellm_params: model: 某國(guó)內(nèi)開(kāi)源模型服務(wù)/某模型名 api_key: os.environ/某國(guó)內(nèi)服務(wù)密鑰 api_base: https://某國(guó)內(nèi)服務(wù)地址/v1 litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-1234 database_url: os.environ/DATABASE_URL逐項(xiàng)解釋一下。model_list是整個(gè)配置的核心它定義了這個(gè)網(wǎng)關(guān)能代理哪些模型。注意每一項(xiàng)里都有model_name和litellm_params兩個(gè)部分。model_name是對(duì)外暴露的名稱業(yè)務(wù)方調(diào)用時(shí)只知道這個(gè)名字litellm_params則是實(shí)際轉(zhuǎn)發(fā)時(shí)需要用到的參數(shù)包括真正的模型標(biāo)識(shí)、供應(yīng)商的密鑰、請(qǐng)求地址等。這里有個(gè)很關(guān)鍵的設(shè)計(jì)點(diǎn)model_name可以重復(fù)。也就是說(shuō)你可以讓兩個(gè)不同的真實(shí)模型共用同一個(gè)對(duì)外名稱。這個(gè)特性后面在做自動(dòng)切換和負(fù)載均衡時(shí)非常有用先記著。litellm_settings里我比較關(guān)注drop_params這個(gè)選項(xiàng)。前面說(shuō)過(guò)不同供應(yīng)商支持的超參數(shù)種類不一樣如果把供應(yīng)商A的參數(shù)傳給供應(yīng)商B對(duì)方可能直接報(bào)錯(cuò)。開(kāi)啟drop_params之后litellm會(huì)自動(dòng)過(guò)濾掉目標(biāo)供應(yīng)商不支持的參數(shù)避免請(qǐng)求失敗。這個(gè)選項(xiàng)在接入多家供應(yīng)商時(shí)幾乎必開(kāi)。general_settings里的master_key是網(wǎng)關(guān)的管理密鑰客戶端請(qǐng)求時(shí)需要在請(qǐng)求頭帶上這個(gè)密鑰才能訪問(wèn)。database_url是可選配置用于持久化請(qǐng)求日志和預(yù)算數(shù)據(jù)。生產(chǎn)環(huán)境建議配上數(shù)據(jù)庫(kù)否則網(wǎng)關(guān)重啟后日志就丟了。2.3 用curl驗(yàn)證代理轉(zhuǎn)發(fā)是否正常配置寫好后用一條curl命令就能驗(yàn)證整個(gè)鏈路是否打通curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-1234 \ -d { model: gpt-like, messages: [ {role: user, content: 你好請(qǐng)用一句話介紹你自己} ] }如果一切正常你會(huì)收到一段結(jié)構(gòu)完整的響應(yīng)里面有生成的內(nèi)容、使用的模型、token用量等信息?？吹竭@段響應(yīng)說(shuō)明代理服務(wù)已經(jīng)成功把你的請(qǐng)求轉(zhuǎn)發(fā)給了真實(shí)的模型服務(wù)并拿到了結(jié)果。第一次驗(yàn)證時(shí)如果遇到問(wèn)題優(yōu)先看兩個(gè)地方。一是啟動(dòng)代理的那個(gè)終端窗口有沒(méi)有輸出錯(cuò)誤日志大多數(shù)轉(zhuǎn)發(fā)失敗的原因都會(huì)直接打在那里二是確認(rèn)配置文件里的密鑰和模型名是否真實(shí)有效。我曾經(jīng)因?yàn)閺?fù)制配置時(shí)多了個(gè)空格導(dǎo)致認(rèn)證一直失敗排查了半天才發(fā)現(xiàn)是YAML解析后的值尾巴上帶了個(gè)不可見(jiàn)字符。2.4 只需改base_url業(yè)務(wù)代碼幾乎不動(dòng)代理跑通之后業(yè)務(wù)代碼的改動(dòng)可以說(shuō)小到令人驚訝。以官方SDK風(fēng)格的調(diào)用方式為例改之前是這樣的from 某海外大模型服務(wù) import Client client Client(api_key真實(shí)密鑰) response client.chat.completions.create( model某模型名, messages[{role: user, content: 你好}] )改之后是這樣from 某海外大模型服務(wù) import Client client Client( base_urlhttp://localhost:8000/v1, api_keysk-1234 ) response client.chat.completions.create( modelgpt-like, messages[{role: user, content: 你好}] )看到區(qū)別沒(méi)有業(yè)務(wù)代碼幾乎原封不動(dòng)唯一變化的是base_url指向了本地代理api_key換成了網(wǎng)關(guān)的密鑰model換成了網(wǎng)關(guān)里配置的對(duì)外名稱。這一點(diǎn)極其重要。這意味著你不需要為litellm引入任何新的SDK不需要重寫調(diào)用邏輯甚至連已有的調(diào)用代碼都可以直接復(fù)用。我接手的一個(gè)老項(xiàng)目里原來(lái)的調(diào)用代碼還停留在比較舊的參數(shù)寫法上我本來(lái)以為要花大力氣改造結(jié)果只是把base_url和api_key兩個(gè)配置項(xiàng)替換掉接口就跑通了這個(gè)體感真的很爽。3. 統(tǒng)一響應(yīng)格式一份日志和一套錯(cuò)誤碼帶來(lái)的連鎖便利3.1 響應(yīng)體結(jié)構(gòu)統(tǒng)一后下游處理簡(jiǎn)化了多少調(diào)用跑通只是第一步真正讓業(yè)務(wù)代碼變清爽的是響應(yīng)格式的統(tǒng)一。在沒(méi)有網(wǎng)關(guān)時(shí)不同供應(yīng)商返回的JSON結(jié)構(gòu)五花八門。有的把生成內(nèi)容放在一個(gè)多層的嵌套結(jié)構(gòu)里有的放在頂層的某個(gè)字段里還有的在返回內(nèi)容的同時(shí)附帶一堆你根本用不到的信息。業(yè)務(wù)端為了兼容這些差異往往會(huì)寫好幾個(gè)解析函數(shù)每個(gè)函數(shù)負(fù)責(zé)一種結(jié)構(gòu)再通過(guò)分支判斷決定走哪個(gè)解析邏輯。接入litellm之后所有響應(yīng)都會(huì)轉(zhuǎn)換成標(biāo)準(zhǔn)結(jié)構(gòu)生成內(nèi)容統(tǒng)一放在固定位置token用量統(tǒng)一放在另一個(gè)固定位置整個(gè)響應(yīng)體的層次結(jié)構(gòu)完全一致。我原來(lái)有七八個(gè)分支的解析函數(shù)直接刪掉絕大部分只保留了一個(gè)針對(duì)標(biāo)準(zhǔn)結(jié)構(gòu)的解析邏輯。代碼量一下子少了很多可讀性和可維護(hù)性都上來(lái)了。更重要的是新同事接手項(xiàng)目時(shí)不用再逐個(gè)了解每家供應(yīng)商的響應(yīng)結(jié)構(gòu)了只需要看一份文檔——就是litellm對(duì)外輸出協(xié)議的標(biāo)準(zhǔn)說(shuō)明上手成本大幅降低。3.2 錯(cuò)誤碼與重試邏輯的統(tǒng)一處理響應(yīng)格式統(tǒng)一之外錯(cuò)誤碼體系的統(tǒng)一是我一開(kāi)始沒(méi)預(yù)料到的增值點(diǎn)。未引入網(wǎng)關(guān)前不同供應(yīng)商的報(bào)錯(cuò)風(fēng)格差異很大有的會(huì)返回HTTP層錯(cuò)誤有的會(huì)在響應(yīng)體里放自定義錯(cuò)誤碼有的錯(cuò)誤信息是一大段英文描述很難直接映射到業(yè)務(wù)邏輯里。這就導(dǎo)致我在業(yè)務(wù)代碼里寫重試邏輯時(shí)得針對(duì)不同錯(cuò)誤類型分別判斷哪些值得重試、哪些不重試規(guī)則亂成一團(tuán)。litellm把所有錯(cuò)誤都映射成了一套統(tǒng)一的錯(cuò)誤類型。比如上游模型服務(wù)被限流時(shí)即使原始報(bào)錯(cuò)五花八門通過(guò)網(wǎng)關(guān)出去的標(biāo)準(zhǔn)響應(yīng)里業(yè)務(wù)端看到的都是統(tǒng)一的限流錯(cuò)誤標(biāo)識(shí)這是一個(gè)非常關(guān)鍵的收斂。業(yè)務(wù)端重試策略只需要判斷這一種錯(cuò)誤即可統(tǒng)一限流錯(cuò)誤說(shuō)明上游資源暫時(shí)不足可以保守重試統(tǒng)一超時(shí)錯(cuò)誤說(shuō)明請(qǐng)求處理時(shí)間過(guò)長(zhǎng)可能需要調(diào)整超時(shí)時(shí)間或改用更快的模型統(tǒng)一鑒權(quán)錯(cuò)誤說(shuō)明密鑰或配置有問(wèn)題這類錯(cuò)誤重試沒(méi)有意義直接告警。我把這套邏輯用在了項(xiàng)目里的一個(gè)批處理任務(wù)上。之前對(duì)接多家供應(yīng)商時(shí)重試參數(shù)五花八門現(xiàn)在全部收斂成統(tǒng)一策略批處理任務(wù)的失敗率肉眼可見(jiàn)地下降了。3.3 流式輸出來(lái)回切換的實(shí)際效果除了普通響應(yīng)流式輸出的一致性也值得一提。很多應(yīng)用在做打字機(jī)效果時(shí)需要用到流式輸出也就是數(shù)據(jù)一段段實(shí)時(shí)返回。不同供應(yīng)商的流式輸出格式差別同樣很大有的按行返回有的按事件塊返回有的還夾雜心跳包和額外元數(shù)據(jù)解析成本非常高。通過(guò)litellm做流式轉(zhuǎn)發(fā)后業(yè)務(wù)端收到的就是統(tǒng)一的流式格式。我在項(xiàng)目里寫了一個(gè)簡(jiǎn)單的測(cè)試分別用三家模型跑同一段流式輸出然后對(duì)比收到的每一幀數(shù)據(jù)結(jié)果前綴部分完全一致幀結(jié)構(gòu)也相同。這意味著前端展示邏輯只寫一套流式解析就能通用不用再針對(duì)不同供應(yīng)商做特殊處理。我還試過(guò)在同一個(gè)請(qǐng)求里來(lái)回切換普通模式和流式模式只要在請(qǐng)求參數(shù)里改一個(gè)布爾值就可以網(wǎng)關(guān)層會(huì)正確處理不需要業(yè)務(wù)端做任何額外的適配工作。4. 多模型自動(dòng)切換、負(fù)載均衡與失敗重試的配置策略4.1 把三個(gè)模型配置成一個(gè)“虛擬模型組”的具體寫法前面提到model_list里的model_name可以重復(fù)這個(gè)特性可以用來(lái)實(shí)現(xiàn)“多模型對(duì)外暴露為同一個(gè)名稱”的效果。我把三個(gè)不同供應(yīng)商的模型配置成了同一個(gè)對(duì)外名稱業(yè)務(wù)方完全無(wú)感知但網(wǎng)關(guān)層已經(jīng)具備了三選一的能力。配置寫法大致如下model_list: - model_name: unified-model litellm_params: model: 供應(yīng)商A/模型A api_key: os.environ/密鑰A - model_name: unified-model litellm_params: model: 供應(yīng)商B/模型B api_key: os.environ/密鑰B - model_name: unified-model litellm_params: model: 供應(yīng)商C/模型C api_key: os.environ/密鑰C三個(gè)真實(shí)模型共享同一個(gè)對(duì)外名稱。你可能會(huì)問(wèn)它們效果完全不同對(duì)外暴露同一個(gè)名字業(yè)務(wù)方怎么知道用哪個(gè)答案是業(yè)務(wù)方不需要知道。這種配置方式通常搭配路由策略使用由網(wǎng)關(guān)層決定每次請(qǐng)求實(shí)際轉(zhuǎn)發(fā)給哪個(gè)模型。這樣配置之后想要在三個(gè)模型之間切換不再需要改業(yè)務(wù)代碼只需要調(diào)整網(wǎng)關(guān)層的策略就行。我在一個(gè)內(nèi)部工具項(xiàng)目里就是這么配的。不同時(shí)候不同模型的可用性、效果、成本都在變化有了這層虛擬模型組我可以隨時(shí)把某個(gè)表現(xiàn)不好的模型從路由池里摘掉或者調(diào)低它的權(quán)重全部在配置文件里完成整個(gè)過(guò)程業(yè)務(wù)方無(wú)感知。4.2 負(fù)載均衡與重試的細(xì)節(jié)參數(shù)配置好多個(gè)模型之后litellm會(huì)默認(rèn)按順序輪詢分發(fā)請(qǐng)求但真正生產(chǎn)環(huán)境肯定要做更精細(xì)的控制。我實(shí)際使用的配置里加了這樣幾項(xiàng)參數(shù)litellm_settings: num_retries: 3 request_timeout: 30 fallbacks: [{ unified-model: [供應(yīng)商A/模型A, 供應(yīng)商B/模型B] }] allowed_fails: 3 cooldown_time: 60逐項(xiàng)說(shuō)下我的理解。num_retries是同一個(gè)請(qǐng)求在遇到暫時(shí)性錯(cuò)誤時(shí)的重試次數(shù)我設(shè)為3次。注意這里有一個(gè)值得注意的機(jī)制超過(guò)指定次數(shù)后如果仍然失敗litellm會(huì)按照f(shuō)allbacks配置的順序把請(qǐng)求轉(zhuǎn)發(fā)給備用模型。比如主模型限流了重試幾次都不行就直接切換備用模型這個(gè)機(jī)制對(duì)線上可用性提升非常明顯。request_timeout是網(wǎng)關(guān)等待上游模型響應(yīng)的最長(zhǎng)秒數(shù)。設(shè)得太短大模型思考時(shí)間長(zhǎng)一點(diǎn)就會(huì)被判定為超時(shí)設(shè)得太長(zhǎng)上游如果卡住了業(yè)務(wù)端會(huì)一直干等。30秒是一個(gè)比較折中的值大家可以根據(jù)實(shí)際請(qǐng)求長(zhǎng)度調(diào)整。cooldown_time是熔斷冷卻時(shí)間。當(dāng)某個(gè)模型連續(xù)出錯(cuò)達(dá)到一定次數(shù)后litellm會(huì)在一段時(shí)間內(nèi)自動(dòng)把它標(biāo)記為不可用不再往它上面分發(fā)新請(qǐng)求。這個(gè)機(jī)制能有效避免一個(gè)故障模型持續(xù)拖垮整個(gè)網(wǎng)關(guān)。4.3 權(quán)重策略在真實(shí)項(xiàng)目中的使用心得除了默認(rèn)的輪詢方式litellm還支持按權(quán)重分配流量。我比較常用的一種策略是按照成本來(lái)分配便宜模型分到的流量多一點(diǎn)貴的模型只在必要時(shí)使用。具體寫法是在每個(gè)模型的litellm_params里加一個(gè)權(quán)重字段配好后每次請(qǐng)求按權(quán)重做隨機(jī)選擇。比如我給模型A配置了較高的權(quán)重意味著平均每十次請(qǐng)求有較多次打給它剩余次數(shù)打給模型B。權(quán)重策略在我實(shí)際使用時(shí)主要解決了兩個(gè)問(wèn)題。一個(gè)是成本控制如果某個(gè)模型雖然效果好但貴我會(huì)給它一個(gè)較低的權(quán)重讓便宜的模型分擔(dān)大部分簡(jiǎn)單請(qǐng)求。另一個(gè)是灰度驗(yàn)證新接入一個(gè)模型時(shí)先給它一個(gè)小的權(quán)重讓它承接一小部分流量觀察一段時(shí)間沒(méi)有問(wèn)題后再逐步調(diào)高權(quán)重相當(dāng)于一種流量灰度機(jī)制。不過(guò)這里要提醒一句權(quán)重策略無(wú)法保證同一用戶的不同請(qǐng)求特性被保留比如希望某個(gè)用戶的所有請(qǐng)求都打到同一個(gè)模型上權(quán)重模式做不到這種情況需要按其他維度做路由最好提前想清楚自己的業(yè)務(wù)是否需要會(huì)話級(jí)或用戶級(jí)一致性。5. 生產(chǎn)環(huán)境必踩的坑與我的修復(fù)過(guò)程5.1 版本重復(fù)安裝帶來(lái)的兼容性問(wèn)題這個(gè)坑我印象很深。最開(kāi)始我是圖省事直接用系統(tǒng)Python環(huán)境裝了litellm后面有一個(gè)項(xiàng)目引入了另一個(gè)依賴庫(kù)安裝時(shí)順便把litellm的依賴版本升了一下。結(jié)果整個(gè)網(wǎng)關(guān)直接起不來(lái)了報(bào)了一個(gè)很長(zhǎng)的依賴沖突錯(cuò)誤關(guān)鍵信息藏在日志中間不仔細(xì)看根本發(fā)現(xiàn)不了。后續(xù)排查發(fā)現(xiàn)系統(tǒng)環(huán)境里同時(shí)存在兩個(gè)版本的litellm相關(guān)文件一個(gè)被舊項(xiàng)目引用一個(gè)新項(xiàng)目又在用另一個(gè)版本兩個(gè)版本之間互相覆蓋導(dǎo)致加載時(shí)出現(xiàn)了錯(cuò)亂。這個(gè)問(wèn)題最終的解決辦法有兩條缺一不可。第一條給litellm單獨(dú)建一個(gè)虛擬環(huán)境和項(xiàng)目環(huán)境隔離。第二條在虛擬環(huán)境里固定litellm的版本號(hào)安裝不輕易升版本。后續(xù)每次要升級(jí)時(shí)先在測(cè)試環(huán)境跑一遍主要流程確認(rèn)沒(méi)有兼容性問(wèn)題后再更新生產(chǎn)環(huán)境。這看起來(lái)是常識(shí)但我在這個(gè)坑上花掉的時(shí)間一點(diǎn)都不少寫出來(lái)是希望后來(lái)者別再重復(fù)一次。5.2 流式輸出超時(shí)與keep-alive參數(shù)另一個(gè)讓我折騰比較久的問(wèn)題是流式輸出偶爾會(huì)“卡住”。具體現(xiàn)象是打字機(jī)效果剛開(kāi)始時(shí)一切正常輸出到一半突然停住過(guò)了一段時(shí)間前端報(bào)超時(shí)錯(cuò)誤。剛開(kāi)始我以為是模型生成太慢調(diào)大了請(qǐng)求超時(shí)時(shí)間問(wèn)題依舊。后來(lái)我去翻了網(wǎng)關(guān)的日志發(fā)現(xiàn)請(qǐng)求其實(shí)一直在正常轉(zhuǎn)發(fā)上游也有數(shù)據(jù)陸續(xù)返回但客戶端和網(wǎng)關(guān)之間的連接被斷開(kāi)了。原因在于流式請(qǐng)求的處理時(shí)間較長(zhǎng)而承接業(yè)務(wù)端與網(wǎng)關(guān)之間的連接服務(wù)在空閑一段時(shí)間后主動(dòng)關(guān)閉了連接。前端沒(méi)有收到任何數(shù)據(jù)自然就認(rèn)為請(qǐng)求超時(shí)了。解決辦法是在網(wǎng)關(guān)和業(yè)務(wù)端的連接層配置保持活躍參數(shù)確保長(zhǎng)連接不因空閑被回收。同時(shí)在流式請(qǐng)求的協(xié)議層約定一個(gè)心跳機(jī)制每隔一段時(shí)間發(fā)送一個(gè)空消息提醒連接不要關(guān)閉。改完之后再長(zhǎng)的輸出也能穩(wěn)定跑完。這個(gè)坑比較隱蔽因?yàn)閳?bào)錯(cuò)信息看起來(lái)像模型問(wèn)題實(shí)際卻是網(wǎng)絡(luò)連接層面的問(wèn)題。排查鏈路值得記錄先確認(rèn)上游是否有數(shù)據(jù)再確認(rèn)數(shù)據(jù)是否到達(dá)網(wǎng)關(guān)最后確認(rèn)網(wǎng)關(guān)到業(yè)務(wù)端的連接是否穩(wěn)定一環(huán)一環(huán)拆開(kāi)看很快就能定位到問(wèn)題出在哪個(gè)環(huán)節(jié)。5.3 并發(fā)額度較低時(shí)的隊(duì)列表現(xiàn)第三個(gè)坑比較讓人頭疼和上游模型服務(wù)的并發(fā)限制有關(guān)。我當(dāng)時(shí)部署的某個(gè)開(kāi)源模型的推理服務(wù)并發(fā)能力比較有限而網(wǎng)關(guān)這邊的請(qǐng)求量又不小導(dǎo)致大量請(qǐng)求打到上游后被限流拒絕。由于網(wǎng)關(guān)本身有重試機(jī)制這些請(qǐng)求會(huì)進(jìn)入重試隊(duì)列重試又繼續(xù)被限流最終形成了一種請(qǐng)求雪崩網(wǎng)關(guān)的線程池被占滿所有請(qǐng)求都在排隊(duì)等待重試包括那些原本可以正常處理的請(qǐng)求。發(fā)現(xiàn)問(wèn)題后我做了三個(gè)調(diào)整。第一在litellm的配置里給這個(gè)模型設(shè)置了一個(gè)每分鐘請(qǐng)求速率上限給上游一個(gè)喘息空間。第二關(guān)閉了對(duì)限流類錯(cuò)誤的自動(dòng)重試讓這類請(qǐng)求快速失敗而不是反復(fù)打上去。第三在業(yè)務(wù)端加了一個(gè)信號(hào)量限制同時(shí)進(jìn)行的請(qǐng)求數(shù)量避免一次性涌入太多。調(diào)整之后整個(gè)系統(tǒng)的穩(wěn)定性明顯好轉(zhuǎn)正常請(qǐng)求的響應(yīng)時(shí)間也降下來(lái)了。這個(gè)坑的本質(zhì)是重試機(jī)制和限流疊加產(chǎn)生了放大器效應(yīng)理解了這個(gè)因果鏈條許多并發(fā)場(chǎng)景下的類似問(wèn)題都能看穿。5.4 啟動(dòng)后找不到配置文件的排查鏈路最后這個(gè)小坑很基礎(chǔ)但幾乎人人都會(huì)遇到我在某個(gè)目錄下啟動(dòng)litellm時(shí)用了相對(duì)路徑指定配置文件啟動(dòng)時(shí)報(bào)找不到文件。單獨(dú)看這條命令一點(diǎn)問(wèn)題沒(méi)有但換到另一個(gè)目錄去啟動(dòng)時(shí)相對(duì)路徑指向的位置就不存在了。這不算什么高深問(wèn)題但解決思路值得總結(jié)。我把配置文件的路徑改成了絕對(duì)路徑同時(shí)在啟動(dòng)腳本里顯式指定配置文件位置避免依賴“當(dāng)前所在目錄”這個(gè)隱式狀態(tài)。后來(lái)我干脆把啟動(dòng)命令封裝成了一個(gè)固定的啟動(dòng)腳本腳本里固定好虛擬環(huán)境路徑、配置文件路徑、日志輸出路徑每次直接執(zhí)行腳本即可。實(shí)踐下來(lái)這樣不僅避免了路徑問(wèn)題還大大降低了誤操作的概率。6. 預(yù)算、密鑰與審計(jì)日志網(wǎng)關(guān)該管的事別交給業(yè)務(wù)代碼6.1 把密鑰管理收斂到config.yaml之后多模型時(shí)代密鑰管理是個(gè)容易被忽視的問(wèn)題。假設(shè)業(yè)務(wù)代碼直接調(diào)用了供應(yīng)商的密鑰那這些密鑰就會(huì)散落在各個(gè)項(xiàng)目的環(huán)境變量里、配置文件里甚至可能被提交到代碼倉(cāng)庫(kù)。一旦泄露風(fēng)險(xiǎn)和排查成本都很高。把litellm當(dāng)作統(tǒng)一入口之后所有供應(yīng)商的密鑰都集中存放在網(wǎng)關(guān)配置層業(yè)務(wù)代碼只認(rèn)網(wǎng)關(guān)的密鑰。這就把密鑰的暴露面從“多份”收斂到了“一份”。我在項(xiàng)目里配合密鑰管理服務(wù)來(lái)存放配置里的敏感信息整個(gè)系統(tǒng)對(duì)供應(yīng)商密鑰的引用全部通過(guò)環(huán)境變量注入不在任何明文配置文件里出現(xiàn)。這里要特別提一下業(yè)務(wù)端使用的網(wǎng)關(guān)密鑰和上游供應(yīng)商密鑰最好嚴(yán)格分離。業(yè)務(wù)端只需要擁有調(diào)用網(wǎng)關(guān)的權(quán)限而真實(shí)的供應(yīng)商密鑰只存在網(wǎng)關(guān)側(cè)。這樣即使某個(gè)業(yè)務(wù)端的密鑰泄露影響范圍也僅限于這個(gè)業(yè)務(wù)端能調(diào)用的模型不至于把上游供應(yīng)商的全部賬戶權(quán)限都暴露出去。6.2 預(yù)算限制字段與實(shí)際觸發(fā)效果litellm還提供了預(yù)算控制能力可以在配置里限制單個(gè)密鑰、單個(gè)模型或整個(gè)網(wǎng)關(guān)的月度消耗上限。我在項(xiàng)目里給內(nèi)部工具配置過(guò)一個(gè)月的總預(yù)算設(shè)置方式是在general_settings里加預(yù)算字段general_settings: master_key: sk-1234 max_budget: 100 budget_duration: 30d意思是30天內(nèi)總消耗預(yù)算為100美元。當(dāng)累計(jì)消耗達(dá)到這個(gè)上限時(shí)網(wǎng)關(guān)會(huì)自動(dòng)拒絕新的請(qǐng)求并返回預(yù)算超限錯(cuò)誤。測(cè)試時(shí)我特意用一個(gè)臨時(shí)密鑰配置了極低的預(yù)算觸發(fā)之后觀察到的現(xiàn)象是業(yè)務(wù)端收到的是統(tǒng)一格式的預(yù)算錯(cuò)誤日志里也能看到網(wǎng)關(guān)記錄了預(yù)算超限的審計(jì)信息。這個(gè)功能最大的價(jià)值在于給業(yè)務(wù)方一個(gè)“安全墊”。特別是那些對(duì)成本敏感的自動(dòng)化任務(wù)如果因?yàn)槟Ｐ驼{(diào)用失控而產(chǎn)生高額賬單預(yù)算限制能避免損失擴(kuò)大。我個(gè)人建議每個(gè)接入網(wǎng)關(guān)的內(nèi)部項(xiàng)目都設(shè)置預(yù)算上限哪怕設(shè)置得寬松一些也好過(guò)完全沒(méi)有防線。6.3 用請(qǐng)求日志定位線上問(wèn)題的流程最后說(shuō)說(shuō)審計(jì)日志。litellm支持把每一次請(qǐng)求的詳細(xì)信息記錄到數(shù)據(jù)庫(kù)包括請(qǐng)求時(shí)間、調(diào)用的模型、消耗的token數(shù)量、響應(yīng)耗時(shí)、狀態(tài)碼等。這些日志在線上問(wèn)題排查時(shí)價(jià)值極高。有一次線上反饋某個(gè)功能變慢了我通過(guò)日志篩選出那個(gè)時(shí)間段內(nèi)的請(qǐng)求記錄按響應(yīng)耗時(shí)排序發(fā)現(xiàn)耗時(shí)長(zhǎng)的主要集中在某個(gè)特定模型上而其他模型基本正常。進(jìn)一步分析之后確認(rèn)是那個(gè)模型的推理服務(wù)負(fù)載過(guò)高導(dǎo)致的于是我把網(wǎng)關(guān)里該模型的權(quán)重降低把流量分流到其他模型上問(wèn)題很快緩解。整個(gè)過(guò)程大概花了十分鐘如果沒(méi)有日志排查這個(gè)問(wèn)題的鏈路會(huì)漫長(zhǎng)得多。建議不要等出問(wèn)題了再考慮加日志從一開(kāi)始就配上數(shù)據(jù)庫(kù)存儲(chǔ)日志養(yǎng)成看日志的習(xí)慣。日志就是系統(tǒng)的黑匣子關(guān)鍵時(shí)刻能幫你省下大量時(shí)間。最后分享一個(gè)我個(gè)人的小習(xí)慣每次修改配置文件前都先備份一份帶日期的副本再動(dòng)原文件。這個(gè)習(xí)慣幫我避免了好幾次“改壞配置但不知道改了什么”的尷尬。另外升級(jí)litellm前我會(huì)先跑一個(gè)測(cè)試腳本把常用的模型調(diào)用、流式輸出、錯(cuò)誤重試全部走一遍確認(rèn)沒(méi)有回歸再正式切換版本。這些看起來(lái)不起眼的細(xì)節(jié)長(zhǎng)期累積下來(lái)是讓整個(gè)網(wǎng)關(guān)穩(wěn)定運(yùn)行的重要保障。