Сжимайте каждый вызов LLM в шлюзе LiteLLM с функцией Headroom

Команды, которые уже используют модели с LiteLLM, могут уменьшать объем входящих токенов от всех поставщиков услуг, не затрагивая при этом код агентов и приложений. Headroom использует прокси в качестве защитного механизма перед вызовом, сокращает результаты работы инструментов и фрагменты данных RAG ещё до обращения к поставщику, но при необходимости позволяет модели получать полные оригинальные данные через соответствующий инструмент получения информации.

Headroom, о котором говорилось ранее в этой серии, сокращает результаты работы инструментов, блоки логов и фрагменты данных, предназначенные для получения информации, ещё до того, как их увидит модель. Сама компрессия никогда не была сложной частью — проблемой всегда было включение её в путь запроса.

С июня 2026 года эта проблема исчезает для пользователей LiteLLM: Headroom интегрируется в качестве встроенного защитного механизма шлюза. Одним переключателем можно компрессировать все вызовы, проходящие через него.

Такое сочетание устраняет последнее оправдание для отказа от использования таких решений. Экономия всегда была реальной; сложность заключалась в настройке процесса. У шлюза достаточно просто переключить один режим, и агенты с клиентами остаются незатронутыми.

Почему именно шлюз

Большинство команд, работающих с несколькими моделями в промышленных условиях, уже используют шлюз для обработки запросов.

LiteLLM является популярным выбором: это единый входной интерфейс, совместимый с OpenAI, для более чем ста поставщиков услуг, при этом маршрутизация, ключи, бюджеты и логирование централизованы.

Именно поэтому шлюз становится естественным местом для реализации функций сжатия. Каждый запрос уже проходит через него, поэтому один компрессор может обрабатывать запросы всех агентов, клиентов и поставщиков.

Необходимо настроить всё лишь один раз, вместо того чтобы добавлять инструменты обработки в каждое приложение. Поскольку LiteLLM поддерживает как интерфейс OpenAI /v1/chat/completions, так и интерфейс Anthropic /v1/messages, компрессор шлюза может одновременно обрабатывать запросы приложений, использующих формат OpenAI, инструментов Anthropic вроде Claude Code, сервисов по извлечению информации и специальных агентов.

Компрессия перестаёт быть дополнительным инструментом и становится частью платформы — это обычный путь развития инфраструктуры: вниз по иерархии к общему слою, который уже используется всеми.

Как работает механизм защиты

Headroom встраивается как механизм защиты перед отправкой запроса: он работает в рамках жизненного цикла LiteLLM непосредственно перед тем, как данные отправляются дальше.

Режим 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.)

Клиенты по-прежнему обращаются к LiteLLM в обычном режиме. Перед отправкой запроса LiteLLM вызывает Headroom, заменяет сообщения на компрессированные и пересылает их дальше. Клиенты и поставщики услуг никогда не общаются напрямую с Headroom — именно в этом заключается принцип его невидимости.

Важны два принципа безопасности.

Ничего не теряется навсегда

Это тот же принцип компрессии, кэширования и восстановления данных, что описывался ранее для Headroom. Оригинальные данные остаются в кэше; LiteLLM предоставляет инструмент retrieve_headroom. Если модели нужен полный контекст, она вызывает этот инструмент. Компрессия является обратимой, а не основанной на потерях данных.

Режим отказа «открыто»

Headroom является дополнительным компонентом, а не частью критического пути обработки. Если он недоступен или работает медленно, вызовы продолжаются без сжатия. Вы сохраняете экономию ресурсов в случае нормальной работы и объем трафика при сбоях — это оптимальный режим отказа для функции, основанной на снижении затрат.

Включение функции

Требуется версия LiteLLM v1.92.x или новее (первые пользователи использовали v1.92.0-dev.1).

Настройка происходит просто: добавьте параметр headroom-compression и выберите режим действия:

• По запросу — включение для отдельных вызовов
• По виртуальному ключу — применение к конкретному ключу; все вызовы с этим ключом сжимаются
• Глобально — параметр default_on: true для всего трафика прокси

Поскольку механизм защиты расположен на уровне шлюза и обрабатывает оба формата запросов, одна и та же настройка подходит для клиентов, совместимых с OpenAI, клиентов Anthropic, разработанных внутри организации агентов, сервисов по извлечению данных и инструментов кодирования в IDE.

Per-key — это удобный способ для администраторов: привязывается «защитный барьер» к виртуальному ключу, ключ передаётся пользователю, и каждый поставщик/клиент, использующий его, автоматически выполняет сжатие.

Пример кода на Claude: установите значение ANTHROPIC_BASE_URL как адрес прокси LiteLLM с ключом сжатия — нет необходимости устанавливать клиент, нет различий в коде. То же самое применимо к клиентам в стиле OpenAI с помощью OPENAI_BASE_URL. Сам инструмент даже не знает о существовании Headroom.

Подтвердите настройку с помощью параметра x-litellm-applied-guardrails или панели Guardrails в журнале записей LiteLLM. Подробная инструкция по настройке содержится в руководстве LiteLLM по защитным барьерам Headroom (см. ссылки) — следуйте ей для получения точной конфигурации в новых версиях, а не для использования устаревших примеров.

Если вы не используете прокси LiteLLM

Защитный барьер на уровне шлюза — это основной вариант, но не единственный.

Вызов функции litellm.completion() на Python — используйте функцию обратного вызова:

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=[...])

Или конфигурация:

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

По сути используется функция async_pre_call_hook от LiteLLM, которая работает в том же цикле жизни, что и механизм защиты гейтвэя. В локальном режиме сжатие происходит внутри приложения с помощью функции compress() от Headroom; в облачном режиме данные передаются в Headroom Cloud для управляемого извлечения информации и обучения.

Собственный ASGI-прокси или веб-приложение — промежуточный слой:

from headroom.integrations.asgi import CompressionMiddleware

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

Ответы могут содержать поля x-headroom-compressed: true и x-headroom-tokens-saved для измерения показателей по каждому запросу.

Только агент для кодирования, без Python-приложения — автономный прокси:

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

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

Правило выбора: прокси от LiteLLM → механизм защиты; LiteLLM в коде → функция обратного вызова; собственное веб-приложение → промежуточный слой; единственный агент для кодирования → автономный прокси.

Чего ожидать, честно говоря

Экономия зависит от содержимого

В документации теперь указан диапазон: примерно на 60–95% меньше токенов в выводах инструментов с большим количеством JSON и результатах поиска; примерно на 15–20% — в трафике, связанном с уже плотными кодами от агентов. Ориентируйтесь на объем своей рабочей нагрузки, а не на максимально возможное сокращение. Оставьте часть данных без сжатия в качестве контрольной группы, чтобы панели управления могли отображать фактическую экономию.

Сжатие увеличивает небольшую задержку

Согласно данным Headroom, для небольших JSON-данных задержка составляет примерно 15 мс, а для крупных блоков данных от инструментов — 100–200 мс. Сокращение количества токенов обычно приводит к увеличению времени генерации больше, чем стоимость сжатия; для очень маленьких объемов данных это может не окупаться. Именно поэтому важны настройки для каждого запроса и каждого ключа.

Старая проблема остается

Агрессивное сжатие мешает полному учету контекста. Функция retrieve_headroom служит регулятором, но для ее работы модель должна это заметить и запросить соответствующие данные. На практике она хорошо работает, но не является гарантией — обращайте внимание на качество выполнения задач, требующих точности.

Это нововведение

Интеграция шлюза была внедрена в середине 2026 года в очень новой версии LiteLLM (изначально — разработочная версия). Сначала проводится пилотный проект, затем оценка результатов, и только после этого — масштабирование; не следует сразу переводить всю производственную систему на новую версию.

Место в стеке

Полезные инструменты для работы с ИИ в производственных условиях продолжают появляться в различных слоях модели, объединяясь с уже существующими командами по управлению инфраструктурой:

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

Идея автономного сжатия теперь является функцией шлюза. Если LiteLLM уже служит входной точкой, это просто изменение настроек через специальный ключ — без необходимости перепроектирования архитектуры. Именно поэтому она интересна даже для тех команд, которые ранее обходились без отдельного прокси для сжатия.

Вывод

Дополнительные возможности LiteLLM позволяют внести небольшие изменения с значительным эффектом. Активируя их на уровне шлюза, каждый агент/клиент будет отправлять более компактные запросы к поставщикам услуг, при этом оригинальные данные всегда будут доступны по одному вызову.

Дизайн остается консервативным там, где это важно: возможность обратного включения, режим аварийного включения и переключение по запросу, ключу или глобально, что позволяет начать с ограниченного использования.

Если токены являются отдельной статьей расходов, а LiteLLM уже используется, стоимость пробного периода практически равна нулю. Прикрепите один ключ, измерьте реальный трафик и примите решение на основе полученных данных.

Ссылки

1. Блог LiteLLM, LiteLLM × Headroom — https://docs.litellm.ai/blog/headroom-integration
2. Документация по интеграции Headroom с LiteLLM — https://headroom-docs.vercel.app/docs/litellm
3. Headroom на GitHub — https://github.com/chopratejas/headroom
4. Документация LiteLLM — https://docs.litellm.ai/

План внедрения

Первая неделя: применить сжатие к одной виртуальной клавише, используемой агентом низкой критичности. Сравнить количество токенов и качество ответов с несжатой версией при одинаковых запросах. Убедиться, что параметр x-litellm-applied-guardrails присутствует и что запросы на получение информации успешны при задании вопросов с большим количеством деталей.

Вторая неделя: расширить применение сжатия на клавишу кодинг-агента, если будет зафиксировано значимое сокращение объема трафика с большим количеством данных в формате JSON. Ожидать более незначительного увеличения эффективности в контекстах сложных кодов; оценивать успех по финансовым показателям и задержкам, а не по стремлению к целевому показателю в 95%.

Третья неделя: установить глобальные параметры по умолчанию только в том случае, если поведение системы при сбоях останется стабильным в ходе специальных тестов на отказоустойчивость, и если ответственные за качество одобрят использование этих параметров для наиболее чувствительных рабочих процессов.

Почему это относится к инженерии платформ

Командам, разрабатывающим приложения, не следует самостоятельно создавать механизмы сжатия. У шлюзов уже есть ключи, бюджеты и функции маршрутизации. Внедрение сжатия там соответствует тому же подходу, который был использован при развитии механизмов ограничения скорости и аутентификации: как только что-то попадает в общую инфраструктуру, каждый клиент автоматически получает возможность использовать это без необходимости повторной настройки.

Следует помнить следующее: клиенты взаимодействуют с LiteLLM; LiteLLM — с поставщиками услуг; Headroom находится рядом с механизмом предварительной подготовки к вызову. Никому из участников не требуется новый SDK. Именно такое незаметное размещение элементов позволяет превратить исследовательскую идею в реальную платформу.

Карта принятия решений

• Уже используется прокси LiteLLM → встроенные механизмы контроля
• Используется litellm.completion → обратный вызов
• Собственный ASGI → промежуточные компоненты
• Один агент для кодирования → автономный прокси Headroom

Сначала измерьте эффективность, затем расширяйте использование. Сжатие — это инструмент для снижения затрат, а не религия.