LLM Gateway для AI API: единый слой ключей, routing, лимитов и fallback

Что такое LLM Gateway и какую проблему он решает

Когда каждое приложение напрямую подключается к AI API, ключи, retries, тарифы, форматы логов и ограничения размножаются по кодовой базе. Замена модели требует правок в нескольких сервисах, а общий расход обнаруживается только в счетах провайдеров.

LLM Gateway - промежуточный data-plane слой, через который приложения вызывают разрешённые модели. Он применяет общие политики до запроса и собирает единый trace после ответа. Это не ещё один чат-бот и не место для всей бизнес-логики.

Когда шлюз нужен, а когда станет лишней сложностью

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

Архитектура: control plane и data plane

Data plane обрабатывает каждый запрос: проверяет identity, лимиты и policy, выбирает route, вызывает backend и пишет минимальный trace. Control plane хранит aliases, разрешённые модели, тарифы, квоты и правила rollout. Их разделение позволяет менять конфигурацию с review и не перегружать горячий путь.

Контракт запроса: нормализуйте только общее

Унифицированный endpoint полезен для общих полей: messages, model alias, deadline, metadata и ожидаемый тип результата. Но нельзя свести все API к наименьшему общему знаменателю: tool calling, reasoning controls, multimodal parts, caching и structured output различаются.

request_id: UUID
model_alias: support.default
messages: typed array
response_contract: schema_id
deadline_ms: integer
tenant_id: trusted identity claim
data_class: public | internal | restricted
capabilities_required: [tools, json_schema]
metadata: allowlisted key/value
provider_options: validated namespaced object

Провайдерские расширения помещайте в namespaced-поле и валидируйте allowlist. Не пропускайте произвольные параметры без контроля.

Model aliases вместо имён моделей в приложениях

Приложение должно просить не конкретную версию, а подтверждённую способность: support.default, document.extract.strict или research.long-context. Alias разрешается в immutable конфигурацию с моделью, region, параметрами и fallback.

Capability contract защищает от ложной переносимости

Одинаковый формат HTTP не означает одинаковое поведение. Перед route gateway сопоставляет требования запроса с подтверждёнными возможностями backend.

Аутентификация: приложение не должно знать ключ провайдера

Клиент аутентифицируется перед gateway своей workload identity. Gateway получает provider credentials из secret manager и выдаёт их только адаптеру на время вызова. По возможности используйте короткоживущие credentials или managed identity.

• Запрещайте API-ключи в браузере и мобильном пакете.
• Разделяйте production, staging и локальную разработку.
• Ограничивайте секрет по провайдеру и проекту.
• Ротируйте ключ без deploy приложений.
• Маскируйте authorization headers в логах и ошибках.
• Ведите аудит чтения и изменения secrets.

Gateway уменьшает площадь распространения секретов, но становится привилегированным компонентом и требует более строгого контроля.

Tenant isolation, token quotas и rate limits

Лимит запросов не отражает нагрузку: один вызов может содержать короткую классификацию, другой - большой документ. Поэтому сочетайте requests per minute, tokens per minute, периодическую token quota и hard budget.

Для consumer [идентификатор] задай:
- разрешённые model aliases;
- requests и tokens per minute;
- дневную и месячную quota;
- максимальный input/output на запрос;
- допустимый cost class;
- concurrency limit;
- поведение: reject, queue или downgrade;
- alert thresholds и owner.
Не доверяй tenant_id из пользовательского тела - бери его из проверенной identity.

Microsoft документирует token-limit policies и квоты по ключу потребителя в Azure API Management. Реализация зависит от платформы, но принцип одинаков: один клиент не должен исчерпать общий backend quota.

Routing: правила должны быть объяснимыми и версионируемыми

Route выбирается по alias, обязательным capabilities, data class, региону, доступности, latency SLO и бюджету. Качество должно быть доказано eval-набором. Случайный выбор самой дешёвой доступной модели опасен.

Load balancing и sticky sessions

Несколько deployment одной совместимой модели можно балансировать по доступной квоте, latency или приоритету. Но диалоговые API иногда хранят provider-side state. Тогда запросы одной сессии должны попадать в совместимый backend либо приложение должно хранить переносимое состояние самостоятельно.

Fallback: только между протестированными эквивалентами

Fallback повышает доступность, но может изменить качество, формат, стоимость и юрисдикцию обработки данных. Цепочка задаётся заранее для alias и активируется только по классифицированным временным ошибкам.

Retries, circuit breaker и защита от каскадного сбоя

Gateway не должен умножать retries приложений. Определите единственного владельца повторов. Для 429 и временных 5xx применяйте ограниченный exponential backoff с jitter и учитывайте Retry-After. Permanent errors не повторяйте.

• Общий max attempts на запрос, включая fallback.
• Deadline передаётся вниз и уменьшается.
• Circuit breaker исключает больной backend.
• Bulkhead разделяет критический и фоновый трафик.
• Queue имеет предел и политику устаревания.
• Tool calls защищены идемпотентностью.
• Partial response не маскируется как полный успех.

Логи и traces без утечки пользовательских данных

Полный prompt удобен для отладки, но создаёт вторую базу конфиденциальных данных. По умолчанию пишите metadata и usage: trace ID, alias, route, версии, токены, latency, статус, retry и стоимость. Содержимое включайте только по разрешённой политике с редактированием и сроком хранения.

Cloudflare AI Gateway, например, документирует analytics, logging, caching, rate limiting, retries и fallback; перед использованием изучите актуальные настройки хранения логов.

Кэширование в gateway: exact прежде semantic

Exact cache по нормализованному запросу, версии alias, prompt, модели и policy предсказуем. Semantic cache переиспользует ответ для похожего запроса и несёт риск вернуть неверный или чужой результат. Его нельзя включать глобально одной кнопкой.

Безопасность: gateway - policy enforcement point, не единственная защита

На шлюзе удобно применять allowlist моделей, ограничения данных, максимальный размер, content policy и DLP. Но prompt injection внутри retrieved документа требует защиты в самом приложении и tool layer. Gateway не знает бизнес-смысл каждого действия.

• Разделяйте instructions и untrusted content.
• Проверяйте URL, тип и размер загружаемого файла.
• Ограничивайте egress и доступные tools.
• Применяйте output validation до действия.
• Требуйте approval для необратимых операций.
• Тестируйте обход policy через encoding и multimodal input.

Gateway не должен стать единой точкой отказа

Шлюз находится в критическом пути, поэтому ему нужны multi-zone deployment, health checks, autoscaling, bounded queues и отдельные лимиты зависимостей. Конфигурация должна кэшироваться локально с безопасной последней версией.

Составь chaos-план для LLM Gateway:
1. недоступен primary provider;
2. 429 и исчерпана quota;
3. control plane недоступен;
4. telemetry backend тормозит;
5. secret rotation в процессе;
6. config содержит ошибочный route;
7. резкий рост длинных запросов.
Для каждого укажи ожидаемую деградацию, SLO, circuit breaker, fallback, защиту данных, алерт, rollback и доказательство восстановления.

Build или buy: собственный gateway, облачный сервис или open source

Выбирайте по требованиям к данным, SLO, масштабу команды и стоимости владения. Возможности и тарифы уточняйте на сайтах конкретных решений.

Пошаговая миграция без остановки приложений

Набор тестов перед production

Unit-тестов адаптера недостаточно. Нужны contract tests на каждого provider, replay обезличенного eval-набора, нагрузочные испытания и проверка деградации.

Отдельно проверьте отмену streaming-запроса, двойную отправку, частичный ответ, несовместимый fallback и недоступность telemetry.

Итоговый production-чек-лист

Хороший LLM Gateway делает решения видимыми и управляемыми. Он не скрывает различия моделей, а превращает их в явные контракты и проверяемые политики.