Compressez chaque appel à un LLM au niveau du gateway LiteLLM avec Headroom

Les équipes qui utilisent déjà des modèles avec LiteLLM peuvent réduire le nombre de tokens reçus de chaque fournisseur en amont, sans toucher au code des agents ni aux applications. Headroom agit comme une barrière de protection avant l’appel, comprime les résultats des outils ainsi que les fragments RAG avant l’appel au fournisseur, tout en permettant au modèle d’accéder aux versions originales complètes via un outil de récupération si nécessaire.

Headroom, mentionné précédemment dans cette série, comprime les résultats des outils, les enregistrements de journal et les fragments de récupération avant que le modèle ne les voie. La compression en soi n’a jamais été la partie difficile ; l’essentiel résidait dans son intégration dans le flux de la demande.

Début juin 2026, cette difficulté disparaît pour les utilisateurs de LiteLLM : Headroom s’intègre en tant que barrière de protection native du gateway. Un simple interrupteur suffit pour compresser tous les appels qui y passent.

Cette combinaison élimine le dernier prétexte : les économies étaient toujours réelles ; la complexité d’intégration constituait le véritable coût. Au niveau du gateway, il suffit d’activer un interrupteur pour laisser les agents et les clients tranquilles.

Pourquoi un gateway ?

La plupart des équipes de production multi-modèles travaillent déjà à travers un gateway.

LiteLLM est un choix courant : une porte d’entrée compatible OpenAI qui regroupe plus d’une centaine de fournisseurs, avec un routage, des clés, des budgets et un enregistrement centralisés.

Cela fait du gateway le lieu naturel pour la compression. Chaque requête passe déjà par lui, ce qui permet à un seul compresseur de gérer tous les agents, clients et fournisseurs.

Il suffit de le configurer une seule fois au lieu d’ajouter des outils dans chaque application. Comme LiteLLM prend en charge à la fois l’interface OpenAI /v1/chat/completions et celle d’Anthropic /v1/messages, un compresseur de gateway peut gérer à la fois les applications utilisant le format OpenAI, les outils d’Anthropic comme Claude Code, les services de récupération de données et des agents personnalisés.

La compression cesse d’être une fonction ajoutée séparément pour devenir une caractéristique intégrée à la plateforme : c’est la voie habituelle pour les infrastructures, en descendant dans la couche partagée que tout le monde utilise déjà.

Fonctionnement de la protection

Headroom s’intègre en tant que mécanisme de protection avant l’appel : il est activé au sein du cycle de vie de LiteLLM juste avant que le chargement ne soit envoyé vers l’extérieur.

Flux Sidecar :

Client (Claude Code, your app, any OpenAI/Anthropic client)
        |
        v
LiteLLM proxy  ── pre_call ──►  Headroom (sidecar): compress messages
        |                              |
        |   ◄── compressed messages ───┘
        v
LLM provider (OpenAI / Anthropic / Bedrock etc.)

Les clients continuent d’appeler LiteLLM normalement. Avant l’appel, LiteLLM invoque Headroom, remplace les messages par des versions compressées et les renvoie. Les clients et les fournisseurs ne communiquent jamais directement avec Headroom — c’est justement cet aspect invisible qui est essentiel.

Deux propriétés de sécurité sont importantes.

Rien n’est perdu définitivement

C’est la même logique de compression, de stockage en cache et de récupération que décrite précédemment pour Headroom. Les versions originales restent en cache ; LiteLLM met à disposition une fonction retrieve_headroom. Si le modèle a besoin du contexte complet, il utilise cette fonction. La compression est réversible, et non basée sur des pertes aléatoires.

Ouverture en cas de défaillance

Headroom est un composant externe, et non une étape critique en ligne. S’il est indisponible ou lent, les appels se poursuivent sans compression. Vous conservez ainsi les économies lorsque tout fonctionne correctement et le trafic en cas de problème : c’est le mode de défaillance idéal pour une fonction à coût réduit.

Activation

Il faut LiteLLM v1.92.x ou une version ultérieure (les premiers utilisateurs ont employé v1.92.0-dev.1).

L’activation se fait simplement : ajoutez headroom-compression et choisissez le mode de fonctionnement :

• Pour chaque demande — activez-le pour des appels individuels
• Pour chaque clé virtuelle — associez-le à une clé ; tous les appels utilisant cette clé seront compressés
• Globalement — default_on: true pour tout le trafic du proxy

Puisque la protection est intégrée au gateway et gère les deux formats de demande, cette même activation s’applique aux clients compatibles OpenAI, aux clients Anthropic, aux agents développés en interne, aux services de récupération d’informations ainsi qu’aux outils de codage IDE.

Per-key est la solution administrative en un seul énoncé : attachez le garde-fou à une clé virtuelle, distribuez cette clé, et tous les fournisseurs/clientes qui l’utilisent effectueront automatiquement la compression.

Exemple de code Claude : définissez ANTHROPIC_BASE_URL sur le proxy LiteLLM muni de la clé de compression — pas d’installation nécessaire du côté du client, aucune différence de code. La même logique s’applique aux clients de type OpenAI via OPENAI_BASE_URL. L’outil ne sait jamais qu’Headroom existe.

Vérifiez l’application via x-litellm-applied-guardrails ou le panneau Guardrails dans les journaux LiteLLM. Les instructions officielles se trouvent dans le guide des garde-fous de Headroom de LiteLLM (voir références) — suivez-le pour obtenir une configuration exacte correspondant à la dernière version, plutôt que des exemples obsolètes.

Si vous n’utilisez pas le proxy LiteLLM

Le garde-fou du gateway est la solution principale, mais ce n’est pas le seul chemin possible.

Appel de litellm.completion() en Python — utilisez la fonction de rappel :

import litellm
from headroom.integrations.litellm_callback import HeadroomCallback

litellm.callbacks = [HeadroomCallback()]
# Every call is now compressed before it reaches the provider
response = litellm.completion(model="gpt-4o", messages=[...])
response = litellm.completion(model="bedrock/claude-sonnet", messages=[...])

Configuration :

# litellm_config.yaml
litellm_settings:
  callbacks: ["headroom.integrations.litellm_callback.HeadroomCallback"]

Au niveau technique, il utilise async_pre_call_hook de LiteLLM, dans le même cadre de gestion que les mécanismes de protection du gateway. En mode local, la compression s’effectue en interne grâce à compress() de Headroom ; en mode cloud, les données sont transmises à Headroom Cloud pour une récupération et un apprentissage gérés.

Votre propre proxy ASGI ou application web — middleware :

from headroom.integrations.asgi import CompressionMiddleware

app.add_middleware(CompressionMiddleware)
# Intercepts /v1/messages, /v1/chat/completions, /v1/responses, /chat/completions

Les réponses peuvent contenir x-headroom-compressed: true et x-headroom-tokens-saved afin de permettre des mesures par requête.

Seul un agent de codage, sans application Python — proxy autonome :

pip install "headroom-ai[all]"
headroom proxy --port 8787

# then, for Claude Code:
ANTHROPIC_BASE_URL=http://localhost:8787 claude

Règle de décision : proxy LiteLLM → mécanismes de protection. LiteLLM intégré dans du code → appel de retour. Votre propre application web → middleware. Un seul agent de codage → proxy autonome.

Que peut-on attendre, honnêtement

Les économies dépendent du contenu

Les documents indiquent désormais une fourchette : environ 60–95 % de réduction des tokens dans les sorties d’outils et les résultats de recherche à forte teneur JSON ; une réduction plus faible, d’environ 15–20 %, pour le trafic provenant d’agents de codage déjà très dense. Planifiez en fonction de votre charge de travail, et non du plafond théorique. Laissez une partie non compressée en tant que groupe de contrôle afin que les tableaux de bord puissent indiquer les économies réelles.

La compression ajoute une légère latence

Headroom cite environ 15 ms pour de petits fichiers JSON et de 100–200 ms pour de gros blocs de données générés par des outils. La réduction du nombre de tokens entraîne généralement plus de temps de génération que les coûts liés à la compression ; les petits envois de données peuvent ne pas être rentables. C’est pourquoi les contrôles par requête et par clé sont importants.

La tension ancienne persiste

Une compression agressive nuit à la compréhension complète du contexte. retrieve_headroom agit comme une soupape, mais le modèle doit en prendre conscience et demander des informations supplémentaires. En pratique, cela fonctionne bien sans pour autant être une garantie — surveillez la qualité des résultats sur les tâches exigeantes en termes de détails.

C’est une nouveauté

L’intégration du gateway a été mise en place à mi-2026 sur une version très récente de LiteLLM (au départ une version de développement). Tester d’abord avec un cas pilote, évaluer les résultats, puis étendre progressivement l’usage — ne pas activer la production mondiale dès le premier jour.

Sa place dans l’architecture

Les fonctionnalités d’IA utiles pour la production continuent d’être intégrées dans les différentes couches entourant le modèle, tout en étant regroupées au sein des équipes chargées de l’infrastructure existante :

Clients / agents (Claude Code, RAG apps, custom agents)
        |
LiteLLM gateway  ── pre_call guardrail ──►  Headroom compression (+ CCR retrieve)
        |
LLM providers (OpenAI / Anthropic / Bedrock etc.)

L’idée de compression indépendante est désormais une fonctionnalité du gateway. Si LiteLLM constitue déjà l’entrée principale, il s’agit simplement d’un changement de configuration accessible via une clé — pas d’une réarchitecture. C’est pourquoi cela reste intéressant même pour les équipes qui ont omis d’utiliser un proxy de compression distinct auparavant.

Conclusion

L’ajout de cette fonctionnalité à LiteLLM représente un petit changement ayant un impact significatif. En l’activant au niveau du gateway, chaque agent ou client peut envoyer des requêtes plus légères vers les différents fournisseurs, avec les fichiers originaux accessibles en un seul appel.

La conception reste conservatrice là où cela compte : fonction reversible, mode défaillance ouvert, et possibilité de basculer selon la demande, la clé ou à l’échelle globale, afin de pouvoir commencer de manière restreinte.

Si les jetons constituent un poste de coût réel et que LiteLLM est déjà intégré, le coût d’essai est presque nul. Associez une clé, mesurez le trafic en temps réel, puis prenez votre décision.

Références

1. Blog LiteLLM, LiteLLM × Headroom — https://docs.litellm.ai/blog/headroom-integration
2. Documents d’intégration Headroom LiteLLM — https://headroom-docs.vercel.app/docs/litellm
3. Headroom sur GitHub — https://github.com/chopratejas/headroom
4. Documentation LiteLLM — https://docs.litellm.ai/

Plan de déploiement

Semaine un : appliquer la compression à une seule clé virtuelle utilisée par un agent non critique. Comparer le nombre de tokens et la qualité des réponses avec une version non compressée pour les mêmes prompts. Vérifier que x-litellm-applied-guardrails apparaît et que les appels de récupération réussissent lorsqu’on pose une question exigeant beaucoup de détails.

Semaine deux : étendre l’application à une clé d’agent de codage si les économies mesurées sur le trafic volumineux en JSON semblent satisfaisantes. S’attendre à des gains plus faibles en pourcentage dans les contextes de code complexes ; évaluer le succès en fonction des coûts et de la latence, plutôt que de viser le plafond marketing de 95 %.

Semaine trois : décider d’une valeur par défaut globale uniquement si le comportement de secours fonctionne correctement lors d’un exercice de panne délibérée et si les responsables de la qualité donnent leur accord pour les workflows les plus sensibles.

Pourquoi cela relève de l’ingénierie de plateforme

Les équipes de développement ne devraient pas inventer séparément des méthodes de compression. Les passerelles disposent déjà des clés, des budgets et du routage nécessaires. Intégrer la compression dans ce cadre correspond à l’évolution des mécanismes de limitation de débit et d’authentification : une fois intégrée au flux partagé, chaque client hérite de ce contrôle sans avoir à recréer le système.

Gardez en tête ce modèle mental : les clients communiquent avec LiteLLM ; LiteLLM communique avec les fournisseurs ; Headroom se trouve à côté du point d’ancrage avant l’appel. Personne, ni du côté des clients ni de celui des fournisseurs, n’a besoin d’un nouveau SDK. C’est cette disposition invisible qui transforme une idée de recherche en un véritable changement de plateforme.

Fiche décision

• Déjà en mode proxy LiteLLM → mécanisme de protection natif
• litellm.completion en cours d’utilisation → appel de retour
• ASGI personnalisé → middleware
• Agent de codage unique → proxy Headroom autonome

Mesurez d’abord, puis élargissez progressivement. La compression est un levier de coûts, pas une religion.