Справочник

LiteLLM: что это, как запустить и что показал прогон

17 сентября 2026 · 15 минут чтения

Проверка фактов

Юлия Найпак

Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.

Автор Р

Редакция

Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Пакет поставлен, прокси поднят и опрошен 17 сентября 2026 года; каждое число ниже снято этим прогоном или названным документом. Обновлено: сентябрь 2026.

LiteLLM — это открытый слой между кодом и провайдерами языковых моделей: один интерфейс в формате OpenAI, за которым стоят OpenAI, Anthropic, Gemini, Bedrock, Azure, Ollama и десятки других. Живёт в двух видах — библиотекой для Python и прокси-шлюзом, который поднимается отдельным сервисом на порту 4000. Что это даёт на практике: смена модели превращается из правки кода в правку одной строки конфига.

Главное:

• Ставится одной командой pip install 'litellm[proxy]', запускается командой litellm --config config.yaml, слушает порт 4000.
• Реклама обещает «100+ провайдеров», сайт — 1800 моделей; внутри пакета лежит третье число, а по умолчанию каталог вообще скачивается при импорте.
• Виртуальные ключи, бюджеты и веб-интерфейс требуют базы Postgres — без неё лимиты не работают.
• Прогон на Windows с русской кодовой страницей падает на стартовом баннере до единой полезной строки лога.
• Строка master_key: os.environ/LITELLM_MASTER_KEY при незаданной переменной оставляет шлюз открытым, и предупреждение об этом — одна строка в логе.

Что такое LiteLLM и из чего он состоит

LiteLLM состоит из двух частей, и путать их дорого. Первая — Python-библиотека: функция completion() принимает имя модели строкой вида anthropic/claude-sonnet-5 или openrouter/openai/gpt-4o-mini и возвращает ответ в структуре OpenAI независимо от того, кто его отдал. Вторая — прокси-сервер (в документации LiteLLM он же AI Gateway): отдельный процесс с OpenAI-совместимым HTTP-эндпоинтом, к которому подключается любой клиент, умеющий менять base_url. Собственный README проекта описывает это так: single, unified interface to call 100+ LLM providers. Лицензия MIT, репозиторий BerriAI/litellm, на 17 сентября 2026 года у него 58,9 тысячи звёзд.

Разница между частями — в том, кто владеет ключами провайдеров: с библиотекой они лежат в приложении, с прокси — в одном месте, откуда приложения получают свои ключи шлюза с лимитом по моделям и бюджету.

Мини-вывод: библиотека убирает разницу форматов, прокси убирает разбросанные по репозиториям ключи.

Сколько провайдеров и моделей в LiteLLM на самом деле

Числа в рекламе LiteLLM и числа внутри пакета расходятся, и проверить это можно за одну команду. Собственный сайт проекта заявляет One OpenAI-compatible API to 140+ providers and 1,800+ models. README того же проекта говорит про «100+ LLM providers», а его таблица провайдеров содержит 105 строк. Статьи повторяют эти цифры вразнобой: Selectel пишет про инструмент, который умеет общаться со 100+ LLM-провайдерами, DevTrends — Работа с 30+ провайдерами через OpenAI-формат, блог ASI Biont оценивает каталог как ~200+ (на июль 2026).

Редакция поставила пакет и пересчитала. Прогон: pip install 'litellm[proxy]' в чистое окружение, Python 3.11.9, получена версия litellm 1.101.0 (выложена на PyPI 2026-09-14). Перечень litellm.provider_list в ней содержит 155 провайдеров. Справочник цен и окон контекста, вшитый в сам пакет, — 3817 записей, из которых одна служебная (sample_spec), то есть 3816 моделей, разложенных по 129 провайдерам.

import os
os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"   # карта из пакета, без похода в сеть
import litellm
print(len(litellm.provider_list))          # 155
print(len(litellm.model_cost) - 1)         # 3816  (минус служебный sample_spec)

Строка с переменной окружения здесь несущая, и вот почему. По умолчанию LiteLLM справочник моделей в пакете не читает: он скачивает его при импорте из репозитория проекта. Документирующая строка модуля get_model_cost_map говорит это первой фразой — карта тянется с github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json, и отключается это той самой переменной. Практическое следствие поймано в этом же прогоне: два импорта на одной машине, одной версии и без переустановки дали разные числа — 4109 моделей в 10:30 и 4110 моделей в 10:44 того же дня.

Расхождение объяснимо: «провайдер» в таблице README, в маркетинге и в перечислении provider_list считается по разным правилам, а справочник цен — прайс-лист, куда попадают одни и те же модели у разных хостингов (fireworks_ai — 320 записей, bedrock — 284, openrouter — 260). Практический смысл не в рекордном числе: набор имён зависит от версии пакета и от момента импорта, поэтому воспроизводимый ответ даёт только счёт с прикреплённой локальной картой.

Мини-вывод: в litellm 1.101.0 — 155 провайдеров и 3816 моделей, если карту цен прикрепить к пакету; без этого каталог меняется от импорта к импорту.

Как установить LiteLLM и проверить версию

Установка LiteLLM занимает одну команду, и ставить нужно именно вариант с прокси. Пакет на PyPI требует Python в диапазоне <3.15,>=3.10; всего у проекта 888 выпусков, из них 723 стабильных — темп такой, что имя поля конфигурации из прошлогодней статьи может уже не существовать.

pip install 'litellm[proxy]'
litellm --version

Вторая команда печатает LiteLLM: Current Version = 1.101.0. Привычный путь через атрибут модуля в этой версии не работает — litellm.__version__ поднимает AttributeError: module 'litellm' has no attribute '__version__', поэтому версию в скриптах берут через importlib.metadata.version("litellm"). Голый образ для Docker берут из docker.litellm.ai/berriai/litellm:latest, а исходники — из репозитория BerriAI/litellm на GitHub; отдельного «скачать LiteLLM» установщика у проекта нет, есть пакет, образ и репозиторий.

Мини-вывод: версия пакета — это то, что печатает litellm --version в вашем окружении, и она же определяет набор доступных полей конфига.

Как запустить прокси LiteLLM: config.yaml и порт 4000

Прокси LiteLLM запускается конфигурационным файлом из четырёх секций. model_list связывает публичное имя model_name, которое увидят приложения, с настоящей строкой провайдера в litellm_params. router_settings описывает маршрутизацию и резервные модели. litellm_settings задаёт общие параметры вызовов. general_settings настраивает сам шлюз, включая мастер-ключ. Ниже — конфигурация, на которой выполнен прогон этой статьи: два маршрута и правило отказа.

model_list:
  - model_name: chat-cheap
    litellm_params:
      model: openrouter/openai/gpt-4o-mini
      api_key: os.environ/OPENROUTER_API_KEY
  - model_name: chat-broken
    litellm_params:
      model: openrouter/no-such-vendor/no-such-model
      api_key: os.environ/OPENROUTER_API_KEY

router_settings:
  fallbacks: [{"chat-broken": ["chat-cheap"]}]
  num_retries: 0

litellm_settings:
  drop_params: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Запуск — litellm --config config.yaml --port 4000. Удачный старт видно по двум строкам лога: адрес сервера и перечень публичных имён из конфига.

INFO:     Uvicorn running on http://0.0.0.0:4000 (Press CTRL+C to quit)
LiteLLM: Proxy initialized with Config, Set models:
    chat-cheap
    chat-broken

После старта шлюз отвечает на /v1/models списком публичных имён, а на /v1/chat/completions — обычным ответом OpenAI. Запрос к модели, которой в конфиге нет, отбивается сразу: Invalid model name passed in model=gpt-4o.

curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-zc-local-demo" \
  -H "Content-Type: application/json" \
  -d '{"model":"chat-cheap","messages":[{"role":"user","content":"Ответь одним словом"}]}'

Мини-вывод: рабочий минимум LiteLLM — четыре секции конфига, одна команда и порт 4000.

Как работает резервная модель LiteLLM при сбое провайдера

Резервная модель LiteLLM — это автоматическое переключение на другую группу моделей, когда основная не ответила. Документация формулирует условие точно: переключение происходит после того, как исчерпаны повторы num_retries, и адресуется от одного model_name к другому. Правил три, и они разнесены по типам ошибок: content_policy_fallbacks ловит блокировку контент-фильтром, context_window_fallbacks — превышение окна контекста, fallbacks — все остальные ошибки вроде превышения лимита запросов. Список резервных обходится по порядку, а default_fallbacks работает общим запасным вариантом для любой сломанной группы.

Проверка на конфигурации выше прошла так: маршрут chat-broken указывает на заведомо несуществующую модель, num_retries: 0 отключает повторы, fallbacks переводит его на chat-cheap. Запрос к chat-broken вернул содержательный ответ модели, а срабатывание переключения видно в заголовках ответа — шлюз сам сообщает и группу, которая обслужила запрос, и число использованных резервов.

x-litellm-model-group: chat-cheap
x-litellm-attempted-fallbacks: 1
x-litellm-attempted-retries: 0

Мини-вывод: правило отказа в LiteLLM проверяется заведомо сломанным маршрутом, и результат читается в заголовках ответа.

Что показал прогон LiteLLM: два молчаливых отказа

Прогон LiteLLM 1.101.0 на Windows дал два отказа, о которых не пишет ни одна страница выдачи, и оба молчаливые. Первый — падение на старте. Русская Windows отдаёт консоли кодовую страницу cp1251, стартовый баннер LiteLLM набран символами псевдографики, и процесс умирает до того, как напечатает хоть что-то полезное:

File "...\litellm\proxy\common_utils\banner.py", line 17, in show_banner
    click.echo(f"\n{LITELLM_BANNER}\n")
UnicodeEncodeError: 'charmap' codec can't encode characters in position 5-7: character maps to <undefined>

ERROR:    Application startup failed. Exiting.

Лечится одной переменной окружения перед запуском — set PYTHONIOENCODING=utf-8 (или chcp 65001), после чего тот же конфиг поднимается за несколько секунд. Причина в функции show_banner() из файла litellm/proxy/common_utils/banner.py: вокруг вывода баннера стоит except ImportError, то есть перехвачен единственный сценарий — отсутствие библиотеки click. Ошибка кодировки к нему не относится, уходит наверх и валит запуск приложения целиком.

Второй отказ дороже. Конфиг из предыдущего раздела выглядит защищённым: master_key объявлен. Но переменная LITELLM_MASTER_KEY в окружении процесса отсутствовала, и шлюз поднялся открытым, сообщив об этом одной строкой в логе:

LiteLLM Proxy:CRITICAL: LITELLM_MASTER_KEY is not set! All requests will be treated as INTERNAL_USER with no admin access.

Дальше проверка вживую: запрос с заведомо неверным ключом sk-totally-wrong-key вернул HTTP 200 и настоящий ответ модели, то есть потратил деньги на провайдере. После перезапуска с заданной переменной тот же неверный ключ получил отказ — "message":"No connected db.", — а верный ключ продолжил работать. Документация предупреждает прямо: LITELLM_MASTER_KEY is the root credential for the gateway. Прогон добавляет к предупреждению цену ошибки: открытый шлюз внешне неотличим от закрытого, разница видна только в одной строке стартового лога.

Мини-вывод: после старта LiteLLM первым делом ищут в логе строку про LITELLM_MASTER_KEY и пробуют шлюз мусорным ключом.

Виртуальные ключи, бюджеты и веб-интерфейс LiteLLM

Виртуальные ключи LiteLLM — это способ раздать командам доступ, не раздавая ключи провайдеров. Ключ создаётся запросом на /key/generate и несёт свои ограничения: список разрешённых моделей, max_budget в долларах, budget_duration вроде 30d, лимиты tpm_limit и rpm_limit. Расход по ключу, пользователю и команде смотрят через /key/info, /user/info и /team/info.

curl -X POST http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models":["chat-cheap"],"max_budget":5,"budget_duration":"30d","rpm_limit":60}'

Условие, которое обрывает половину первых попыток: всё это требует базы. Документация виртуальных ключей начинается с требования Need a postgres database и переменной DATABASE_URL. Без неё шлюз работает как маршрутизатор, но ключей не выдаёт, расход не хранит и в веб-интерфейс не пускает: в прогоне без базы /health/readiness честно ответил {"status":"healthy","db":"Not connected"}.

Веб-интерфейс живёт по адресу /ui и умеет добавлять модели без перезапуска, показывать расход, заводить команды и лимиты. Вход по мастер-ключу документация называет временным: этот путь stores a permanent, shared, cleartext admin credential in your environment, не ротируется и не показывает, кто из администраторов что сделал. Рекомендация документации — завести пользователя proxy_admin и выключить вход по переменным флагом disable_env_credential_login: true.

Мини-вывод: без Postgres у LiteLLM нет ни виртуальных ключей, ни бюджетов, ни входа в интерфейс.

Сколько LiteLLM добавляет к задержке

Накладные расходы шлюза LiteLLM измеряются самим шлюзом и оказываются меньше шума сети. Каждый ответ прокси несёт заголовок x-litellm-overhead-duration-ms — время внутри шлюза, отдельно от времени провайдера в x-litellm-response-duration-ms. Замер редакции: 20 вызовов подряд через прокси к gpt-4o-mini, медиана накладных расходов 1,56 мс при разбросе от 0,51 до 2,0 мс, медиана полного ответа 916,34 мс. Доля шлюза в ответе — 0,17 %.

Числа сняты на одной машине и одном провайдере, поэтому переносится способ: заголовок стоит в каждом ответе, и своя цифра снимается без профилировщика. Собственные бенчмарки проекта заявляют 8 мс на 95-м перцентиле при 1000 запросов в секунду — другая нагрузка, но тот же порядок.

Мини-вывод: цена шлюза в задержке измеряется единицами миллисекунд и считается по заголовку ответа.

Когда LiteLLM не нужен и чем его заменяют

LiteLLM избыточен, когда провайдер один и менять его не планируют: прямой SDK проще в отладке и не добавляет точку отказа. Второй случай — задача решается готовым агрегатором с единым счётом; эту роль играет OpenRouter и его аналоги, и разница между ними в том, у кого лежат ключи и промпты. Третий — задача про оркестрацию цепочек: там работают LangChain и LlamaIndex, под которыми LiteLLM встраивается нижним слоем.

Два инструмента рядом стоит назвать отдельно, потому что оба ходят в LiteLLM как в обычный OpenAI-эндпоинт: Aider CLI для правок в репозитории и Claude Code в локальном контуре. Обоим достаточно подменить base_url на адрес шлюза. Что такое сами модели за этим адресом, разобрано в материале про большие языковые модели.

Мини-вывод: LiteLLM решает задачу «много провайдеров и общий контроль», и вне этой задачи он лишний слой.

Чек-лист перед запуском LiteLLM

• Поставить litellm[proxy] и записать версию из litellm --version в репозиторий рядом с конфигом.
• Посчитать доступные имена моделей по своей версии с переменной LITELLM_LOCAL_MODEL_COST_MAP=True, иначе счёт зависит от момента импорта.
• Проверить лог старта на строку про LITELLM_MASTER_KEY и попробовать шлюз мусорным ключом.
• Поднять Postgres, если нужны виртуальные ключи, бюджеты или веб-интерфейс.
• Завести пользователя proxy_admin и выключить вход по переменным окружения.
• На Windows задать PYTHONIOENCODING=utf-8 до первого запуска.
• Снять свою цифру накладных расходов по заголовку x-litellm-overhead-duration-ms.

Как выглядит выдача по запросу «litellm что это»

Выдача Яндекса по LiteLLM почти не содержит первоисточника. Редакция сняла её 17 сентября 2026 года по пяти запросам кластера — 50 позиций, 31 домен. Официальным страницам проекта принадлежат 10 позиций из 50, причём по головному запросу «litellm что это» официальная страница одна, а документация docs.litellm.ai не появляется вовсе. Первые места держат обзоры облачных провайдеров, и каждый переписывает вендорскую цифру каталога без проверки.

Мини-вывод: по этому запросу читатель почти гарантированно попадёт на пересказ, поэтому числа стоит сверять с установленным пакетом.

Частые вопросы о LiteLLM

Что такое LiteLLM простыми словами? Прослойка, которая принимает запрос в формате OpenAI и переводит его любому провайдеру языковых моделей, возвращая ответ в том же формате. Работает библиотекой в коде и отдельным прокси-сервером для команды.

Сколько моделей поддерживает LiteLLM? В версии 1.101.0 вшитый справочник цен содержит 3816 моделей, список провайдеров — 155 записей. По умолчанию справочник скачивается при импорте, и тогда число плавает: в одном прогоне 4109 моделей в 10:30 и 4110 моделей через четырнадцать минут. Публичные цифры проекта (100+, 140+, 1800+) считаются по другим правилам и между собой не совпадают.

Как установить LiteLLM? Командой pip install 'litellm[proxy]' для Python от 3.10 до 3.14, затем litellm --config config.yaml --port 4000. Готовый образ — docker.litellm.ai/berriai/litellm:latest.

Нужна ли LiteLLM база данных? Для маршрутизации — нет, для виртуальных ключей, бюджетов и веб-интерфейса — да, нужен Postgres и переменная DATABASE_URL.

Почему LiteLLM не запускается на Windows? Стартовый баннер набран псевдографикой, и на консоли с кодовой страницей cp1251 запуск падает с UnicodeEncodeError. Помогает set PYTHONIOENCODING=utf-8 или chcp 65001 перед командой запуска.

Чем LiteLLM отличается от OpenRouter? LiteLLM разворачивается у себя и работает на своих ключах провайдеров, OpenRouter — внешний сервис с одним ключом и своим счётом. LiteLLM умеет ходить в OpenRouter как в обычного провайдера через префикс openrouter/.