SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor

Як розгорнути LiteLLM як власний LLM gateway

Налаштуйте єдиний OpenAI сумісний endpoint для всіх моделей. Керуйте віртуальними ключами, встановлюйте ліміти витрат та налаштовуйте автоматичні fallbacks на власному VPS.

Що робить self-hosted LLM gateway

LiteLLM — це open source LLM gateway, який ви розгортаєте самостійно: один HTTP endpoint, до якого звертаються всі ваші застосунки. Gateway передає кожен запит тому провайдеру, який має на нього відповісти. LLM означає large language model. Gateway використовує OpenAI chat completions API (application programming interface), тому будь-яка клієнтська бібліотека, яка вже працює з OpenAI, працюватиме і з ним після двох змін: base URL і key.

У цьому й полягає призначення такого шару абстракції. Застосунки більше не зберігають облікові дані провайдерів. Щоб змінити модель, достатньо змінити один рядок у конфігураційному файлі на сервері, а не вносити зміни в код п’яти сервісів. Оскільки кожен виклик проходить через один процес, у вас є централізоване місце для встановлення бюджету та обліку витрат.

Після запуску ви отримуєте:

  • Один endpoint. Застосунки звертаються до https://gateway.example.com/v1 і запитують модель із заданою вами назвою, наприклад bulk або strong.
  • Віртуальні ключі. Кожен застосунок отримує власний key із власним allowlist моделей і власним лімітом витрат. Один ключ можна відкликати, не змінюючи інші.
  • Fallbacks. Якщо запит завершується помилкою або prompt перевищує допустимий розмір, його автоматично повторно надсилають до іншої моделі.
  • Запис у журналі. Для кожного запиту записується рядок із його вартістю, тому на запитання «який застосунок це витратив?» є відповідь.

Навіщо запускати gateway самостійно

Керований router має таку саму схему, але між кожним запитом і сервісом працює процес стороннього постачальника. Якщо запускати його самостійно, ключі провайдера та текст prompt зберігаються на сервері під вашим контролем. Ціна цього рішення реальна: тепер ви обслуговуєте компонент, від якого залежить кожен застосунок. Останній розділ цього посібника присвячено цій ціні, оскільки в більшості матеріалів про неї не згадують.

Що потрібно

  • VPS (віртуальний приватний сервер) під керуванням Ubuntu 24.04, на якому встановлено Docker і плагін Compose.
  • Доменне ім’я, що вказує на цей сервер, якщо зовнішні клієнти підключатимуться до шлюзу через TLS (захист транспортного рівня).
  • Щонайменше один API-ключ провайдера.

Шлюз не виконує інференс. Він пересилає запити та передає відповіді потоком, тому навантаження на CPU залежить від кількості запитів, а не від розміру моделі. Сервер із 1 vCPU без проблем обслуговує кілька внутрішніх застосунків. Зростає база даних, оскільки шлюз записує один рядок витрат для кожного запиту.

Спочатку запишіть config.yaml

Файл конфігурації визначає, які моделі може запитувати клієнт. Важливі чотири секції верхнього рівня: model_list, litellm_settings, router_settings і general_settings.

model_list:
  - model_name: bulk
    litellm_params:
      model: anthropic/claude-haiku-4-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: openai/gpt-5.5
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  num_retries: 2
  request_timeout: 120
  json_logs: true
  set_verbose: false

router_settings:
  allowed_fails: 3
  cooldown_time: 30
  fallbacks: [{"bulk": ["strong"]}]
  context_window_fallbacks: [{"bulk": ["strong"]}]

general_settings:
  background_health_checks: true
  health_check_interval: 300

model_name — це ім’я, яке надсилають ваші клієнти. litellm_params.model — фактична модель, записана як provider/model. Називайте моделі за призначенням, а не за постачальником. Застосунок, який запитує bulk, продовжить працювати, навіть якщо наступного місяця ви вирішите, що bulk має бути іншою моделлю.

api_key: os.environ/ANTHROPIC_API_KEY вказує LiteLLM зчитувати цю змінну під час роботи. Сам ключ у файлі не з’являється. Це важливо, оскільки config.yaml — файл, який ви додаєте до репозиторію.

Два записи навмисно мають однакове ім’я strong. Якщо кілька deployment мають однаковий model_name, router вважає їх взаємозамінними та розподіляє між ними запити для цього імені. Завдяки цьому strong продовжує працювати, якщо в одного постачальника тимчасово виникають проблеми: після переведення deployment у cooldown (див. нижче) нові запити для strong надходять до іншого deployment.

num_retries: 2 повторює запит після помилки, яку можна повторити, щонайбільше двічі. Під час цих повторів можна вибрати інший доступний deployment у тій самій групі моделей: в архітектурній документації LiteLLM, перевіреній 2026-10-29, повтори в межах групи та fallback між групами описані як окремі етапи. Тому повторний запит для strong може перейти до іншого постачальника без увімкнення weighted failover. Fallback спрацьовує лише після завершення цих повторів.

allowed_fails і cooldown_time — це опції router, тому вони мають бути вкладені в router_settings. Proxy створює router на основі цієї секції. У v1.95.0 параметр cooldown_time, записаний у litellm_settings, до router не потрапляє, тому cooldown непомітно залишається зі стандартним значенням 5 секунд. cooldown_time: 30 визначає, як довго deployment залишається виключеним із розподілу запитів після переходу в cooldown. У довіднику конфігурації allowed_fails описано як кількість помилок, яку deployment має перевищити протягом cooldown_time, перш ніж його буде переведено в cooldown. У вихідному коді v1.95.0 allowed_fails: 3 має значення за замовчуванням. Якщо залишити це значення, router використовує вбудовані умови спрацювання. Лічильник помилок починає діяти лише після встановлення іншого значення. Ці умови включають негайний cooldown після відповіді 429 для групи з кількома deployment, понад 50% помилок у поточній хвилині після щонайменше 5 запитів для такої групи, а також помилки, які router не повторює, наприклад 401 через неправильний ключ. Окрема умова переводить у cooldown один deployment, якщо всі запити в поточній хвилині завершилися помилкою, а трафік досяг SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD, що за замовчуванням становить 1000 запитів. Тому для strong, який має два deployment, сплеск відповідей 500 від постачальника припиняє повторне використання цього deployment для кожного наступного запиту. Водночас поодинока відповідь 500 раз на кілька хвилин не запускає cooldown. bulk має лише один deployment, тому умова за часткою помилок до нього не застосовується: сплеск відповідей 500, що не перевищує 1000 запитів за хвилину, не виключає його з розподілу запитів. Його клієнтів захищає num_retries, після якого виконується fallback до strong.

fallbacks і context_window_fallbacks мають різні умови спрацювання. Друга з них є корисною, але її часто пропускають.

  • fallbacks спрацьовує, коли основний виклик завершується помилкою.
  • context_window_fallbacks спрацьовує, коли постачальник відхиляє запит через перевищення розміру контекстного вікна цієї моделі. Тому надто великий prompt передається моделі, яка може його обробити, замість повернення помилки клієнту.

Також існує content_policy_fallbacks — для випадків, коли постачальник відхиляє запит через політику щодо вмісту. Встановлюйте його лише тоді, коли маєте коректний маршрут для таких запитів.

Розгорніть LiteLLM на VPS за допомогою Docker Compose

Створіть каталог із трьома файлами: config.yaml, docker-compose.yml і .env. У quickstart від upstream використовується тег latest. Замість нього зафіксуйте тег релізу. Тоді оновлення відбуватиметься лише після редагування файлу, а відкат зводитиметься до зміни одного рядка. Сам тег не гарантує ідентичний вміст, оскільки теги образів можна змінювати, і видавець може прив’язати тег до нового образу. Якщо docker compose up -d наступного місяця має надавати рівно той самий gateway, що й сьогодні, додайте також digest образу у форматі ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>; командою docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 його можна вивести.

services:
  litellm:
    image: ghcr.io/berriai/litellm:v1.95.0
    restart: unless-stopped
    command: ["--config", "/app/config.yaml", "--num_workers", "1"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file: .env
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: litellm
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Compose двічі читає .env. Один раз — щоб підставити ${POSTGRES_PASSWORD} безпосередньо у файл compose, і один раз через env_file, щоб передати в контейнер усі змінні.

v1.95.0 був поточним релізом у серпні 2026 року. Перевірте сторінку релізів проєкту та зафіксуйте версію, актуальну на момент розгортання. Для кожного релізу публікується підпис, тому перед перевіркою образу перевірте його автентичність:

cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0

Рядок із портом має вигляд 127.0.0.1:4000:4000. Він публікує порт лише на loopback-інтерфейсі. Якщо натомість записати 4000:4000, gateway стане доступним з усього інтернету. Docker додає власні правила до ланцюжка iptables FORWARD і обробляє їх раніше за правила ufw, тому ufw deny 4000 це не зупинить. Це найпоширеніший спосіб, у який self-hosted gateway стає доступним з інтернету: див. як Docker публікує порт контейнера безпосередньо в обхід ufw. Зовнішній трафік надходить через reverse proxy.

Не зберігайте ключі провайдерів в образі

Файл .env містить усі секрети. Під час запуску він передається як змінні середовища, тому секрети не вбудовуються в образ і файл ніколи не додається до репозиторію.

LITELLM_MASTER_KEY=sk-REPLACE_ME
LITELLM_SALT_KEY=sk-REPLACE_ME_TOO
POSTGRES_PASSWORD=REPLACE_ME_AS_WELL
DATABASE_URL=postgresql://litellm:REPLACE_ME_AS_WELL@db:5432/litellm
STORE_MODEL_IN_DB=True
LITELLM_MODE=PRODUCTION
LITELLM_LOG=ERROR
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...

Згенеруйте два ключі LiteLLM із використанням криптографічно стійкої випадковості, а потім обмежте права доступу до файлу:

printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .env

LITELLM_MASTER_KEY — облікові дані адміністратора. Вони використовуються для автентифікації Management API і є паролем для Admin UI за адресою /ui. Жоден застосунок не повинен їх зберігати.

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

STORE_MODEL_IN_DB=True дає змогу додавати й редагувати моделі в Admin UI без змін у config.yaml. Це зручно, але джерел правди стає два. Визначте, яке з них є основним, і зафіксуйте це рішення поруч із конфігурацією.

Логіка, за якою ключі не зберігають у файлі конфігурації, так само стосується інструментів, які ви надаєте агенту. У матеріалі Не зберігайте секрети провайдерів у AI-агентів описано цей підхід, а в матеріалі Файли env і секрети в Docker Compose — практичну реалізацію.

Запустіть сервіс і стежте за першим запуском:

docker compose up -d
docker compose logs -f litellm

Перевірте фактичну роботу

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

curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness

/health/liveliness не потребує автентифікації та повертає відповідь "I'm alive!", поки процес працює. /health/readiness також не потребує автентифікації. Він повертає JSON-об’єкт із полем "status": "healthy" і полем db або код 503, якщо база даних недоступна. Налаштовуйте моніторинг на readiness, оскільки liveliness залишатиметься успішною на gateway, який не може знайти жодного virtual key.

Перевірка з автентифікацією — це та, що звертається до providers:

curl -s http://127.0.0.1:4000/health \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

Вона повертає масиви healthy_endpoints і unhealthy_endpoints. Якщо модель у unhealthy_endpoints має помилку автентифікації, це означає, що ключ provider у .env неправильний або відсутній. Саме цю помилку потрібно знайти зараз. Оскільки background_health_checks: true встановлено, proxy самостійно виконує ці проби кожні health_check_interval секунд, а /health повертає останній результат. Тому опитування цього endpoint не надсилає тестовий запит до providers щоразу.

Віртуальні ключі та бюджети для кожного ключа

Кожен застосунок отримує власний ключ, створений на основі головного ключа.

curl -s http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "key_alias": "nightly-summariser",
    "models": ["bulk"],
    "max_budget": 5,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 200000
  }'

Відповідь містить поле key, значення якого починається з sk-. Саме цей рядок отримує застосунок. Це єдине, що отримує застосунок.

  • models — це список дозволених операцій, які може виконувати цей ключ. Наведений вище ключ може запитувати bulk і нічого іншого.
  • max_budget: 5 зі значенням budget_duration: "30d" — це п’ять доларів США на календарний місяць. LiteLLM скидає бюджет 30d 1-го числа кожного місяця опівночі за UTC, якщо ви не вкажете timezone у розділі litellm_settings. Бюджет не обчислюється за ковзний період у 30 днів. Після витрати п’яти доларів ключ припиняє працювати до наступного 1-го числа.
  • rpm_limit і tpm_limit обмежують кількість запитів за хвилину та кількість токенів за хвилину лише для цього ключа.
  • key_alias — це значення, яке ви побачите в журналі витрат через шість тижнів. Завжди задавайте його.

Коли бюджет вичерпано, виклик завершується помилкою типу budget_exceeded і повідомленням такого формату:

Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>

Код стану залежить від версії. У зафіксованій версії v1.95.0 це HTTP 429. Починаючи з v1.104.0, типовим є HTTP 422. Параметр budget_exceeded_status_code: 429 у розділі litellm_settings повертає попередній код. Справжнє перевищення rpm_limit і tpm_limit в обох версіях і далі повертає 429. Після кожного оновлення перевіряйте, який код ви отримуєте.

Код стану ускладнює діагностику, оскільки жоден із цих кодів не вказує на бюджет. Клієнтська бібліотека сприймає 429 як обмеження частоти й може повторювати запит із затримкою, хоча бюджет не відновиться до моменту скидання. Код 422 вона сприймає як запит, який не вдалося обробити. Записуйте тіло відповіді разом із кодом стану. Інакше вичерпання бюджету щоразу виглядатиме як інша проблема.

Переглядати та змінювати ключі можна через той самий API керування:

curl -s "http://127.0.0.1:4000/key/info?key=sk-..." \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

curl -s -X POST http://127.0.0.1:4000/key/update \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key": "sk-...", "max_budget": 25}'

Бюджет, контрольований на шлюзі, діє навіть тоді, коли проблема виникла в самому агенті. Саме тому він є основою контролю витрат на AI-агентів на VPS.

Передавайте масові завдання дешевій моделі

Спрямуйте клієнт на gateway. Базова URL-адреса, ключ і назва моделі:

curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bulk",
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'

Будь-яка клієнтська бібліотека OpenAI працює так само, хоча назви параметрів відрізняються залежно від мови. У клієнті Python встановіть base_url у значення https://gateway.example.com/v1, а api_key — у віртуальний ключ. У клієнті JavaScript і TypeScript ті самі два параметри мають назви baseURL і apiKey.

Політика маршрутизації з config.yaml тепер застосовується без відома клієнта. Запит до bulk надходить до дешевої моделі. Якщо цей виклик завершується помилкою після всіх повторних спроб, запит повторно надсилається до strong. Якщо prompt задовгий для bulk, context_window_fallbacks надсилає його до strong замість повернення помилки. Масові завдання, як-от класифікація або узагальнення черги, за замовчуванням виконуються дешево, і лише складні запити коштують дорожче.

Саме тут gateway виправдовує використання для агентів, які працюють з інструментами. MCP (протокол контексту моделі) server на тому самому VPS і агент, який ним керує, можуть вказувати на одну endpoint, тому модель за ними можна змінити без повторного розгортання жодного з них.

Як визначити, що спрацював fallback?

Це режим відмови, який коштує грошей, бо зовні все працює. У разі успішного fallback повертається HTTP 200 зі звичайним тілом відповіді. Ваша дешева модель може бути недоступною протягом дня, усі запити непомітно оброблятиме дорожча модель, а першим доказом стане рахунок.

Доказ є в заголовках відповіді. Запросіть їх:

curl -s -D - -o /dev/null http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{"model":"bulk","messages":[{"role":"user","content":"ping"}]}' \
  | grep -i '^x-litellm'
  • x-litellm-model-group — назва моделі, під якою було маршрутизовано запит, наприклад bulk. x-litellm-model-id — ID deployment, який надав відповідь. Його можна знайти за допомогою /v1/model/info?litellm_model_id=.... Якщо цей ID не належить жодному з ваших deployment bulk, спрацював fallback.
  • x-litellm-attempted-fallbacks і x-litellm-attempted-retries підраховують їх. Для штатного запиту жодне з цих значень не має бути більшим за 0.
  • x-litellm-response-cost — вартість цього запиту в доларах США.
  • x-litellm-call-id — ідентифікатор, за яким можна знайти цей самий запит у журналах.

Записуйте x-litellm-attempted-fallbacks для кожного запиту та створіть alert, якщо його значення перевищує 0. Це число визначає різницю між політикою маршрутизації, яка працює, і політикою, що непомітно перетворилася на «завжди використовувати дорожчу модель».

Повна реалізація цього підходу — tracing. Вона потребує окремого налаштування: self-hosted Langfuse для tracing викликів агентів. LiteLLM постачається з callback, тому його підключення потребує двох рядків і облікових даних.

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

Для Langfuse v3 і новіших версій сторінка LiteLLM для Langfuse тепер рекомендує preset langfuse_otel; callback langfuse, наведений вище, усе ще задокументований. Задайте також failure_callback і success_callback. Якщо пропустити цей крок, зберігатимуться лише trace, у яких нічого не пішло не так. Окремо від цього LiteLLM записує рядок про витрати для кожного запиту в Postgres, а Admin UI за адресою /ui читає цю таблицю. Вона зростає разом із трафіком, тому контролюйте її розмір на диску малої ємності.

Розміщення шлюзу за reverse proxy

Жоден зовнішній запит не повинен мати доступ до порту 4000. Виконуйте TLS termination на рівні nginx або Caddy та перенаправляйте трафік на адресу loopback.

location / {
    proxy_pass http://127.0.0.1:4000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
}

Два з цих рядків часто забувають додати. proxy_buffering off важливий, оскільки потокове завершення (streaming completion) — це послідовність server-sent events, а з увімкненим буферизацією nginx збирає фрагменти в буфери перед відправкою, що затримує доставку клієнту. proxy_read_timeout 600s важливий, оскільки стандартний ліміт nginx у 60 секунд — це максимальний час очікування між двома операціями читання зі шлюзу, а не загальний ліміт на всю відповідь. Непотокова відповідь не надсилає нічого, доки генерація не завершиться, тому тривала генерація перевищує 60 секунд без жодного байта даних, і клієнт отримує помилку 504, а в журналі помилок фіксується upstream timed out (110: Connection timed out) while reading response header from upstream. Потокова відповідь, що постійно надсилає фрагменти, може тривати значно довше 60 секунд; таймаут спрацює лише в тому разі, якщо модель не надсилатиме дані протягом цього часу.

Для отримання сертифіката Certbot з Let's Encrypt на nginx є найшвидшим шляхом. Якщо сервер уже обслуговує кілька контейнерів, Traefik перед кількома Compose-застосунками забезпечить маршрутизацію та керування сертифікатами в одному місці.

Шлюз тепер є єдиною точкою відмови

Будьте відвертими щодо того, що ви побудували. Кожен ваш застосунок тепер залежить від одного контейнера на одному VPS. Поки він не працює, ніщо не може звернутися до жодної моделі, навіть до тих провайдерів, які повністю справні. З цього випливають чотири наслідки.

  • Помилкова конфігурація виводить з ладу все одночасно. restart: unless-stopped перезапускає процес після збою, і він знову намагається запустити контейнер, який не може обробити config.yaml, знову і знову. Читайте docker compose logs litellm після кожної зміни конфігурації та вносьте зміни тоді, коли маєте час за ними спостерігати.
  • Postgres знаходиться на шляху запиту при промаху кешу. Пошук віртуального ключа використовує його, коли ключ не кешований; запис витрат відбувається асинхронно після відповіді. /health/readiness, що повертає 503, є вашим попередженням про те, що шлюз працює, але не може виконати жодну з цих дій.
  • Спочатку використовуйте ядра, потім додавайте екземпляри. Рекомендація проєкту щодо продуктивності — один воркер на екземпляр (--num_workers 1) — призначена для Kubernetes або іншого автоскейлера подів, який додає екземпляри за вас. Для окремої VM або такого контейнера, як цей, правило протилежне: встановіть кількість воркерів відповідно до кількості vCPU машини. На машині з 1 vCPU, згаданій вище, це все ще --num_workers 1; на потужнішій машині збільште це значення, пам’ятаючи, що кожен воркер споживає власну пам’ять. Другий шлюз за балансувальником навантаження усуває проблему єдиного контейнера. Це не усуває проблему бази даних.
  • Робіть резервні копії того, що неможливо відновити. Це config.yaml та .env разом із pg_dump бази даних. Втрата LITELLM_SALT_KEY робить зашифровані облікові дані провайдерів у цьому дампі марними, тому env-файл і дамп мають бути в одному завданні резервного копіювання: резервне копіювання restic на зовнішнє сховище.

Оновлення полягає у зміні тегу образу та запуску docker compose up -d. LiteLLM за замовчуванням виконує prisma migrate deploy під час запуску, тому новий контейнер мігрує схему бази даних при першому завантаженні. Зробіть дамп перед зміною тегу, оскільки повернення старого образу не скасовує міграцію, яка вже була виконана.

Читайте примітки до випуску кожної версії, яку ви пропускаєте, а не лише тієї, на яку переходите. Перехід з v1.95.0 на v1.104.0 або новішу версію містить кілька критичних змін: код статусу бюджету, згаданий вище, проксі, який відмовляється запускатися з не встановленим, порожнім або загальновідомим майстер-ключем, і проксі, який завершує роботу, якщо налаштування бази даних не вдалося під час запуску, що за restart: unless-stopped виглядає як цикл перезавантажень. При переході з v1.102.x або раніших версій, примітки до v1.104.0 також вимагають від вас самостійно створити два LiteLLM_SpendLogs індекси.

FAQ

Чи додає LiteLLM помітну затримку до кожного виклику?

Проєкт вказує 8 ms на 95-му перцентилі за 1000 запитів на секунду, як зазначено в його README у листопаді 2026. Вважайте це даними постачальника. На фактичну затримку найбільше впливає мережева відстань між застосунками та шлюзом, оскільки кожен виклик отримує додатковий round trip. Розмістіть шлюз у тому самому регіоні, що й застосунки, які його викликають, а потім виміряйте власні накладні витрати за заголовком x-litellm-overhead-duration-ms у реальній відповіді.

Чому потокова передача перестала працювати після встановлення nginx перед шлюзом?

Тому що nginx за замовчуванням буферизує відповіді upstream, а потокова генерація — це послідовність server-sent events. Коли proxy_buffering увімкнено, nginx накопичує фрагменти в буферах перед передаванням їх клієнту, через що доставка затримується. Установіть proxy_buffering off; у блоці location. У цьому самому блоці також збільште proxy_read_timeout. За замовчуванням nginx припиняє очікування після 60 секунд без даних від шлюзу. Тривала генерація без потокової передачі легко перевищує цей час, і клієнт отримує 504.

Що відбувається, коли віртуальний ключ вичерпує бюджет?

Виклик завершується помилкою типу budget_exceeded і повідомленням форми Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>. У зафіксованій версії v1.95.0 статусом є HTTP 429, а починаючи з v1.104.0 типовим статусом є HTTP 422. Жоден із цих кодів не вказує на бюджет. У цьому полягає проблема: клієнтська бібліотека сприймає 429 як перевищення ліміту запитів і може повторити запит, тому замість аналізу повідомлення користувачі починають шукати причину в throttling. Записуйте тіло відповіді разом із кодом статусу. Перевірте фактичне положення ключа за допомогою /key/info?key=sk-..., використовуючи master key, і збільште ліміт за допомогою /key/update, якщо бюджет установлено надто низьким.

Чи може шлюз маршрутизувати запити до локальної моделі та до hosted-моделей?

Так. Це ще один запис у model_list. Використовуйте префікс ollama_chat/ з api_base, наприклад model: ollama_chat/llama3.1 разом із api_base: http://ollama:11434. У типовій мережі Compose localhost усередині контейнера означає цей самий контейнер. Тому використовуйте ім’я сервісу Compose або адресу хоста в Docker network, але не 127.0.0.1. Винятком є host networking, за якого контейнер використовує мережевий стек хоста. Розгортання локальної моделі є окремим завданням: див. self-hosting LLM з Ollama на VPS.

Чи була ця стаття корисною?