LiteLLM: универсальный прокси-шлюз для управления 100+ LLM-провайдерами

LiteLLM — это self-hosted прокси-шлюз, который ставит один OpenAI-compatible API перед десятками LLM-провайдеров. Если несколько сервисов ходят в Anthropic, Groq, Perplexity и другие API напрямую, LiteLLM убирает привязку кода к конкретному поставщику и дает единую точку контроля над ключами, расходами и отказоустойчивостью. Ниже — практика: запуск LiteLLM Docker, конфигурация провайдеров в litellm_config.yaml, кэширование, fallback-цепочки и лимиты бюджета.

• как запустить LiteLLM через Docker и проверить endpoint;
• как подключить Groq и Perplexity через LiteLLM config;
• как включить локальный или Redis cache;
• как настроить fallback и повторные попытки;
• как ограничить бюджет пользователей и контролировать расходы;
• что проверять, если после установки запросы не проходят.

Проблема: зоопарк LLM-провайдеров и привязка кода

Микросервисы разрастаются. Каждый из них обращается к своей языковой модели: один через Anthropic API, второй через Groq, третий через Perplexity. Форматы запросов и ответов у всех разные.

При смене провайдера, например, из-за цены или качества инференса, приходится переписывать интеграционный слой в каждом сервисе. Это прямое следствие vendor lock-in — привязки кода к конкретному API, а не к задаче, которую он решает.

Что меняет единый шлюз

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

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

Что такое LiteLLM и как он унифицирует API

LiteLLM — это прокси-сервер с открытым исходным кодом. Он принимает входящие запросы в формате OpenAI API и перенаправляет их к выбранному LLM-провайдеру.

На выходе клиент получает ответ, структурированный так же, как от оригинального OpenAI — с полями choices, usage, model. Механика проста: вы пишете код один раз, под стандарт /v1/chat/completions, а замена модели или провайдера сводится к изменению параметра model в запросе или конфигурации шлюза.

Пример: Python-клиент под OpenAI без изменений идет в Groq

Python-клиент, написанный под OpenAI, без изменений отправляет запрос к Groq. Достаточно указать в вызове model: "groq/llama-3.1-70b-versatile" и направить запрос на endpoint LiteLLM. Шлюз сам преобразует формат, добавит нужные заголовки и вернет ответ в ожидаемой структуре.

Это снимает блокировку на уровне кодовой базы — миграция между провайдерами становится операционной задачей, а не инженерной.

Поддерживаемые провайдеры и модели

Провайдеров у LiteLLM больше сотни, и список продолжает расти: актуальный перечень ищите в репозитории проекта, он меняется от релиза к релизу. Среди поддерживаемых — OpenAI, Anthropic, Cohere, Groq, Perplexity, Together AI, Mistral, DeepSeek, AI21, Replicate, Hugging Face Inference Endpoints и десятки других.

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

Это особенно ценно при тестировании новых моделей: команда может сравнить качество ответов от разных поставщиков, не меняя ни строчки в приложениях. Подход снижает time-to-experiment с дней до минут.

Как запустить LiteLLM через Docker

Для запуска нужен Docker и файл конфигурации. Никаких внешних зависимостей на стороне приложения не требуется: образ содержит компоненты, необходимые для запуска прокси. Разберем по шагам.

Шаг 1. Создайте директорию проекта и файл litellm_config.yaml:

mkdir litellm-proxy && cd litellm-proxy
touch litellm_config.yaml

Шаг 2. Опишите провайдеров в конфигурации — рабочий пример с двумя провайдерами ниже.

Шаг 3. Запустите контейнер, передав ему ключи из .env:

docker run -d \
  --name litellm \
  -p 4000:4000 \
  --env-file .env \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-latest

Конфиг ссылается на переменные окружения вида os.environ/GROQ_API_KEY, поэтому ключи нужно передать внутрь контейнера — через -e или --env-file. Если этого не сделать, LiteLLM подставит пустое значение, и запросы к провайдеру упадут с ошибкой авторизации.

Шаг 4. Проверьте работоспособность через curl:

curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-litellm-master-key" \
  -d '{
    "model": "perplexity/llama-3.1-sonar-large-128k-online",
    "messages": [{"role": "user", "content": "Привет, как дела?"}]
  }'

Ответ придет в формате OpenAI API. Модель можно заменить на любую из конфигурации — достаточно изменить поле model в теле запроса.

Пример LiteLLM config для Perplexity и Groq

Рабочий YAML с двумя провайдерами. Параметры: model_name — псевдоним для клиентов, litellm_params.model — идентификатор модели у провайдера, api_key — ключ доступа.

model_list:
  - model_name: perplexity-sonar
    litellm_params:
      model: perplexity/llama-3.1-sonar-large-128k-online
      api_key: os.environ/PERPLEXITY_API_KEY
  - model_name: groq-llama
    litellm_params:
      model: groq/llama-3.1-70b-versatile
      api_key: os.environ/GROQ_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Псевдонимы perplexity-sonar и groq-llama скрывают детали провайдера от клиентов. При миграции, например, с Groq на другого поставщика, достаточно изменить litellm_params.model под тем же псевдонимом — клиенты не заметят подмены. API-ключи вынесены в переменные окружения, что соответствует базовым практикам безопасности.

После правки YAML перезапустите контейнер: конфигурация читается при старте, на лету изменения не подхватываются.

Ускорение и экономия: кэширование и LiteLLM Redis cache

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

Механика: шлюз вычисляет хеш от комбинации model + messages + temperature + max_tokens. При совпадении хеша с уже сохраненным ответ возвращается из кэша, минуя обращение к провайдеру. Кэш точный: если промпт изменился хотя бы на символ, это уже другой ключ. Фактический выигрыш по времени и стоимости зависит от типа кэша, параметров запроса и конкретного провайдера, поэтому его стоит измерять на собственном трафике.

Включение кэширования в конфигурации:

litellm_settings:
  cache: true
  cache_params:
    type: local
    ttl: 3600

Параметр ttl задает время жизни записи в секундах. Для production-сред с несколькими репликами шлюза локальный кэш не подходит — каждый экземпляр хранит свою копию. Решение — Redis.

Локальное кэширование vs LiteLLM Redis cache

Локальный кэш хранится в памяти процесса. Плюсы: нулевая задержка, отсутствие внешних зависимостей. Минусы: не работает при горизонтальном масштабировании (две реплики шлюза не видят кэш друг друга) и теряется при перезапуске контейнера.

Redis-кэш обеспечивает общее хранилище для всех экземпляров LiteLLM. Конфигурация:

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: os.environ/REDIS_HOST
    port: os.environ/REDIS_PORT
    ttl: 3600

Выбор между подходами определяется масштабом системы. Для одного сервера и разработки достаточно локального кэша. Для кластера из нескольких реплик нужен Redis. Инвалидация кэша автоматическая по TTL, ручная очистка доступна через API шлюза.

Отказоустойчивость: LiteLLM fallback-цепочки и балансировка

Провайдеры LLM периодически деградируют. API возвращает 5xx, модель зависает на инференсе, квота исчерпана. Без fallback-стратегии это означает отказ сервиса для конечного пользователя. LiteLLM предоставляет декларативный механизм цепочек отказоустойчивости.

Какие ошибки обычно триггерят переключение

Смысл fallback — уйти на резервную модель, когда проблема на стороне провайдера. Как правило, цепочку активируют:

• ответы 5xx — сбой или перегрузка у провайдера;
• таймауты и обрывы соединения — модель не успела ответить за отведенное время;
• 429 rate limit — исчерпана квота или превышен лимит запросов;
• ошибки доступа к модели у провайдера — отозванный ключ, снятая с обслуживания модель.

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

Пример конфигурации с fallback-цепочкой: основная модель — Groq, резервная — Perplexity.

model_list:
  - model_name: my-llm
    litellm_params:
      model: groq/llama-3.1-70b-versatile
      api_key: os.environ/GROQ_API_KEY
    model_info:
      mode: chat
  - model_name: my-llm-fallback
    litellm_params:
      model: perplexity/llama-3.1-sonar-large-128k-online
      api_key: os.environ/PERPLEXITY_API_KEY

router_settings:
  routing_strategy: usage-based
  allowed_fails: 3
  num_retries: 2
  fallbacks:
    - my-llm: [my-llm-fallback]

После заданного числа ошибок от Groq шлюз может переключиться на Perplexity. Точное поведение зависит от типа ошибки, параметров маршрутизатора и доступности резервной модели, поэтому fallback стоит проверять на сценариях, которые важны для вашего сервиса. Параметр num_retries задает количество повторных попыток перед активацией fallback-модели.

Проверять это лучше по логам: docker logs litellm показывает, к какому провайдеру ушел запрос, сколько было повторов и сработало ли переключение. Правки в YAML начинают действовать после перезапуска контейнера.

Балансировка нагрузки между провайдерами настраивается через routing_strategy. Стратегия usage-based распределяет запросы по наименее загруженному провайдеру из группы. Это полезно при работе с несколькими поставщиками одной модели — снижается зависимость от квот конкретного провайдера.

Мониторинг расходов и управление пользователями

LiteLLM включает веб-интерфейс для административного контроля. Он доступен по адресу http://localhost:4000/ui после запуска контейнера. Дашборд показывает расходы с разбивкой по моделям и пользователям, количество запросов за период и среднюю задержку ответа.

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

Как настроить budget limits

Лимиты задаются на двух уровнях. Общий бюджет всего прокси прописывается в конфигурационном файле:

litellm_settings:
  max_budget: 50
  budget_duration: 1mo

Персональные лимиты выдаются не в YAML, а на уровне виртуальных ключей: в административном UI ключу задаются max_budget, budget_duration и список доступных моделей. Создавать ключи можно и через управляющий API шлюза, но в UI нагляднее: рядом сразу видны потраченная сумма и остаток по каждому ключу.

Параметр budget_duration принимает значения вида 1d, 1mo. При достижении лимита запросы блокируются до окончания периода. Оповещения о приближении к лимиту настраиваются через webhook — шлюз отправляет POST-запрос на указанный URL при расходе 80% и 100% бюджета.

Проверить, что лимит действительно работает: создайте ключ с заведомо маленьким бюджетом, отправьте несколько запросов и убедитесь, что после исчерпания шлюз отвечает ошибкой 429, а расход по ключу в UI совпадает с вашими ожиданиями.

LiteLLM: частые сценарии, проверки после установки и диагностика

Как подключить нового провайдера?

Добавьте модель в model_list, укажите идентификатор модели в litellm_params.model, а API-ключ вынесите в переменную окружения. Затем отправьте тестовый запрос с соответствующим значением model. Если запрос не проходит, проверьте имя модели у провайдера и наличие ключа внутри контейнера.

Как включить Redis cache?

Укажите type: redis, адрес в host и порт в port. LiteLLM и Redis должны быть доступны друг другу по сети Docker. После запуска проверьте логи контейнера и повторите одинаковый запрос. Косвенный признак работающего кэша — рост числа ключей в Redis после серии идентичных запросов (redis-cli dbsize). Если Redis недоступен, запросы не должны молча считаться успешно закэшированными.

Почему не работает fallback?

Проверьте совпадение имен в fallbacks и model_list, значения allowed_fails и num_retries, а также наличие API-ключа резервного провайдера. Отдельно учитывайте, что не каждая ошибка должна приводить к переключению модели — ошибки некорректного запроса резервная модель не исправит.

Почему контейнер запущен, но API не отвечает?

Проверьте проброс порта, путь монтирования /app/config.yaml, содержимое конфигурации и логи через Docker. Затем повторите запрос к http://localhost:4000/v1/chat/completions с корректными заголовками Content-Type и Authorization.

Как проверить переменные окружения, логи и Redis внутри Docker

Три команды, которые закрывают большинство вопросов после установки:

docker logs --tail 100 litellm
docker exec litellm env | grep -E "GROQ_API_KEY|PERPLEXITY_API_KEY|LITELLM_MASTER_KEY|REDIS"
docker exec -it redis redis-cli ping

docker logs покажет, стартовал ли прокси и какие ошибки он вернул на входящие запросы. docker exec ... env подтвердит, что ключи действительно попали внутрь контейнера, а не остались в вашей shell-сессии, — вывод содержит секреты, не пересылайте его в чаты и тикеты. Ответ PONG от redis-cli ping означает, что хранилище кэша доступно; если Redis запущен не в контейнере с именем redis, подставьте свой хост и порт.

LiteLLM в архитектуре микросервисов

Типовая production-схема: три микросервиса (чат-бот, аналитический пайплайн, генератор отчетов) обращаются к единому экземпляру LiteLLM. Шлюз маршрутизирует запросы к разным провайдерам в зависимости от модели, указанной в запросе. Все API-ключи провайдеров хранятся только в конфигурации шлюза — микросервисы не имеют к ним доступа.

Это решает проблему безопасности: ключи не размазываются по кодовой базе и не попадают в логи разработчиков. При компрометации ключа его замена происходит в одной точке — конфигурационном файле шлюза.

Масштабирование достигается запуском нескольких реплик LiteLLM за балансировщиком. Общий Redis-кэш и единая конфигурация обеспечивают согласованное поведение. Мониторинг всех реплик централизован через административный дашборд. Для Kubernetes-окружений сообщество предоставляет готовые Helm-чарты.

При проектировании AI-агентов на базе LLM шлюз становится критическим элементом архитектуры. Он обеспечивает единую точку контроля над расходами и отказоустойчивостью для всех агентов в системе. Подробнее об архитектуре агентов и интеграции LiteLLM — в материале о создании AI-агента с нуля, где разобраны метрики latency, cost и reliability.

Сравнение с коммерческими ИИ-роутерами и издержки самостоятельного хостинга

Рынок предлагает коммерческие аналоги: OpenRouter, Martian, Portkey. Они решают ту же задачу унификации API, но с другой экономикой и уровнем контроля.

Portkey в таблицу не попал: по модели поставки он не укладывается в простое деление «self-hosted vs managed». У проекта есть open-source gateway, который можно развернуть в своем контуре, поэтому по контролю над данными он ближе к LiteLLM, а по части enterprise-обвязки — к managed-роутерам. Если выбираете между LiteLLM и Portkey, сравнивайте не только цену токенов, но и то, какой объем конфигурации вам придется поддерживать самостоятельно.

Операционные издержки самостоятельного хостинга — главный скрытый фактор. Поддержка в production требует мониторинга доступности шлюза, обновления образа при выходе новых версий, настройки резервного копирования конфигурации и реагирования на инциденты. Для команды без DevOps это риск деградации сервиса при отсутствии мониторинга.

Когда стоит выбрать LiteLLM, а когда — коммерческий роутер

LiteLLM — ваш выбор, если:

• Данные не должны покидать ваш контур (fintech, healthcare, enterprise).
• Нужна глубокая кастомизация маршрутизации и fallback-логики.
• Есть DevOps-ресурс для поддержки инфраструктуры.
• Бюджет на инструментарий ограничен, а стоимость токенов уже высока.

Коммерческий роутер — ваш выбор, если:

• Нет возможности выделить инженера на поддержку шлюза.
• Важнее скорость внедрения, чем экономия на наценке.
• Нужен доступ к провайдерам, отсутствующим в LiteLLM.

Для enterprise-внедрений, где критичен контроль над данными и расходами, LiteLLM часто используют как компонент более широкой стратегии LLM gateway. Детальный разбор архитектуры с guardrails и compliance — в статье об управляемых AI-агентах в enterprise.

Заключение: кому и зачем нужен LiteLLM

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

Инструмент снижает порог входа в мультипровайдерную стратегию. Команда может тестировать новые модели без изменения кода, переключаться между поставщиками при изменении цен и контролировать бюджет через лимиты на пользователей. Для тех, кто уже работает с LLM в production, LiteLLM — способ вернуть контроль над зависимостью от API-провайдеров.

Если вы рассматриваете оптимизацию расходов на LLM, обратите внимание на кейс миграции с Claude Sonnet на Qwen 3.5 Flash — там разобрана методология выбора модели и скрытые проблемы дешевых LLM.

Подписаться на канал