# LiteLLM Proxy: как установить, настроить и сделать первый запрос
Каноническая страница: https://plainews.ru/posts/litellm-proxy-guide
Опубликовано: 2026-10-31T06:42:53.601Z

Как установить и запустить LiteLLM Proxy: конфиг, Docker-команды, первый запрос через curl и Python, типичные ошибки и ответы на частые вопросы.
# 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-ключ для авторизации запросов к прокси.

> **Важно.** Значения вида `os.environ/ИМЯ_ПЕРЕМЕННОЙ` означают, что LiteLLM читает ключ из переменной окружения. Не вставляйте реальные ключи прямо в YAML-файл — передавайте их через `-e` при запуске контейнера.

Если провайдер изменил базовый 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/