Kompresuj każde wezwanie LLM w bramce LiteLLM za pomocą Headroom
Headroom jako zabezpieczenie przed wywołaniami w LiteLLM kompresuje każde wywołanie LLM: odwracalna kompresja, projekt typu fail-open, stopniowe wdrażanie dla poszczególnych kluczy oraz mierzalna oszczędność tokenów.
Źródła: Compress Every LLM Call at the Gateway: Headroom on LiteLLM
Zespoły, które już używają modeli z LiteLLM, mogą zmniejszyć liczbę odbieranych tokenów od każdego dostawcy, nie wpływając na kod agenta i aplikacji. Headroom działa jako zabezpieczenie przed połączeniem, skraca wyniki narzędzi oraz fragmenty danych RAG przed wywołaniem dostawcy, a jednocześnie pozwala modelowi na pobieranie pełnych oryginałów za pomocą narzędzia do wyszukiwania w razie potrzeby.
Headroom, omawiany wcześniej w tej serii, skraca wyniki narzędzi, pliki logów oraz fragmenty danych przed tym, jak model je zobaczy. Samo kompresowanie nigdy nie było trudne – problemem była integracja tego rozwiązania z ścieżką żądania.
Od czerwca 2026 roku ten problem znika dla użytkowników LiteLLM: Headroom jest integrowany jako standardowe zabezpieczenie bramy. Wystarczy jeden przycisk, aby skompresować każde połączenie przechodzące przez tę bramę.
To połączenie eliminuje ostatni powód do obaw. Oszczędności zawsze były rzeczywiste; trudnością była integracja. Przy bramie wystarczy przełączyć jeden przycisk, aby nie wpływać na agenty i klientów.
Dlaczego brama?
Większość zespołów produkcyjnych pracujących z wieloma modelami już korzysta z bramy.
LiteLLM jest popularnym wyborem: jedna brama kompatybilna z OpenAI obsługująca ponad sto dostawców, przy czym routowanie, klucze, budżety oraz logowanie są centralizowane.
Dzięki temu brama staje się naturalnym miejscem do stosowania kompresji. Każda prośba i tak przechodzi przez nią, więc jeden kompresor wystarcza do obsługi wszystkich agentów, klientów i dostawców.
Konfigurujesz to raz zamiast instalować narzędzia w każdym aplikacji. Ponieważ LiteLLM obsługuje zarówno interfejs OpenAI /v1/chat/completions, jak i Anthropic /v1/messages, kompresor w bramie może obsługiwać aplikacje używające formatu OpenAI, narzędzia w stylu Anthropic takie jak Claude Code, usługi wyszukiwania oraz specjalnie opracowane agenty.
Kompresja przestaje być dodatkowym elementem i staje się funkcją platformy – to standardowa ścieżka dla infrastruktury: w dół łańcucha do warstwy wspólnej, którą wszyscy już używają.
Jak działa zabezpieczenie
Headroom integruje się jako zabezpieczenie przed wysyłką wiadomości: w ramach cyklu życia LiteLLM, tuż przed przesłaniem treści do odbiorcy.
Przepływ 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.)
Klienci nadal korzystają z LiteLLM w normalny sposób. Przed wysyłką wiadomości LiteLLM wywołuje Headroom, zastępuje je skompresowanymi wiadomościami i przekazuje dalej. Klienci oraz dostawcy nigdy nie komunikują się bezpośrednio z Headroom – właśnie ta niewidzialność jest kluczowa.
Ważne są dwie właściwości bezpieczeństwa.
Nic nie jest trwale tracone
To ta sama zasada kompresji, przechowywania w pamięci cache i odzyskiwania danych co opisano wcześniej w artykule o Headroom. Oryginalne dane pozostają w pamięci cache; LiteLLM udostępnia narzędzie retrieve_headroom. Jeśli model potrzebuje pełnego kontekstu, wywołuje to narzędzie. Kompresja jest odwracalna, a nie oparta na stratach danych.
Rozbicie przy awarii
Headroom to element dodatkowy, a nie część krytycznej ścieżki w formacie inline. Jeśli jest niedostępny lub działa wolno, połączenia odbywają się bez kompresji. Zachowujesz oszczędności, gdy system jest sprawny, oraz ruch, gdy nie – to odpowiedni tryb awaryjny dla funkcji opartej na kosztach.
włączanie
Wymagane jest LiteLLM wersji v1.92.x lub nowszej (pierwsi użytkownicy używali v1.92.0-dev.1).
Rozwój tej funkcji odbywa się stopniowo: dodaj headroom-compression i wybierz tryb działania:
- Dla każdej prośby – włącz funkcję dla poszczególnych połączeń
- Dla każdego klucza wirtualnego – przypisz funkcję do konkretnego klucza; wszystkie połączenia z tym kluczem będą kompresowane
- Globally –
default_on: truedla całego ruchu przez proxy
Ponieważ mechanizm ochronny znajduje się na bramce i obsługuje oba formaty zapytań, ten sam tryb działania obejmuje klientów kompatybilnych z OpenAI, klientów Anthropic, lokalne agenty, usługi wyszukiwania oraz narzędzia do programowania w IDE.
Per-key to proste rozwiązanie dla administratorów: przymocuj zasady bezpieczeństwa do wirtualnego klucza, przekaż ten klucz i każdy dostawca/klient korzystający z niego będzie kompresował dane automatycznie.
Przykład kodu w Claude: ustaw ANTHROPIC_BASE_URL na proxy LiteLLM z kluczem kompresji — nie ma konieczności instalacji klienta ani modyfikacji kodu. Ta sama zasada obowiązuje dla klientów w stylu OpenAI za pomocą OPENAI_BASE_URL. Narzędzie w ogóle nie wie o istnieniu Headroom.
Potwierdź zastosowanie poprzez x-litellm-applied-guardrails lub panel Guardrails w dziennikach LiteLLM. Dokładne instrukcje znajdują się w przewodniku po zasadach bezpieczeństwa Headroom w LiteLLM (zobacz referencje) — postępuj zgodnie z nimi, aby uzyskać dokładną konfigurację w najnowszej wersji, a nie na podstawie przestarzałych przykładów.
Jeśli nie korzystasz z proxy LiteLLM
Zasady bezpieczeństwa bramy są najważniejsze, ale nie jedynym rozwiązaniem.
Wywoływanie litellm.completion() w Pythonie — użyj funkcji callback:
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=[...])
Lub konfiguracja:
# litellm_config.yaml
litellm_settings:
callbacks: ["headroom.integrations.litellm_callback.HeadroomCallback"]
W rzeczywistości wykorzystuje funkcję async_pre_call_hook z LiteLLM, tę samą funkcję zarządzania cyklem życia co mechanizm ochronny bramy. Tryb lokalny kompresuje dane wewnątrz procesu za pomocą funkcji compress() z Headroom; tryb chmurowy przekazuje dane do Headroom Cloud w celu zarządzanego pobierania informacji i uczenia się.
Własny proxy ASGI lub aplikacja internetowa — middleware:
from headroom.integrations.asgi import CompressionMiddleware
app.add_middleware(CompressionMiddleware)
# Intercepts /v1/messages, /v1/chat/completions, /v1/responses, /chat/completions
Odpowiedzi mogą zawierać atrybuty x-headroom-compressed: true oraz x-headroom-tokens-saved do pomiarów na poziomie każdej prośby.
Tylko agent kodujący, bez aplikacji Python — samodzielny proxy:
pip install "headroom-ai[all]"
headroom proxy --port 8787
# then, for Claude Code:
ANTHROPIC_BASE_URL=http://localhost:8787 claude
Zasada decyzyjna: proxy LiteLLM → mechanizm ochronny. LiteLLM w kodzie → funkcja powrotna. Własna aplikacja internetowa → middleware. Jeden agent kodujący → samodzielny proxy.
Czego można się spodziewać, szczerze mówiąc
Oszczędności zależą od treści
Dokumentacja teraz wskazuje na określony zakres: mniej więcej o 60–95% mniej tokenów w wynikach narzędzi opartych na JSON oraz w rezultatach wyszukiwania; bliżej 15–20% w przypadku już gęstego ruchu pochodzącego od agentów kodujących. Planuj z uwzględnieniem swojego obciążenia pracy, a nie maksymalnych wartości. Zostaw część danych nieskompresowaną jako grupę kontrolną, aby panele analityczne mogły pokazywać rzeczywiste oszczędności.
Kompresja powoduje niewielki opóźnienie
Headroom wskazuje na około 15 ms dla małych plików JSON oraz 100–200 ms dla dużych plików generowanych przez narzędzia. Redukcja liczby tokenów zazwyczaj powoduje dłuższy czas generowania niż koszty kompresji; małe obciążenia mogą nie przynieść korzyści. Dlatego ważne są kontrole na poziomie każdej prośby i każdego klucza.
Stary konflikt pozostaje
Agresywna kompresja koliduje z pełnym kontekstem. retrieve_headroom jest elementem regulującym, ale wymaga, aby model to zauważył i o to poprosił. W praktyce działa dobrze, choć nie stanowi gwarancji — zwracaj uwagę na jakość przy zadaniach wymagających szczegółowości.
To jest coś nowego
Integracja bramy dostępu została wdrożona w połowie 2026 roku na najnowszej linii LiteLLM (początkowo w wersji deweloperskiej). Najpierw testy, później pomiar efektów, a dopiero potem rozszerzenie – nie należy uruchamiać produkcji globalnej od pierwszego dnia.
Miejsce w całym systemie
Korzystne rozwiązania AI do produkcji są stopniowo wdrażane w różnych warstwach modelu, integrując się z już istniejącymi zespołami zajmującymi się infrastrukturą:
Clients / agents (Claude Code, RAG apps, custom agents)
|
LiteLLM gateway ── pre_call guardrail ──► Headroom compression (+ CCR retrieve)
|
LLM providers (OpenAI / Anthropic / Bedrock etc.)
Pomysł samodzielnej kompresji stał się teraz funkcją bramy dostępu. Jeśli LiteLLM jest już głównym wejściem, to zmiana konfiguracji polega na użyciu specjalnego klucza – nie jest to rearchitektura. Dlatego jest to interesujące nawet dla zespołów, które wcześniej pomijały oddzielny proxy do kompresji.
Wniosek
Dodanie tej funkcji do LiteLLM to niewielka zmiana o dużej sile oddziaływania. Po jej włączeniu każdy agent/klient wysyła lżejsze żądania do dostawców, a oryginały są dostępne w zaledwie jednym kroku.
Projekt pozostaje konserwatywny tam, gdzie to ważne: możliwość odwrócenia funkcji, tryb awaryjny oraz dostosowanie według żądania, klucza lub globalnie, dzięki czemu możesz zacząć od wąskiego zakresu działań.
Jeśli tokeny stanowią rzeczywisty element kosztów, a LiteLLM jest już w użyciu, koszt próbnego okresu jest niemal zerowy. Dołącz jeden klucz, zmierz ruch w czasie rzeczywistym i podejmij decyzję na podstawie tych danych.
Odnośniki
- Blog LiteLLM, LiteLLM × Headroom — https://docs.litellm.ai/blog/headroom-integration
- Dokumentacja integracji Headroom z LiteLLM — https://headroom-docs.vercel.app/docs/litellm
- Headroom na GitHubie — https://github.com/chopratejas/headroom
- Dokumentacja LiteLLM — https://docs.litellm.ai/
Plan wdrożenia
Pierwszy tydzień: zastosuj kompresję do pojedynczego klucza wirtualnego używanego przez agenta nieważnego. Porównaj liczbę tokenów i jakość odpowiedzi z niekompresowanym odpowiednikiem na tych samych promptach. Upewnij się, że pojawia się x-litellm-applied-guardrails oraz że wywołania retrieve odnoszą sukces przy zadawaniu pytań wymagających wielu szczegółów.
Drugi tydzień: rozszerz zastosowanie na klucz agenta do kodowania, jeśli zaoszczędzenia w ruchu generowanym przez duże pliki JSON wydają się istotne. Oczekuj mniejszych wzrostów procentowych w kontekstach kodu o dużej gęstości; oceniaj sukces pod kątem kosztów i opóźnień, a nie dążenia do celu marketingowego na poziomie 95%.
Trzeci tydzień: ustal globalne ustawienia domyślne tylko wtedy, gdy zachowanie „fail-open” utrzymało się podczas celowego testu awarii Headroom, a osoby odpowiedzialne za jakość zatwierdziły najbardziej wrażliwe procesy pracy.
Dlaczego to należy do inżynierii platformy
Zespoły tworzące aplikacje nie powinny samodzielnie wymyślać metod kompresji. Bramy już posiadają klucze, budżety oraz mechanizmy routingu. Dodanie kompresji w tych miejscach odpowiada sposobowi, w jaki rozwijały się ograniczenia szybkości i mechanizmy autoryzacji: gdy coś trafi na wspólną ścieżkę, każdy klient odziedzicza kontrolę bez konieczności ponownego wdrożenia.
Pamiętaj o tym modelu myślowym: klienci komunikują się z LiteLLM; LiteLLM komunikuje się z dostawcami; Headroom znajduje się obok mechanizmu pre-call hook. Nikt po żadnej ze stron nie potrzebuje nowego SDK. To niewidzialne umiejscowienie jest tym, co przekształca pomysł badawczy w zmianę platformy.
Karta decyzji
- Już używasz proxy LiteLLM → standardowe zabezpieczenia
litellm.completionw trakcie działania → funkcja callback- Szyty na miarę ASGI → middleware
- Jeden agent programistyczny → samodzielny proxy Headroom
Mierz wyniki, a następnie rozszerz rozwiązanie. Kompresja to narzędzie do kontrolowania kosztów, a nie religia.
Pozycje pokrewne
- Wire MCP Tools Through LiteLLM: Przewodnik po mock bank gateway — Zarejestruj mock bank działający przez streamable-HTTP, porównaj ręcznie napisane pętle narzędzi z jednym żądaniem do gateway i udowodnij, że zasady bezpieczeństwa pre_call nigdy nie dotrą do MCP.
- Twój pierwszy narzędzie wykorzystujące agenta AI z LangChain — Stwórz małego agenta matematycznego w LangChain w Pythonie: zainicjuj model do rozmów, zarejestruj narzędzia, pozwól LLM wybrać funkcję do wywołania i zobacz wieloetapowe użycie narzędzi.