LiteLLM Proxy — это сервер, который ваша команда разворачивает у себя и превращает в единую точку входа к нескольким языковым моделям: сервисы обращаются к нему по OpenAI-совместимому адресу, а он направляет вызов нужному поставщику. Взамен россыпи ключей по скриптам появляются виртуальные ключи с лимитами, общий журнал расхода и запасная модель на случай сбоя. Шлюз раздаёт доступ и записывает, кто, куда и сколько обращался, а смысл ответов и решения остаются за моделью, людьми и серверами приложений. Вариант оправдан, когда моделей и потребителей уже несколько; для одного скрипта с одной моделью шлюз добавит лишнюю сущность.
Зачем нужен шлюз
По описанию в документации, LiteLLM Proxy даёт единый интерфейс к более чем сотне моделей, виртуальные ключи с бюджетами и лимитами, учёт расхода и маршрутизацию с резервом.
Типичная картина в команде выглядит так: у аналитика ключ в блокноте, у разработчика другой ключ в переменной окружения, у бота третий в конфигурации контейнера. Расход собрать невозможно, отозвать доступ сотруднику после его ухода сложно, а смена поставщика требует правок в каждом сервисе. Шлюз собирает эти точки в одну: сервисы получают адрес шлюза и свой виртуальный ключ, а настоящие ключи поставщиков хранятся только в конфигурации шлюза.
Шлюз подходит для моделей, к которым у компании есть прямой законный доступ, и для собственных открытых весов на своём сервере; организацию такого сервера разбирает статья про выбор между vLLM и Ollama. Доступность отдельных зарубежных поставщиков из вашей страны проверяйте по их условиям: шлюз только маршрутизирует вызовы и доступ к поставщику создать бессилен.
Ещё одно преимущество: смена поставщика или модели превращается в правку одной строки в конфигурации, после которой запускают тестовый набор и смотрят на расхождения. Принцип разделения труда сохраняется: шлюз считает и ограничивает, модель отвечает, человек проверяет итог, а права на запись в бизнес-системах проверяет сервер приложения. Включение шлюза сохраняет эти слои и делает их наблюдаемыми.
Файл config.yaml
Основа настройки — файл config.yaml со списком model_list. В каждой записи есть имя, под которым сервисы будут обращаться к модели, и параметры вызова поставщика. Такое внутреннее имя разумно делать смысловым, например «черновик-ответа» или «быстрая-классификация»: смена модели за этим именем обойдётся без правок в сервисах.
- Список моделей с внутренними именами и параметрами поставщиков, секреты берутся из переменных окружения.
- Мастер-ключ администратора: по документации, значение начинается с префикса sk- и задаётся в окружении или в разделе общих настроек.
- База PostgreSQL для хранения виртуальных ключей и расхода: без неё ключи и учёт останутся без работы.
- Настройки резерва, повторов и таймаутов в разделе настроек шлюза.
Мастер-ключ нужен только администраторам. Прикладные сервисы получают виртуальные ключи, а мастер-ключ хранится в менеджере секретов и в журналах отсутствует. Настройки лучше держать в репозитории без секретов и менять через запрос на слияние: каждая правка видна, у каждой есть автор.
Ключи и лимиты
Виртуальный ключ создают запросом /key/generate, авторизуясь мастер-ключом. В запросе перечисляют доступные модели и ограничения; метаданные позволяют записать, чей это ключ и для какой задачи. Сервисы подключаются к шлюзу как к обычному OpenAI-совместимому адресу, подставляя виртуальный ключ в заголовок.
| Параметр | Что задаёт | Зачем команде |
|---|---|---|
| models | Список доступных моделей | Бот поддержки получает лёгкую модель, аналитик любую из нужных |
| max_budget | Предел расхода по ключу | Скрипт с ошибкой в цикле упирается в потолок |
| rpm_limit и tpm_limit | Запросы и токены в минуту | Один сервис ограничен и оставляет канал остальным |
| duration | Срок жизни ключа | Временный доступ подрядчику закрывается сам |
| team_id и user_id | Принадлежность ключа | Расход раскладывается по командам и людям |
Отключение ключа выполняется запросами блокировки и разблокировки с мастер-ключом, а расход по ключу доступен через запрос информации о ключе. Для сотрудника, покидающего команду, достаточно заблокировать его ключ: настоящие ключи поставщиков остались у шлюза и менять их нет нужды. Связанные принципы выдачи и отзыва прав описаны в статье про права, секреты и проверку.
Размеры лимитов определяйте по журналу первой недели работы, догадки тут вредны: сначала поставьте щедрые значения, затем сузьте до реальной нагрузки с небольшим запасом. Для каждого лимита назначьте владельца: именно он получает уведомление, когда сервис упёрся в потолок, и решает, поднять предел или чинить сам сервис.
Журнал и резерв
Журнал шлюза отвечает на три вопроса: кто обращался, к какой модели и сколько токенов потрачено. Эти данные ложатся в базу, и руководитель команды видит расход по людям и задачам. Для разбора качества ответов нужен отдельный инструмент трассировки, например описанный в материале про Langfuse; шлюз отвечает за доступ и учёт, а оценка текстов лежит на другом инструменте.
Содержимое запросов в журнале шлюза хранят лишь при необходимости. Заведите правило: персональные данные и тексты клиентских документов в журналах отсутствуют, а в записи остаются идентификатор вызова, ключ, модель и число токенов.
Резерв настраивается в разделе настроек шлюза. Документация показывает список вида «основная модель — запасные», число повторов перед переходом на запасную, таймаут запроса и паузу для модели после серии сбоев. Запасная модель обязана пройти тот же тестовый набор: ответ, приемлемый от первой модели, от второй может оказаться хуже. Если запасной вариант работает у другого поставщика, проверьте для него отдельно политику хранения данных.
Сколько сервисов и людей у вас уже обращается к моделям?
Проверка перед запуском
Первый прогон проводите на вымышленных запросах. Создайте ключ с одной моделью, отправьте вызов на шлюз и убедитесь, что запрос дошёл, ответ вернулся, а расход записан в базе. Затем нарочно превысьте лимит и проверьте, что шлюз отвечает отказом, после чего заблокируйте ключ и проверьте отказ в доступе. Наконец отключите основную модель и убедитесь, что запрос ушёл в запасную.
Шлюз сам становится критичным узлом: его падение останавливает все сервисы. Опишите, что будет при отказе: запасной экземпляр, мониторинг, ручной режим для критичных процессов. Доступ к самому шлюзу закройте от внешней сети, а административный интерфейс отдайте узкой группе.
Контрольный список запуска: у каждого сервиса свой ключ с ограничением по моделям, у каждого ключа указан владелец, лимиты заданы, журнал читается раз в неделю, резервный маршрут проверен вручную, мастер-ключ лежит в хранилище секретов. Отметка по каждому пункту ставится после проверки, а запись о проверке сохраняется рядом с настройками. Пилот можно предложить на одной команде и двух-трёх сервисах: ключи, лимиты, журнал и один резервный маршрут. После недели работы сравните журнал с ожиданиями и решите, какие сервисы переводить следующими.
Выпишите всех потребителей моделей в компании: сервисы, скрипты, ботов и людей с ключами. Сверьте список с реальным расходом, запустите шлюз на тестовом контуре и переведите туда один сервис. Если нужен проект с ключами, лимитами и приёмкой, обсудите с нами ИИ-консалтинг для вашей команды; состав работ определим после разбора текущей схемы.