talhasarit/llm-rate-limiting

LLM レート制限

OpenAI と Groq に対応した、確定的リトライ、スロットリング、割り当て管理、同時実行制御を備えた堅牢な LLM 統合を実装します。期待されるトリガーと非トリガーを理解するには references/examples.md を読んでください。症状が正常な動作と一致しない場合は references/troubleshooting.md を読んでください。

ワークフロー

1. コードベースを調査し、LLM 呼び出しがアプリケーションを離れる単一の境界を見つけます。リトライを呼び出し箇所に散在させるよりも、1 つの共有ゲートウェイ、クライアントラッパー、またはサービスモジュールを変更することを推奨します。
2. ターゲットプロジェクトのソースコードを分析し、使用中の特定の LLM プロバイダを特定します。OpenAI と Groq は第一級のブランチとして扱い、プロバイダ固有のヘッダーセマンティクスと制限モデルを使用します。
3. プロバイダが OpenAI の場合は、references/openai-rate-limits.md を読んでから、割り当て、リトライ動作、またはペーシングの前提を選択します。
4. プロバイダが Groq の場合は、references/groq-rate-limits.md を読んでから、割り当て、リトライ動作、またはペーシングの前提を選択します。
5. ユーザーが「私は Tier 1 です」などのプランラベルを指定した場合は、プロバイダのドキュメントがそのラベルが運用上の制限を完全に決定すると明示しない限り、予算コンテキストとしてのみ扱います。
6. プロジェクトに既存の抽象化、ログ、設定、テストヘルパーを再利用します。プロジェクトのスタイルを維持し、並列のクライアントスタックを導入しないようにします。
7. scripts/resilience_templates.py を読み、そのリトライ、リセットウィンドウ、およびサーキットブレーカーパターンをプロジェクトの HTTP クライアントと例外モデルに適応させます。
8. プロジェクトにテストがある場合は、共有 LLM 境界の周りに回帰カバレッジを追加または更新します。正常系、スロットリング系、およびプロバイダ固有のヘッダーパース系を検証します。

リアクティブ処理

リアクティブなヘッダ駆動型処理を実装します。Python では tenacity ライブラリを使用して、すべての LLM ネットワーク呼び出しをラップします。

1. Retry-After が存在する場合は、それを最初にパースします。
2. Retry-After がない場合は、指数バックオフ＋ジッターにフォールバックする前に、プロバイダのリセットヘッダーを使用してペーシングします。
3. 指数ジッターは 1s から 60s の範囲に抑え、シンデレラ（スケールが急増する）スパイクを回避します。
4. HTTP 429 および 503 エラーを明示的に処理します。
5. 一時的な 5xx、タイムアウト、および接続リセットエラーは、周囲の呼び出しがべき等であるか安全に繰り返せる場合にのみリトライ候補として扱います。
6. 不正なリクエストなどの確定的なクライアントエラーはリトライしません。
7. プロバイダ、モデル、ステータスコード、リトライ試行回数、および計算された遅延を含む構造化ログを出力します。
8. 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 をパースし、最も制約のあるディメンションに合わせてペーシングします。
9. Groq の場合は、retry-after と x-ratelimit-* ヘッダーをパースします。リクエストヘッダーは RPD、トークンヘッダーは TPM を参照することに注意してください。
10. リトライ可能なスロットリングと、リトライ不可能な割り当て枯渇または課金枯渇を区別します。

サーキットブレーカー

サーキットブレーカーパターンを実装します。pybreaker ライブラリを使用して、5 回連続のスロットリングまたは一時的なサーバー障害の後に回路を開きます。

1. 400 および 401 のクライアントエラーはブレーカーをトリップさせないように除外します。
2. ブレーカーはリトライロジックと同じ共有 LLM 境界に配置します。
3. ブレーカーが開いているときは、上流のコードがグレースフルに劣化できるように、プロジェクト固有のフェイルファスト例外を発生させるかマッピングします。
4. Groq のフレックス処理の場合、ステータス 498 と capacity_exceeded は永続的なアプリケーションエラーではなく、リトライ可能な容量シグナルとして扱います。

プロアクティブスロットリング

プロアクティブスロットリングを実装します。

1. ターゲット API が実際に公開しているプロバイダのディメンションを追跡する、ローカルのクライアントサイドトークンバケットまたは同等のリミッターをセットアップします。
2. 既知のしきい値よりも約 10% 低い実効スループットを維持し、ジッター、クロックスキュー、および同時ワーカー用のヘッドルームを確保します。
3. 十分なリクエストまたはトークンバジェットがない場合は、プロバイダに呼び出しを拒否させる代わりに、ローカルでキューに入れる、遅延させる、または拒否します。
4. 同じバジェットを調整する必要がある複数のワーカーまたはホストがアプリケーションにある場合にのみ、Redis などの共有状態を優先します。
5. OpenAI の場合、制限は組織レベルおよびプロジェクトレベルの制約として扱い、ユーザーレベルの制約としては扱いません。
6. OpenAI の場合、すべてのモデルが独立したバジェットを持つと想定するのではなく、モデルファミリーおよび共有制限グループごとにペーシングをスコープします。
7. OpenAI の場合、ターゲットモデルが別個の長いコンテキストバケットを使用する場合は、長いコンテキスト要求制限を個別に考慮します。
8. Groq の場合、制限は組織レベルの制約として扱い、プロジェクトレベルのカスタム制限は組織の上限よりも制限的にしかできないことを覚えておきます。
9. Groq の場合、キャッシュされたトークンはレート制限にカウントされませんが、並列トラフィックは非キャッシュ容量を枯渇させる可能性があることを覚えておきます。

フレームワーク最適化

オーケストレーションレイヤーが存在する場合、フレームワーク最適化を実装します。

1. すべての並列 LLM 実行パスに明示的な max_concurrency または同等のファンアウト制限を適用し、ネットワークスパイクを防止します。
2. 非同期ヘルパー、ワーカープール、グラフランナー、および評価ハーネスに隠れた並列 LLM 呼び出しがないか検査します。
3. 統合が古いコンテキストをすべての呼び出しに追加し続け、トークンバジェットを急速に消費する場合は、無制限のチャット履歴をトリミングまたは制限します。

キャッシングガイダンス

セマンティックキャッシングとプロバイダ対応のスループット調整を推奨します。

1. コンソールでユーザーに、Redis バックアップのセマンティックキャッシュまたは GPTCache を統合して、繰り返される外部呼び出しをバイパスするように促します。
2. キャッシングをレイテンシ最適化だけでなく、直接的なレート制限の乗数として位置付けます。
3. 出力が再利用に十分安定しているプロンプトにのみ、キャッシュ挿入を提案します。
4. OpenAI の場合、max_tokens を最も近い現実的な出力サイズに減らし、RPM が飽和していて TPM ヘッドルームが残っている場合にのみ同期ワークロードをバッチ処理することを推奨します。
5. Groq の場合、モデルがサポートし、ワークロードが大きな共有プレフィックスを再利用する場合に、プロンプトキャッシングを推奨します。

実装ルール

1. カスタムのリトライループやブレーカー実装よりも、実績のあるライブラリを優先します。
2. 確定的なコードパスは自由度を低く保ちます。テンプレートが既に適合している場合は、新しいバックオフ式を発明しないでください。
3. 記述または参照するすべてのファイルパスに Unix スタイルのスラッシュ（/）を使用します。
4. プロバイダのセマンティクスを明示的に保持します。あるプロバイダのヘッダー意味が別のプロバイダに適用されると想定しないでください。
5. 正確なペーシングが重要な場合は、実際のヘッダー、認証された制限ページ、またはユーザーが明示的に指定した数値を使用します。
6. スキルフォルダをクリーンに保ちます。インストール可能なスキル内に README.md、リポジトリのみのドキュメント、スクリーンショットは含めないでください。