LLM 速率限制
實作具有確定性重試、節流、配額處理和並發控制的高復原力 LLM 整合。閱讀 references/examples.md 以了解預期的觸發條件與非觸發條件。當症狀與預期路徑不符時，請閱讀 references/troubleshooting.md。
工作流程
- 檢查程式碼庫，找到 LLM 呼叫離開應用程式的單一邊界。優先修改一個共享的閘道、客戶端包裝器或服務模組，而不是將重試邏輯分散到各個呼叫點。
- 分析目標專案原始碼，以識別正在使用的特定 LLM 供應商。將 OpenAI 和 Groq 視為具有供應商特定標頭語意和限制模型的首選分支。
- 如果供應商是 OpenAI，在選擇配額、重試行為或節流假設之前，請先閱讀
references/openai-rate-limits.md。 - 如果供應商是 Groq，在選擇配額、重試行為或節流假設之前，請先閱讀
references/groq-rate-limits.md。 - 如果使用者說「我在第 1 層」或提供其他方案標籤，請將其視為預算背景資訊，除非供應商文件說明它完全決定營運限制。
- 重複使用專案中已有的抽象、日誌記錄、配置和測試輔助程式。保留專案風格，而不是引入平行的客戶端堆疊。
- 閱讀
scripts/resilience_templates.py並將其重試、重置視窗和斷路器模式調整為符合專案的 HTTP 用戶端和例外模型。 - 當專案有測試時，請在共享的 LLM 邊界周圍新增或更新回歸覆蓋範圍。驗證快樂路徑、節流路徑和供應商特定標頭解析。
反應式處理
實作反應式標頭驅動處理。在 Python 中使用 tenacity 函式庫包裝所有 LLM 網路呼叫。
- 當
Retry-After存在時，優先解析它。 - 如果缺少
Retry-After，則在退回到具有抖動的指數補償之前，使用供應商的重置標頭進行節流。 - 將指數抖動保持在
1s到60s的範圍內，以避免驚群效應。 - 明確處理 HTTP
429和503錯誤。 - 僅當周圍的呼叫是冪等的或可以安全重複時，才將短暫的
5xx、超時和連線重置錯誤視為重試候選項。 - 避免重試確定性的用戶端錯誤，例如格式錯誤的請求。
- 發出結構化日誌，其中包含供應商、模型、狀態碼、重試嘗試次數和計算出的延遲。
- 對於 OpenAI，解析
x-ratelimit-limit-requests、x-ratelimit-limit-tokens、x-ratelimit-remaining-requests、x-ratelimit-remaining-tokens、x-ratelimit-reset-requests和x-ratelimit-reset-tokens，並根據最受限的維度進行節流。 - 對於 Groq，解析
retry-after加上x-ratelimit-*標頭，記住請求標頭指的是 RPD，權杖標頭指的是 TPM。 - 區分可重試的節流與不可重試的配額或帳單耗盡。
斷路器
實作斷路器模式。使用 pybreaker 函式庫，在連續 5 次節流或短暫伺服器失敗後斷開電路。
- 排除
400和401用戶端錯誤，使其不會觸發斷路器。 - 將斷路器保持在與重試邏輯相同的共享 LLM 邊界。
- 當斷路器斷開時，引發或對應特定於專案的快速失敗例外，以便上游程式碼能夠優雅地降級。
- 對於 Groq flex 處理，將狀態
498與capacity_exceeded視為可重試的容量訊號，而不是永久的應用程式錯誤。
主動節流
實作主動節流。
- 設定本機用戶端權杖桶或同等限制器，以追蹤目標 API 實際暴露的供應商維度。
- 將有效吞吐量保持在已知閾值的大約
10%以下，以便為抖動、時鐘偏差和並行工作者保留空間。 - 當本機請求或權杖預算不足時，排隊、延遲或在本地拒絕，而不是讓供應商拒絕呼叫。
- 僅當應用程式具有必須協調相同預算的多個工作者或主機時，才優先使用共享狀態（例如 Redis）。
- 對於 OpenAI，將限制視為組織級別和專案級別的約束，而不是使用者級別的約束。
- 對於 OpenAI，按模型系列和共享限制組來界定節流範圍，而不是假設每個模型都有獨立的預算。
- 對於 OpenAI，當目標模型使用不同的長上下文儲存桶時，請單獨考慮長上下文請求限制。
- 對於 Groq，將限制視為組織級別約束，並記住專案級別的自訂限制只能比組織上限更嚴格。
- 對於 Groq，記住快取權杖不計入速率限制，但並行流量仍可能耗盡非快取容量。
框架最佳化
當存在編排層時，實作框架最佳化。
- 在每個並行 LLM 執行路徑上強制執行明確的
max_concurrency或等效的扇出限制，以防止網路尖峰。 - 檢查非同步輔助程式、工作者池、圖形執行器和評估框架中隱藏的並行 LLM 呼叫。
- 如果整合不斷將舊上下文附加到每個呼叫中並快速耗盡權杖預算，請修剪或限制無界聊天記錄。
快取指南
建議使用語意快取和供應商感知的吞吐量調整。
- 在控制台中提示使用者整合 Redis 支援的語意快取或 GPTCache，以繞過重複的外部呼叫。
- 將快取視為直接的速率限制倍增器，而不僅僅是延遲最佳化。
- 僅建議對輸出足夠穩定以供重複使用的提示進行快取插入。
- 對於 OpenAI，建議將
max_tokens減少到最接近的實際輸出大小，並且僅在 RPM 飽和且 TPM 有餘量時批次處理同步工作負載。 - 對於 Groq，當模型支援且工作負載重複使用大型共享前綴時，建議使用提示快取。
實作規則
- 優先使用經過實戰考驗的函式庫，而不是自訂的重試迴圈或斷路器實作。
- 保持確定性程式碼路徑低自由度。當範本已適用時，不要發明新的補償公式。
- 在您編寫或引用的每個檔案路徑中使用 Unix 風格的正斜線。
- 保持供應商語意明確。不要假設一個供應商的標頭含義適用於另一個供應商。
- 當精確節流很重要時，使用實際標頭、經過驗證的限制頁面或明確的使用者提供的數字。
- 保持技能資料夾乾淨：在可安裝的技能中沒有
README.md、沒有僅限儲存庫的文件，也沒有螢幕截圖。