LiteLLM 限流診斷更新:收到 429 或換模型,怎麼查是哪一條額度擋住?

LiteLLM 新增限流原因與備援回應資訊。解析 rate_limited_by、模型配額與客戶共同額度的差別,以及回應標頭、花費紀錄和串流事件的適用邊界。

Share
LiteLLM 官方限流標頭影片封面,文字為 Rate-limit headers
LiteLLM 在回應資訊中標示擋住請求的規則,協助判斷拒絕與備援原因。圖片來源:LiteLLM 官方帳號。 圖片來源:官方原文。

LiteLLM 的限流診斷更新,讓服務遇到 429 錯誤時能直接讀出哪一層規則擋住請求。若系統改用備援模型回答,也會留下切換次數與觸發原因,避免只看到成功卻不知道答案換了來源。

LiteLLM 官方於 2026 年 11 月 12 日 UTC 分享這項功能,對應十一日合併的兩項原始修正。這次新聞是回應資訊變得可追查,並非所有模型限制被取消,也不等於新發布一個模型。

LiteLLM 是把不同模型服務放在共同介面後方的代理層。它能替應用安排配額與備援,因此同一個錯誤碼可能來自金鑰、團隊、專案或某位使用者在指定模型的額度。

新版讓這些原因透過回應標頭傳回,不必依賴容易改寫的錯誤句子。標頭是服務隨回應附上的資訊欄位,程式可以據此決定等待、降流量或交給管理者處理。

我會先把失敗原因接到既有紀錄,再確認備援後的結果是否仍符合原任務。若限制是整個客戶的共同額度,換另一個模型不會因此取得新的使用權。

從沒有備援時的 429 開始,才能看懂成功切換後留下的資訊,以及兩種情況為什麼需要不同處理。

429 回應直接指出限流層級,不必拆錯誤句子

新增的 rate_limited_by 標頭,指出 LiteLLM 本地限流器拒絕請求的規則。這讓程式取得一個可辨認的欄位,不用再從錯誤句子裡搜尋某段文字,猜測是哪個額度先被用完。

429 是表示請求受到頻率或用量限制的回應碼。在代理服務裡,限制可能由服務提供者設定,也可能來自團隊自己管理的 LiteLLM 規則。這次新增資訊針對後者,不能推論所有外部供應商都會回傳相同欄位。

過去錯誤文字已經可能提到規則名稱,但句子通常是給人閱讀。應用若依固定文字位置拆出原因,一旦訊息呈現調整,告警或重試程式就可能讀錯,留下只有請求失敗的籠統紀錄。

將規則名稱放進獨立標頭後,服務能按相同欄位分類。例如金鑰層級與團隊層級的限制,可以走不同管理流程,不必讓所有使用者都收到同一句稍後再試,卻不知道是否需要管理者調整配置。

標頭仍只是診斷資訊,不會提高使用額度。知道哪條規則拒絕之後,應用需要依原有政策等待或處理,而不是看到可讀原因,就認為可以跳過代理重新呼叫其他服務。

採用前也要確認部署版本含有對應兩項修正。原始 PR 合併與官方分享提供可查的程式差異,不能由一則功能貼文推論每個既有穩定版本、每種部署都已經具備這些回應欄位。

因為反向代理或應用閘道也可能處理回應標頭,接入時應核對資訊有沒有一路保留到實際呼叫者。只在模型代理那一端看見欄位,還不能證明前端或後續服務已讀得到,這會直接影響診斷程式能否採取預期行動。

找出哪條規則後,才知道下一步應等額度重設,還是檢查模型自己的配額。規則名稱還需要搭配限制類型,才能完整對回實際設定。

LiteLLM 官方限流標頭影片封面,文字為 Rate-limit headers
LiteLLM 在回應資訊中標示擋住請求的規則,協助判斷拒絕與備援原因。圖片來源:LiteLLM 官方帳號。 圖片來源:官方原文。
官方示意限流拒絕與備援後的回應欄位,並非本刊實測。影片來源:LiteLLM 官方帳號。 來源:官方原文。

規則名稱要搭配類型,才能對回實際設定

同一層規則可能限制請求數,也可能限制模型處理的內容量。只知道是某位客戶的額度不夠,還不能決定是降低呼叫頻率,或縮小單次處理內容。

rate_limit_type 提供 tokens 或 requests 這類型別。token 是模型切分內容後計算的單位,請求數則計算呼叫次數,兩種限制的分母不同,不應混成一個通用的剩餘次數。

例如 model_per_end_user 指一位使用者在指定模型的限制。若類型是 tokens,就需要對照該模型的內容額度。若類型是 requests,則是呼叫數規則。這是欄位組合的解讀,不是直接暴露使用者個人資料的理由。

應用紀錄可以保留規則範圍與模型名稱,再按自己的授權方式連到內部工作。沒有必要為了排查限流,把原始提示、個人聯絡資訊或憑證全部寫進每一筆告警,因為這些內容未必有助於分辨觸發條件。

原本的重設時間與 retry-after 也仍有用途。retry-after 是建議等待多久再嘗試,程式若遇到拒絕就立刻重送,多半只會增加同一限制下的失敗次數,並讓真正需要處理的工作更難追蹤。

剩餘額度標頭並不是這次才全部新增。原始修正特別指出,部分客戶模型剩餘量早已存在,新的重點是說明拒絕原因。若監控畫面要呈現兩者,應分清現有資料與新增欄位,避免把缺少監控圖誤判成限流未啟用。

當只有指定模型的配額用完,已有備援配置才可能讓工作繼續。但成功回應也必須留下來源,因為切換後的答案不一定來自最初選擇的模型。

備援成功仍要記錄,答案可能已經換模型

本地每模型限流觸發備援後,回應會增加切換計數並記下限流原因。這讓應用能區分原模型成功回答,以及原模型被限制後改由其他模型完成。

備援是事先配置的替代路徑,並非這次才新增的無條件切換能力。團隊原本需要決定哪些模型可以互相替代,也可以沿用既有設定關閉每模型限流所觸發的備援。

這次修正的一個問題,是請求在進入路由器之前就被本地額度規則改送,回應的 attempted-fallbacks 卻沒有計入那一段。於是呼叫者看到零次切換,可能以為原先指定模型直接完成。

新版會將這種切換加入計數,再與路由器自身的切換次數一起呈現。新增的 x-litellm-fallback-reason 則以 rate_limit 加上規則範圍,說明這次改路是因本地配額,而非單純外部服務出錯。

實際服務模型也能從相應模型群組欄位對照。例如原本請求甲模型,最後由已配置的乙模型回答,應用可以把這項差異存進工作紀錄,方便日後核對品質或解釋回答風格為何改變。

對有固定模型要求的任務,回應成功還不足以完成驗收。若替代模型不支援相同的工具、輸入型態或品質要求,應用需要先決定可接受的備援範圍,而不能等答案產生後才發現無法使用。

若任務允許備援,也應在品質測試裡納入替代結果。因為同一個成功碼可能對應不同模型,單看失敗率下降,無法確認使用者需要的欄位、語言或工具內容仍正確。這能讓備援的可用性與任務品質分別被驗收。

模型層級能切換,不代表跨模型共用的額度也能用同樣方法繞過。不同限制範圍的目的不同,應用必須按同一套規則處理。

客戶總額度用完,換模型仍然會被擋

客戶共同配額的目的,是限制整體使用,並非只限制一個模型名稱。若共同內容額度已經用完,把同一位客戶轉到另一個模型,也不會因此得到新的使用權。

原始 PR 用兩種情境說明這項差異。一種是客戶只有某個模型的額度不足,可以沿既有配置改用備援。另一種是客戶整體額度已耗盡,無論原模型或替代模型,都仍收到拒絕。

這項區分能避免錯誤的自動修復。若應用對所有 429 都輪流嘗試更多模型,共同配額問題並不會消失,反而增加等待、重複紀錄與服務負擔,讓使用者更難知道工作是否還會接續。

較合理的處理,是先看觸發範圍,再決定等待、排程或交給額度管理者。對共同額度而言,保存尚未完成的工作,比不停切換更有用,因為之後恢復時不必重新處理已完成部分。

原始示範中的小額度,是為了容易重現拒絕與備援,不是建議所有正式服務採用的預設。團隊的限制仍應依實際流量、模型成本與角色責任設定,不能直接照搬測試數字。

維護者使用兩個代理工作程序、共用 Redis 與資料庫,並讓模型回傳模擬答案驗證欄位。這能檢查代理層的行為,不能據此推論真實模型品質、上游服務延遲或生產負載表現,本刊也沒有自行重現這組環境。

限流原因清楚之後,記錄系統還要知道哪些欄位這次沒有一起變更。否則團隊可能在兩份紀錄看到不同數字,便誤以為其中一份一定錯了。

回應標頭變了,花費紀錄與串流事件仍有邊界

這次主要增加回應的可觀測資訊,不會把所有記帳與串流欄位一併改成相同數字。可觀測是讓系統行為能被記錄和解釋,仍要清楚每個欄位是在什麼階段產生。

原始修正列出,花費紀錄仍使用路由器的切換計數。因此在本地配額進入路由前已觸發備援的情況,回應標頭可能顯示一次,花費紀錄卻仍是零,兩者計算範圍並不相同。

這個限制對建立監控圖很重要。若把不同來源的計數直接相減,就可能製造不存在的差額。若只選其中一個當成全部歷史,又可能漏掉本地配額觸發的切換。

串流的 fallback_metadata 事件也沒有在這次一併變更。需要逐字傳回的應用,應按實際可取得的回應欄位與事件安排監控,不能因一般回應多了標頭,就推論每一個串流事件都已同步擴充。

外部供應商錯誤造成的備援,亦不保證有這個新的限流原因欄位。它描述的是本地限流範圍,缺少欄位時應回查原有錯誤與路由資訊,不能自動解讀成從未切換或絕對沒有遇到限制。

系統也會移除客戶端傳入、屬於路由器保留的來源標記,避免呼叫者自行植入一個看似可信的備援原因。這保住的是這項標記的來源,應用仍需保護自己的紀錄與讀取權限。

告警也可以按原因分流。頻率型限制若可等待,先保留佇列。持續出現同一團隊額度拒絕,則交給有權調整配置的人檢查。這是根據欄位設計的接入建議,不代表這次更新已替所有部署自動建立排程或告警流程。

因此,驗收應同時保留回應與既有紀錄,確認程式讀到的是哪個來源。先在低風險環境逐一測沒有備援、備援成功與共同額度拒絕,比單純確認畫面多一個欄位更有意義。

LiteLLM 限流診斷常見問題與接入順序

所有 429 都能直接用 rate_limited_by 解釋嗎?

這次欄位來自 LiteLLM 本地限流器。上游供應商也可能回傳 429,實際欄位要按其回應與代理處理方式確認,不能把兩種來源混為一談。

看到成功回應,就代表原模型有回答嗎?

不一定。已有備援配置時,其他模型可能完成請求,應對照實際模型與切換資訊,再判斷結果是否符合任務要求。

換到不同模型,可以繼續使用耗盡的客戶共同額度嗎?

共同額度仍會限制該客戶,模型切換不能繞過。應保留工作進度並依政策等待或處理,而不是反覆重送更多請求。

先讓每次拒絕與切換都有原因,再安排重試與告警,才不會靠增加請求掩蓋原本限制。部署時先核對相應修正是否已包含,再用自己的三種回應情境回歸,才能把新增欄位轉成可採用的診斷依據。

延伸閱讀:LiteLLM 1.107.0 遭供應鏈攻擊:原碼標籤乾淨,為何安裝包仍能竊取密鑰?

延伸閱讀:Vercel Virtual Models 教學:同一個模型名稱,如何管理團隊 AI 設定?

原始資料來源