LiteLLM Proxy: единый шлюз к моделям на своём сервере

LiteLLM Proxy — шлюз между приложением и API нейросетей. Приложение обращается к одному адресу, а шлюз выбирает настроенного провайдера, проверяет ключ и учитывает расход. Такой слой удобен, когда у команды несколько сервисов: каждому можно выдать свой доступ и разрешить только нужные модели.

Разберём конфигурацию с Gemini и DeepSeek, выпуск ограниченного ключа и проверку учёта. Это программный шлюз, который вы обслуживаете на своём сервере. Для покупки готового доступа у внешнего посредника у нас есть отдельное сравнение сервисов. Альтернативы OpenRouter в России.

Как проходит запрос

Путь выглядит так: приложение → LiteLLM → API провайдера → LiteLLM → приложение. В конфигурации шлюза модель получает короткое имя. Например, приложение отправляет text-fast, а LiteLLM связывает его с конкретной Gemini. Если потребуется изменить модель, можно обновить конфигурацию централизованно, сохранив имя для клиента.

Здесь есть три вида секретов. Ключи провайдеров дают шлюзу доступ к внешним моделям. Master key администрирует сам шлюз. Виртуальный ключ принадлежит приложению и ограничивает его доступ. Приложению нужен последний. Биллинг и условия провайдеров продолжают действовать для запросов через шлюз.

Что подготовить для установки

Для примера нужны установленный uv, доступ к двум API и отдельная база PostgreSQL. База требуется для виртуальных ключей и учёта. Подготовьте пользователя базы и строку подключения к ней. Если пароль содержит специальные символы, корректно закодируйте их в URL. Для установки CLI документация рекомендует следующий способ:

uv tool install 'litellm[proxy]'
litellm --version

На 9 ноября 2026 года документация указывает Python 3.10 или новее для актуальных выпусков LiteLLM. uv может подобрать совместимый интерпретатор. После проверки выбранной версии закрепите её в инструкции развёртывания команды. LiteLLM Proxy Quick Start.

Перед запуском задайте переменные окружения GEMINI_API_KEY, DEEPSEEK_API_KEY, DATABASE_URL и LITELLM_MASTER_KEY. Строка базы имеет вид postgresql://user:password@host:5432/litellm. Master key должен начинаться с sk- и содержать случайное секретное значение. Передавайте значения через защищённую конфигурацию службы. Для локального примера они должны быть доступны оболочке, из которой запускается LiteLLM.

Два провайдера в одном config.yaml

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

model_list:
  - model_name: text-fast
    litellm_params:
      model: gemini/gemini-3.8-flash
      api_key: os.environ/GEMINI_API_KEY
  - model_name: text-alt
    litellm_params:
      model: deepseek/deepseek-flash
      api_key: os.environ/DEEPSEEK_API_KEY

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

Запустите шлюз на локальном интерфейсе. В примере команды далее приведены для Bash и предполагают, что соответствующий ключ доступен в текущей оболочке.

litellm --config config.yaml --host 127.0.0.1 --port 4000

Идентификаторы моделей сверены с текущей документацией LiteLLM. Перед рабочим запуском проверьте доступность каждой модели у вашего аккаунта. Разрешённые поля запроса и особенности ответа зависят от адаптера и внешнего API. Подключение Gemini · Подключение DeepSeek.

Проверка маршрутизации

Сначала вызовите /v1/models с master key и убедитесь, что шлюз видит оба имени. Затем выполните по одному короткому запросу к каждому маршруту. В другом терминале нужно использовать тот же master key из защищённой конфигурации.

curl http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-fast",
    "messages": [{"role":"user","content":"Объясни HTTP одним предложением."}],
    "max_tokens": 128
  }'

Для второго запроса замените text-fast на text-alt. Проверьте HTTP-статус, ответ и фактического провайдера в журнале. Если один маршрут работает, а другой возвращает ошибку, сначала сверяйте его ключ и доступ к модели. Успешная загрузка YAML подтверждает структуру конфигурации, а доступ к каждому внешнему API проверяется отдельным запросом.

Выдаём ключ одному приложению

После проверки административным ключом создайте виртуальный для тестового приложения. В примере он получает доступ только к text-fast, действует семь дней и имеет бюджет $5 на заданное окно в 24 часа. Частота ограничена десятью запросами и 10 000 токенов в минуту. Это учебные значения, которые нужно подобрать под приложение.

curl http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "demo-app",
    "models": ["text-fast"],
    "duration": "7d",
    "max_budget": 5,
    "budget_duration": "24h",
    "rpm_limit": 10,
    "tpm_limit": 10000
  }'

Сохраните значение поля key из ответа в секреты приложения. Затем повторите запрос к чату уже с этим ключом. Для работы клиента достаточно адреса шлюза, имени модели и виртуального ключа. Master key оставьте административным инструментам. Требования PostgreSQL и параметры ключей приведены в документации. Virtual Keys.

Проверьте и отказ: с тем же виртуальным ключом отправьте запрос к text-alt. Он должен быть отклонён из-за списка разрешённых моделей. Такая проверка показывает, что приложение действительно работает под ограниченным доступом. Для следующего приложения выпустите другой ключ, чтобы видеть расход отдельно и иметь возможность отключить один клиент.

Как понимать бюджет и расход

duration задаёт срок действия ключа. budget_duration относится к окну бюджета. Эти поля решают разные задачи: ключ может жить неделю, а его учёт расхода сбрасываться по расписанию бюджетного окна. При отсутствии max_budget денежное ограничение для ключа по умолчанию не проверяется. После пересечения заданного бюджета документация описывает отказ новых запросов. Бюджеты и ограничения.

Проверяйте, что LiteLLM правильно распознаёт стоимость выбранной модели. Для нестандартного тарифа или собственной модели могут понадобиться заданные вручную цены. Сопоставьте короткий тест с отчётом провайдера. Если учёт показывает нулевой расход для платного запроса, сначала разберитесь с расчётом стоимости, а затем оценивайте работу бюджета.

Денежный порог зависит от состояния учёта и уже начатых обращений. При параллельной нагрузке отдельно проверьте поведение вблизи лимита. Для контроля общего счёта полезны также ограничения на стороне провайдера. Резервный маршрут и повтор запроса могут создавать дополнительный расход, поэтому их включают после базовой проверки. Ограничения API и ошибка 429.

Что смотреть в журнале

После тестов откройте учёт расходов в интерфейсе LiteLLM или соответствующий API журнала. Найдите приложение по псевдониму ключа, затем проверьте модель, время запроса, токены, стоимость и статус. Сверьте два административных теста и один запрос виртуального ключа. Период хранения и доступ к журналам настройте под правила команды. Spend Tracking.

Для запуска в команде добавьте TLS, доступ к административным маршрутам, резервирование базы и наблюдение за ошибками. Начните с одного приложения и двух явных маршрутов. Когда учёт и ограничения проверены, можно переходить к резервным моделям и балансировке. По этим данным будет видно, что меняет стоимость и задержку конкретного приложения.