LiteLLM Proxy: один API для 100+ LLM (налаштування за 15 хв у Docker)

LiteLLM Proxy: один API для 100+ LLM (налаштування за 15 хв у Docker)

Ваша команда ділиться ключами API OpenAI в особистих повідомленнях Slack. Ніхто не знає, хто витратив $400 минулого вівторка. Немає обмеження швидкості запитів, немає резервного варіанта, якщо постачальник лягає, а перехід з GPT-4o на Claude означає зміну коду в дванадцяти місцях. Знайомо? Локальний LLM-шлюз виправляє все це, а проксі-сервер LiteLLM є найпопулярнішим опенсорсним рішенням — це єдина точка доступу, сумісна з OpenAI, яка маршрутизує запити до понад 100 постачальників LLM.

Цей посібник охоплює повне налаштування litellm proxy: Docker Compose з PostgreSQL, віртуальні ключі команд з бюджетами, відстеження витрат, обмеження швидкості та підключення AI-IDE, таких як Claude Code і Cursor. Якщо ви оцінюєте інструменти LLM-шлюзів, це практичний туторіал, який допоможе перейти від нуля до продакшену.

Важливе зауваження перед початком: SDK LiteLLM (бібліотека Python) та проксі-сервер — це різні речі. SDK призначений для окремого розробника, який викликає кілька LLM API з Python. Проксі призначений для команд; він працює як сервер між вашими додатками та постачальниками LLM. Якщо ви соло-розробник і пишете скрипт, вам достатньо SDK. Якщо ж ви керуєте ключами, бюджетами та доступом для команди, вам потрібен проксі. Саме його ми тут і налаштовуємо.

LiteLLM Proxy коротко

Ось порівняння методів розгортання:

Для більшості команд оптимальним варіантом є Docker Compose з PostgreSQL. До цього ми й прийдемо, але спочатку запустимо проксі за 60 секунд.

Передумови та налаштування середовища

Перед початком переконайтеся, що у вас є:

• Встановлені Docker та Docker Compose (Docker Desktop містить обидва)
• Принаймні один ключ API LLM (OpenAI, Anthropic або локальний екземпляр Ollama)
• Базові навички роботи з терміналом / CLI

Переконайтеся, що Docker готовий до роботи, та експортуйте свої ключі API:

# Check Docker is installed
docker --version
docker compose version

# Export your LLM API keys (add to your shell profile for persistence)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: set a master key for your proxy (you'll need this later)
export LITELLM_MASTER_KEY="sk-master-your-secret-key"

Це все. Жодних спеціальних версій Python, жодних інструментів, прив'язаних до ОС. Якщо Docker працює на вашій машині, ви готові.

Швидкий старт: ваш перший LiteLLM Proxy за 60 секунд

Одна команда для запуску проксі з GPT-4o:

docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e LITELLM_MASTER_KEY=$LITELLM_MASTER_KEY \
  ghcr.io/berriai/litellm:main-stable \
  --model openai/gpt-4o

Перевірте за допомогою curl:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Say hello from LiteLLM"}]
  }'

Або перевірте з Python:

from openai import OpenAI

# Point the standard OpenAI SDK at your proxy
client = OpenAI(
    api_key="sk-master-your-secret-key",
    base_url="http://localhost:4000/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Say hello from LiteLLM"}]
)
print(response.choices[0].message.content)

Що тільки що сталося? Ваш код звертається до localhost:4000, використовуючи стандартний формат SDK OpenAI. Проксі отримує запит, пересилає його до API OpenAI з реальним ключем і повертає відповідь. Код вашого додатка ніколи не торкається фактичного ключа API.

Це і є основна ідея. Тепер побудуємо продакшен-налаштування.

Продакшен-налаштування Docker Compose з PostgreSQL

Команда docker run працює для тестування, але продакшен-командам потрібне постійне відстеження витрат, віртуальні ключі та належне зберігання в базі даних. Це означає використання Docker Compose з PostgreSQL.

Файл Docker Compose

# docker-compose.yml
version: "3.9"

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm-proxy
    ports:
      - "4000:4000"         # Proxy API port
    volumes:
      - ./config.yaml:/app/config.yaml   # Mount your config file
    environment:
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://litellm:litellm_password@postgres:5432/litellm
      - LITELLM_SALT_KEY=${LITELLM_SALT_KEY:-sk-salt-random-string}
    command: --config /app/config.yaml --detailed_debug
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: litellm-db
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm_password
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  litellm_pgdata:

Змінна LITELLM_SALT_KEY шифрує дані віртуальних ключів у базі даних. Документація найкращих практик LiteLLM для продакшену рекомендує встановлювати її для будь-якого командного розгортання.

Запуск стеку

# Create a .env file with your keys (don't commit this to git)
echo "LITELLM_MASTER_KEY=sk-master-your-secret" > .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
echo "LITELLM_SALT_KEY=sk-salt-$(openssl rand -hex 16)" >> .env

# Start everything
docker compose up -d

# Check logs
docker compose logs -f litellm

Перевірка працездатності

# Health check
curl http://localhost:4000/health

# Test a request
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]}'

Якщо ви бачите успішну відповідь, ваш продакшен-стек працює. PostgreSQL зберігає всі дані про витрати, віртуальні ключі та метрики використання навіть після перезапуску контейнерів.

Вердикт: Docker Compose + PostgreSQL — рекомендоване налаштування для продакшену. Воно надає вам постійне сховище, відстеження витрат і віртуальні ключі приблизно за 10 хвилин роботи. Документація з розгортання Docker охоплює Kubernetes і Helm, якщо пізніше знадобиться автомасштабування.

Розбір config.yaml: реальне налаштування з кількома постачальниками

Більшість туторіалів показують config.yaml з однією моделлю. Ось як виглядає реальна конфігурація команди з трьома постачальниками, резервними варіантами та балансуванням навантаження.

Файл конфігурації

# config.yaml -- Real multi-provider setup
model_list:
  # Primary: OpenAI GPT-4o
  - model_name: gpt-4o          # The name YOUR code uses
    litellm_params:
      model: openai/gpt-4o      # The actual provider/model
      api_key: os.environ/OPENAI_API_KEY

  # Secondary: Anthropic Claude
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

  # Local: Ollama for development / cost-free testing
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.1
      api_base: http://host.docker.internal:11434

  # Fallback: route "gpt-4o" to Claude if OpenAI is down
  - model_name: gpt-4o
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: least-busy    # Load balance across same-name models
  num_retries: 3
  retry_after: 5                  # Seconds between retries
  fallbacks: [{"gpt-4o": ["claude-sonnet"]}]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

Аліаси моделей та маршрутизація

Зауважте, що gpt-4o з'являється в конфігурації двічі: один раз вказує на OpenAI, інший — на Anthropic. Коли ваш код запитує gpt-4o, LiteLLM спочатку пробує OpenAI. Якщо це не вдається, налаштування fallbacks автоматично перенаправляє запит до Claude. Код вашого додатку зовсім не змінюється.

Якщо ви використовуєте продакшен-бекенди для інференсу, такі як vLLM або SGLang, ви можете додати їх так само, просто встановивши api_base на адресу вашого сервера інференсу.

Швидка довідка по постачальниках

Налаштування routing_strategy: least-busy розподіляє запити між моделями з однаковим model_name. Якщо у вас є два ключі OpenAI (наприклад, різні організації з різними лімітами швидкості), перелічіть обидва під gpt-4o, і LiteLLM збалансує навантаження.

Віртуальні ключі: API-ключі для кожної команди з бюджетами та лімітами швидкості

Саме тут LiteLLM перестає бути «просто проксі» і стає інструментом управління командою. Віртуальні ключі дозволяють надавати кожному члену команди або сервісу власний API-ключ із лімітами витрат та обмеженнями швидкості, усе це маршрутизується через ваш єдиний набір ключів API постачальників.

Створення ключа команди з бюджетом

# Create a virtual key with a $50/month budget
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "frontend-team",
    "max_budget": 50.0,
    "budget_duration": "1mo",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"purpose": "frontend AI features"}
  }'

У відповіді ви отримаєте новий ключ, наприклад sk-team-abc123.... Передайте його фронтенд-команді. Вони можуть використовувати його точно так само, як ключ OpenAI, але він обмежений сумою $50/місяць і має доступ лише до моделей, які ви вказали.

Встановлення обмежень швидкості

# Create a key with rate limits: 100 requests/minute, 50K tokens/minute
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "backend-team",
    "max_budget": 200.0,
    "budget_duration": "1mo",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "models": ["gpt-4o", "claude-sonnet", "local-llama"]
  }'

Документація з віртуальних ключів охоплює кожен параметр. Ви також можете встановити бюджети та обмеження швидкості для кожного користувача для ще більш детального контролю.

Моніторинг використання ключів

import requests

# Check a key's current spend and limits
response = requests.get(
    "http://localhost:4000/key/info",
    headers={"Authorization": f"Bearer {MASTER_KEY}"},
    params={"key": "sk-team-abc123..."}
)
info = response.json()
print(f"Spent: ${info['spend']:.2f} / ${info['max_budget']:.2f}")
print(f"RPM used: {info['rpm_limit_used']} / {info['rpm_limit']}")

Потрібно відкликати компрометований ключ? Один API-виклик:

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["sk-team-abc123..."]}'

Вердикт: саме віртуальні ключі роблять LiteLLM командним інструментом, а не просто особистим проксі. Без них ви просто додаєте зайву ланку між вашим кодом та LLM. З ними ви отримуєте контроль доступу, примусове дотримання бюджету та атрибуцію використання — те, що не дасть вашому фінансовому директору панікувати.

Відстеження витрат та панель керування LiteLLM

Після підключення PostgreSQL LiteLLM автоматично відстежує вартість кожного запиту. Вам не потрібно нічого налаштовувати; система знає ціну за токен для кожної підтримуваної моделі.

Панель керування

Отримайте доступ до вбудованого інтерфейсу за адресою http://localhost:4000/ui (увійдіть, використовуючи свій майстер-ключ). Ви побачите:

• Загальні витрати по всіх командах і ключах
• Розбивку по моделях: які моделі «з'їдають» ваш бюджет
• Витрати по командах: хто і що використовує
• Обсяг запитів у динаміці

Для команд, серйозно налаштованих на зниження витрат на API LLM, сама лише панель керування виправдовує запуск проксі. Ви також можете підключити LiteLLM до зовнішніх платформ спостережуваності за AI, таких як Langfuse або Helicone, для глибшої аналітики.

Порівняння витрат по постачальниках

Ось скільки коштують основні моделі за мільйон токенів (станом на квітень 2026 року):

Коли ви бачите ці цифри в панелі керування з розбивкою по командах, розмови на тему «чи варто використовувати дешевшу модель для цього випадку?» стають дуже конкретними.

Вердикт: лише відстеження витрат виправдовує використання проксі для будь-якої команди, яка витрачає >$100/місяць на API LLM. Ви не можете оптимізувати те, що не вимірюєте.

Підключення AI-IDE: Claude Code, Cursor та Continue

Ось що більшість посібників з LiteLLM повністю пропускають: ви можете спрямувати свої інструменти AI-кодування на проксі. Один проксі, усі ваші IDE-інструменти, єдиний білінг.

Claude Code

# Set Claude Code to use your LiteLLM proxy
export ANTHROPIC_BASE_URL=http://localhost:4000/v1
export ANTHROPIC_API_KEY=sk-team-your-virtual-key

Це все. Claude Code надсилає запити до вашого проксі, який маршрутизує їх до Anthropic (або туди, куди вказує ваша конфігурація), одночасно відстежуючи витрати за вашим віртуальним ключем.

Cursor

У налаштуваннях Cursor додайте власний ендпоінт, сумісний з OpenAI:

{
  "openai.apiBaseUrl": "http://localhost:4000/v1",
  "openai.apiKey": "sk-team-your-virtual-key"
}

Continue (VS Code)

У файлі config.json для Continue:

{
  "models": [
    {
      "title": "GPT-4o via LiteLLM",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-team-your-virtual-key"
    }
  ]
}

Навіщо це робити? Тому що тепер використання IDE кожного розробника проходить через проксі. Ви отримуєте відстеження витрат на AI-асистенти кодування для кожної особи, обмеження швидкості, щоб ніхто випадково не «спалив» $500 за сеанс кодування, та єдине місце для зміни моделей, якщо ви знайдете кращий варіант.

Усунення поширених проблем

«Config file not found» (Файл конфігурації не знайдено)

Зазвичай це означає, що шлях монтування тома в Docker неправильний. Переконайтеся, що ваш config.yaml знаходиться в директорії, з якої ви монтуєте:

# Check the file exists where you think it does
ls -la ./config.yaml

# The volume mount in docker-compose.yml should match
# volumes:
#   - ./config.yaml:/app/config.yaml

«Connection refused» до PostgreSQL

Мережа Docker хоч раз, та впіймає кожного. Якщо LiteLLM не може досягти Postgres, перевірте, чи:

• Назва служби в DATABASE_URL збігається з назвою служби Docker Compose (postgres, а не localhost)
• Встановлено depends_on з умовою condition: service_healthy (щоб LiteLLM чекав, поки Postgres буде готовий)
• Обидві служби знаходяться в одній мережі Docker (за замовчуванням у Compose вони там)

«Invalid API key format» (Невірний формат ключа API)

Найпоширеніша плутанина: ваш LITELLM_MASTER_KEY призначений для адміністративних операцій (створення віртуальних ключів, доступ до панелі керування). Віртуальні ключі (sk-team-...) — це те, що використовують ваші додатки. Не плутайте їх.

«Model not found» (Модель не знайдено)

Поле model у вашому запиті має збігатися з model_name у config.yaml. Якщо ваша конфігурація визначає gpt-4o, а ваш код запитує openai/gpt-4o, збігу не буде. Перевірте точне написання.

Проксі запускається, але запити «висять»

Зазвичай це проблема фаєрволу або прив'язки портів. Переконайтеся, що порт 4000 відкритий і не заблокований:

# Check if the port is listening
docker port litellm-proxy
# Should show: 4000/tcp -> 0.0.0.0:4000

Безпека: уникайте версій 1.82.7 та 1.82.8

У березні 2026 року інцидент із ланцюгом поставок вплинув на версії LiteLLM 1.82.7 та 1.82.8. Компрометовані версії були вилучені, а чистий реліз випущено під номером 1.83.0. Завжди фіксуйте конкретну версію свого Docker-образу та перевіряйте офіційне оновлення безпеки перед оновленням. Якщо ви використовуєте 1.82.7 або 1.82.8, оновіться негайно.

Який метод налаштування LiteLLM обрати?

Якщо ви читаєте цей посібник вперше, почніть з Docker Compose + PostgreSQL. Ви завжди можете мігрувати на Kubernetes пізніше, файл config.yaml залишиться тим самим.

FAQ

Що таке LiteLLM proxy і як він працює?

LiteLLM proxy — це опенсорсний сервер AI-шлюзу, який знаходиться між вашими додатками та постачальниками LLM, такими як OpenAI та Anthropic. Він надає єдиний ендпоінт, сумісний з OpenAI, тому ваш код спілкується з однією URL-адресою, тоді як проксі займається маршрутизацією, управлінням ключами, відстеженням витрат та резервними варіантами «за лаштунками».

Як налаштувати LiteLLM proxy за допомогою Docker Compose?

Створіть docker-compose.yml з образом LiteLLM proxy та базою даних PostgreSQL, змонтуйте свій config.yaml, встановіть ключі API як змінні середовища та запустіть docker compose up -d. У розділі «Продакшен-налаштування Docker Compose» вище наведено повний файл, готовий до копіювання.

Як керувати API-ключами команди за допомогою LiteLLM?

Використовуйте віртуальні ключі. Зверніться до ендпоінту /key/generate зі своїм майстер-ключем, щоб створити ключі для кожної команди або користувача. Кожен віртуальний ключ може мати власний місячний бюджет, обмеження швидкості (RPM і TPM) та обмеження доступу до моделей. Розділ «Віртуальні ключі» охоплює весь робочий процес.

Як додати відстеження витрат та обмеження швидкості до мого LLM API?

Підключіть PostgreSQL до проксі (через DATABASE_URL), і відстеження витрат відбуватиметься автоматично. Для обмеження швидкості встановіть rpm_limit та tpm_limit під час генерації віртуальних ключів. Вбудована панель керування за адресою /ui показує витрати по командах та моделях.

Чи безпечно використовувати LiteLLM proxy у продакшені?

Так, з одним застереженням: уникайте версій 1.82.7 та 1.82.8, на які вплинув інцидент із ланцюгом поставок у березні 2026 року. Використовуйте версію 1.83.0 або новішу. Зафіксуйте версію свого Docker-образу, встановіть LITELLM_SALT_KEY для шифрування та дотримуйтесь офіційних найкращих практик для продакшену.

Яка різниця між LiteLLM SDK та LiteLLM proxy?

SDK — це бібліотека Python для виклику кількох LLM API з вашого коду. Проксі — це окремий сервер, до якого підключається вся ваша команда. Використовуйте SDK, якщо ви соло-розробник і пишете скрипт. Використовуйте проксі, якщо вам потрібен спільний контроль доступу, відстеження витрат та обмеження швидкості для всієї команди.

Чи можна використовувати LiteLLM proxy з Ollama та локальними моделями?

Безумовно. Додайте запис у свій config.yaml з model: ollama/llama3.1 та api_base: http://host.docker.internal:11434 (або хостом вашого Ollama). Тоді ваша команда зможе отримати доступ до локальних моделей через той самий ендпоінт проксі, що чудово підходить для розробки та безкоштовного тестування.

Скільки коштує LiteLLM proxy?

LiteLLM proxy є безкоштовним та опенсорсним (ліцензія MIT). Ви розміщуєте його на власній інфраструктурі. Єдині витрати — це ваш сервер (невеликого VPS достатньо для більшості команд) та витрати на API LLM, які ви вже оплачуєте. BerriAI також пропонує керовану хмарну версію, якщо ви не хочете розміщувати її самостійно.

Яких постачальників підтримує LiteLLM?

Понад 100, включаючи OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Ollama, Hugging Face, Cohere, Replicate та багатьох інших. Повний список є на репозиторії LiteLLM у GitHub.

Як безпечно оновити LiteLLM proxy?

Завжди фіксуйте конкретну версію в тезі вашого Docker-образу (наприклад, ghcr.io/berriai/litellm:v1.83.2-stable). Перед оновленням перевірте журнал змін на наявність критичних змін. Ніколи не використовуйте latest у продакшені. І завжди перевіряйте, чи нова версія не входить до списку попереджень безпеки; інцидент у березні 2026 року довів, що навіть довірені пакети можуть бути компрометовані.

Фінальний вердикт та наступні кроки

Якщо ваша команда витрачає гроші на API LLM і у вас ще немає проксі, почніть з Docker Compose + Postgres сьогодні. Налаштування займає 15 хвилин, і до кінця ви отримаєте видимість витрат та контроль доступу.

Коли все запрацює, досліджте можливість додавання захисних бар'єрів до вашого LLM-пайплайну для фільтрації контенту та перевірок безпеки. Проксі є фундаментом, все інше будується поверх нього.

Джерела

• Швидкий старт LiteLLM Proxy, офіційна документація
• Посібник з розгортання LiteLLM у Docker
• Документація з віртуальних ключів LiteLLM
• Найкращі практики LiteLLM для продакшену
• Оновлення безпеки LiteLLM, березень 2026
• BerriAI/litellm, репозиторій GitHub