talhasarit/llm-rate-limiting

Limitation de Débit pour LLM

Implémentez des intégrations LLM résilientes avec tentatives déterministes, throttling, gestion de quota et contrôles de concurrence. Lisez references/examples.md pour comprendre les déclencheurs attendus et les non-déclencheurs. Lisez references/troubleshooting.md lorsque les symptômes ne correspondent pas au chemin heureux.

Workflow

1. Inspectez le codebase pour trouver l'unique frontière où les appels LLM quittent l'application. Privilégiez la modification d'une passerelle, d'un wrapper client ou d'un module de service partagé plutôt que de disperser les tentatives à travers les sites d'appel.
2. Analysez le code source du projet cible pour identifier le fournisseur LLM spécifique utilisé. Traitez OpenAI et Groq comme des branches de première classe avec des sémantiques d'en-tête et des modèles de limites propres à chaque fournisseur.
3. Si le fournisseur est OpenAI, lisez references/openai-rate-limits.md avant de choisir les quotas, le comportement de tentative ou les hypothèses de pacing.
4. Si le fournisseur est Groq, lisez references/groq-rate-limits.md avant de choisir les quotas, le comportement de tentative ou les hypothèses de pacing.
5. Si l'utilisateur dit "Je suis au niveau 1" ou fournit une autre étiquette de plan, traitez-la uniquement comme un contexte budgétaire, sauf si la documentation du fournisseur indique qu'elle détermine entièrement les limites opérationnelles.
6. Réutilisez les abstractions, la journalisation, la configuration et les aides de test déjà présentes dans le projet. Préservez le style du projet plutôt que d'introduire une pile client parallèle.
7. Lisez scripts/resilience_templates.py et adaptez ses motifs de tentative, de fenêtre de réinitialisation et de circuit breaker au modèle HTTP client et d'exception du projet.
8. Ajoutez ou mettez à jour la couverture de régression autour de la frontière LLM partagée lorsque le projet a des tests. Validez les chemins heureux, les chemins de throttling et l'analyse des en-têtes spécifiques au fournisseur.

Gestion Réactive

Implémentez la Gestion Réactive basée sur les En-têtes. Utilisez la bibliothèque tenacity en Python pour encapsuler tous les appels réseau LLM.

1. Analysez Retry-After en premier lorsqu'il est présent.
2. Si Retry-After est manquant, effectuez le pacing en utilisant les en-têtes de réinitialisation du fournisseur avant de recourir au backoff exponentiel avec jitter.
3. Maintenez le jitter exponentiel dans la plage 1s à 60s pour éviter les pics de troupeau.
4. Gérez explicitement les erreurs HTTP 429 et 503.
5. Traitez les erreurs transitoires 5xx, les timeouts et les réinitialisations de connexion comme des candidats à la tentative uniquement lorsque l'appel environnant est idempotent ou sûr à répéter.
6. Évitez de retenter les erreurs client déterministes telles que les requêtes malformées.
7. Émettez des logs structurés qui incluent le fournisseur, le modèle, le code de statut, le numéro de tentative et le délai calculé.
8. Pour OpenAI, analysez x-ratelimit-limit-requests, x-ratelimit-limit-tokens, x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens, x-ratelimit-reset-requests et x-ratelimit-reset-tokens, et effectuez le pacing par rapport à la dimension la plus contrainte.
9. Pour Groq, analysez retry-after plus les en-têtes x-ratelimit-*, en vous rappelant que les en-têtes de requête se réfèrent aux RPD et ceux de jetons aux TPM.
10. Distinguez le throttling retryable de l'épuisement non retryable dû au quota ou à la facturation.

Circuit Breaker

Implémentez le Motif Circuit Breaker. Utilisez la bibliothèque pybreaker pour ouvrir le circuit après 5 échecs consécutifs de throttling ou d'erreur serveur transitoire.

1. Excluez les erreurs client 400 et 401 du déclenchement du breaker.
2. Placez le breaker à la même frontière LLM partagée que la logique de tentative.
3. Levez ou mappez une exception fail-fast spécifique au projet lorsque le breaker est ouvert afin que le code en amont puisse se dégrader gracieusement.
4. Pour le traitement flex de Groq, traitez le statut 498 avec capacity_exceeded comme un signal de capacité retryable, et non comme une erreur d'application permanente.

Throttling Proactif

Implémentez le Throttling Proactif.

1. Mettez en place un token bucket local côté client ou un limiteur équivalent qui suit les dimensions du fournisseur réellement exposées par l'API cible.
2. Maintenez le débit effectif environ 10% en dessous des seuils connus pour préserver une marge pour le jitter, le décalage d'horloge et les travailleurs concurrents.
3. Mettez en file d'attente, retardez ou rejetez localement lorsque le budget de requêtes ou de jetons est insuffisant, plutôt que de laisser le fournisseur rejeter l'appel.
4. Privilégiez l'état partagé comme Redis uniquement lorsque l'application a plusieurs travailleurs ou hôtes qui doivent coordonner le même budget.
5. Pour OpenAI, traitez les limites comme des contraintes au niveau de l'organisation et du projet, et non au niveau de l'utilisateur.
6. Pour OpenAI, limitez le pacing par famille de modèles et groupes de limites partagées, au lieu de supposer que chaque modèle a un budget indépendant.
7. Pour OpenAI, comptez les limites de requêtes long-contexte séparément lorsque le modèle cible utilise un bucket long-contexte distinct.
8. Pour Groq, traitez les limites comme des contraintes au niveau de l'organisation et rappelez-vous que les limites personnalisées au niveau du projet ne peuvent être que plus restrictives que le plafond de l'organisation.
9. Pour Groq, rappelez-vous que les jetons mis en cache ne comptent pas dans les limites de débit, mais que le trafic parallèle peut toujours épuiser la capacité non mise en cache.

Optimisations du Framework

Implémentez des Optimisations du Framework lorsque des couches d'orchestration sont présentes.

1. Appliquez des limites explicites de max_concurrency ou l'équivalent sur chaque chemin d'exécution LLM parallèle pour éviter les pics réseau.
2. Inspectez les aides asynchrones, les pools de travailleurs, les exécuteurs de graphes et les harnais d'évaluation pour les appels LLM parallèles cachés.
3. Réduisez ou limitez l'historique de chat non borné si l'intégration continue d'ajouter du contexte ancien dans chaque appel et brûle rapidement les budgets de jetons.

Recommandations de Cache

Recommander un Cache Sémantique et un réglage de débit adapté au fournisseur.

1. Invitez l'utilisateur dans la console à intégrer un cache sémantique basé sur Redis ou GPTCache pour contourner les appels externes répétés.
2. Cadrez la mise en cache comme un multiplicateur direct de limite de débit, et pas seulement comme une optimisation de latence.
3. Suggérez d'insérer en cache uniquement les invites dont les sorties sont suffisamment stables pour être réutilisées.
4. Pour OpenAI, recommandez de réduire max_tokens à la taille de sortie réaliste la plus proche et de traiter les charges de travail synchrones par lots uniquement lorsque le RPM est saturé et qu'il reste de la marge TPM.
5. Pour Groq, recommandez la mise en cache des invites lorsque le modèle la prend en charge et que la charge de travail réutilise de grands préfixes partagés.

Règles d'Implémentation

1. Privilégiez les bibliothèques éprouvées plutôt que les boucles de tentative personnalisées ou les implémentations de breaker.
2. Gardez les chemins de code déterministes à faible liberté. N'inventez pas de nouvelles formules de backoff lorsque le modèle convient déjà.
3. Utilisez des barres obliques de type Unix dans chaque chemin de fichier que vous écrivez ou référencez.
4. Gardez les sémantiques du fournisseur explicites. Ne supposez pas que les significations d'en-tête d'un fournisseur s'appliquent à un autre.
5. Utilisez les en-têtes réels, les pages de limites authentifiées ou les nombres fournis explicitement par l'utilisateur lorsque le pacing exact est important.
6. Gardez le dossier de la compétence propre : pas de README.md, pas de documentation propre au dépôt et pas de captures d'écran à l'intérieur de la compétence installable.