LiteLLM Proxy: как установить, настроить и сделать первый запрос

LiteLLM Proxy — это AI-шлюз (gateway), который принимает запросы в формате OpenAI API и перенаправляет их к 100+ LLM-провайдерам: OpenAI, Anthropic, Groq, Perplexity, Bedrock, Azure и другим. Вы пишете код один раз, а модель меняете в конфиге без правки приложения.

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

Как работает LiteLLM Proxy

Прокси принимает запрос в формате POST /v1/chat/completions, определяет нужного провайдера по имени модели из конфига и транслирует запрос в нативный формат этого провайдера. Ответ возвращается обратно в формате OpenAI — независимо от того, какой провайдер ответил.

Это значит: если сегодня вы используете gpt-4o, а завтра решили перейти на llama-3.1-8b через Groq — в коде приложения ничего не меняется. Достаточно обновить конфиг прокси.

Установка через Docker

Проще и быстрее всего развернуть LiteLLM Proxy в Docker-контейнере: это изолирует окружение и избавляет от ручной настройки Python-зависимостей.

Шаг 1. Скачайте образ

bash
docker pull docker.litellm.ai/berriai/litellm:latest

Шаг 2. Создайте файл конфигурации

Создайте файл config.yaml в текущей директории. В нём перечисляются все модели, которые будут доступны через прокси.

Пример конфига с двумя провайдерами — Perplexity и Groq:

plain
model_list:
  # --- Perplexity (Sonar) ---
  - model_name: sonar
    litellm_params:
      model: perplexity/sonar
      api_key: os.environ/PERPLEXITYAI_API_KEY

  - model_name: sonar-pro
    litellm_params:
      model: perplexity/sonar-pro
      api_key: os.environ/PERPLEXITYAI_API_KEY

  # --- Groq ---
  - model_name: gpt-oss
    litellm_params:
      model: groq/openai/gpt-oss-120b
      api_key: os.environ/GROQ_API_KEY

  - model_name: groq-llama-3.1-8b
    litellm_params:
      model: groq/llama-3.1-8b-instant
      api_key: os.environ/GROQ_API_KEY

litellm_settings:
  drop_params: true
  set_verbose: false
  request_timeout: 300

router_settings:
  timeout: 300
  fallbacks:
    - sonar: ['gpt-oss']
    - gpt-oss: ['sonar']

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Что означают секции конфига:

  • model_list — перечень всех моделей, доступных через прокси. Каждая запись содержит псевдоним (model_name) и параметры провайдера (litellm_params).
  • litellm_settings — параметры, применяемые ко всем запросам: drop_params убирает неподдерживаемые параметры, request_timeout задаёт таймаут в секундах.
  • router_settings — настройки роутера: таймауты и цепочки fallback. В примере выше, если sonar недоступен, запрос автоматически уйдёт к gpt-oss, и наоборот.
  • general_settings — настройки самого инстанса LiteLLM. Здесь задаётся master_key — главный API-ключ для авторизации запросов к прокси.

Если провайдер изменил базовый URL или вы хотите переопределить его вручную, добавьте параметр api_base на том же уровне, что и api_key в блоке litellm_params.

Шаг 3. Запустите контейнер

bash
docker run -d \
  --name litellm \
  -p 4000:4000 \
  -v "$(pwd)/config.yaml:/app/config.yaml:ro" \
  -e PERPLEXITYAI_API_KEY=ваш_ключ_perplexity \
  -e GROQ_API_KEY=ваш_ключ_groq \
  -e LITELLM_MASTER_KEY=sk-litellm-local \
  docker.litellm.ai/berriai/litellm:latest \
  --config /app/config.yaml \
  --port 4000

Замените ваш_ключ_perplexity и ваш_ключ_groq на реальные API-ключи от соответствующих провайдеров. Значение LITELLM_MASTER_KEY — это ключ, который вы будете передавать в заголовке Authorization при запросах к прокси; задайте любую строку в формате sk-....

После запуска прокси слушает на порту 4000.

Первый запрос через curl

Проверьте, что прокси работает, отправив тестовый запрос:

bash
curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-litellm-local" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

Успешный ответ — JSON с полями id, model, choices (текст ответа модели) и usage (количество использованных токенов). Структура ответа идентична OpenAI API вне зависимости от того, какой провайдер обработал запрос.

Первый запрос через Python

Установите библиотеку LiteLLM:

bash
pip install litellm

Минимальный рабочий скрипт:

python
from litellm import completion

response = completion(
    model="perplexity/sonar",
    messages=[
        {"role": "user", "content": "Привет!"}
    ],
    api_base="http://localhost:4000",
    api_key="sk-litellm-local",
)

print(response.choices[0].message.content)

Здесь api_base указывает на локальный прокси, а api_key — это LITELLM_MASTER_KEY, заданный при запуске контейнера. Код работает с любой моделью из model_list — достаточно изменить значение параметра model.

Типичные ошибки и как их исправить

Ошибка 401 Unauthorized — неверный или отсутствующий заголовок Authorization. Убедитесь, что передаёте Bearer и точное значение LITELLM_MASTER_KEY, которое задали при запуске контейнера.

Ошибка 404 / модель не найдена — имя модели в запросе не совпадает ни с одним model_name в config.yaml. Проверьте написание: значение в запросе должно точно совпадать со значением model_name в конфиге.

Контейнер запустился, но запросы не проходят — проверьте, что порт 4000 не занят другим процессом. Посмотрите логи контейнера командой:

bash
docker logs litellm

Ключ провайдера не подхватывается — убедитесь, что переменная окружения передана через флаг -e при docker run и что имя переменной в конфиге (os.environ/ИМЯ) точно совпадает с именем, переданным в -e.

Fallback не срабатывает — проверьте, что имена моделей в секции fallbacks в router_settings совпадают с model_name из model_list. Опечатка в имени — и роутер не найдёт запасную модель.

FAQ

Можно ли использовать LiteLLM Proxy без Docker?

Да. Установите пакет через pip install litellm[proxy] и запустите командой litellm --config config.yaml --port 4000. Docker-способ предпочтительнее для продакшена, так как изолирует зависимости.

Как добавить новую модель без перезапуска контейнера?

Добавьте новую запись в model_list в config.yaml. Если конфиг смонтирован через -v как в примере выше, перезапустите контейнер командой docker restart litellm, чтобы изменения применились.

Как ограничить расходы по пользователям?

LiteLLM Proxy поддерживает бюджетные лимиты через general_settings и управление пользователями через API прокси. Создайте отдельные API-ключи для каждого пользователя или команды и задайте им лимиты через эндпоинт /key/generate.

Работает ли прокси с локальными моделями через Ollama?

Да. Добавьте в model_list запись с model: ollama/llama3 и укажите api_base: http://localhost:11434. LiteLLM Proxy умеет работать с локальными моделями так же, как с облачными провайдерами.

Что такое drop_params: true в конфиге?

Эта настройка в litellm_settings заставляет прокси автоматически удалять параметры запроса, которые конкретный провайдер не поддерживает. Без неё запрос к модели, не понимающей, например, параметр logprobs, завершится ошибкой.

Источники

  • https://github.com/BerriAI/litellm
  • https://habr.com/ru/companies/selectel/articles/1064050/