Архитектура AI API Gateway: один ключ, маршрутизация моделей и отказоустойчивость

Шлюз AI API предоставляет приложению один стабильный endpoint, тогда как инфраструктура за этим endpoint может использовать несколько моделей, провайдеров, аккаунтов или регионов. Польза заключается не просто в том, чтобы скрыть несколько API-ключей за одним ключом. Польза в том, чтобы создать контролируемую точку принятия решений для каждого запроса.

Эта точка принятия решений может отвечать на операционные вопросы до того, как трафик достигнет провайдера модели:

• Разрешено ли этому клиенту вызывать запрошенную модель?
• Какой upstream сейчас удовлетворяет требованиям запроса к возможностям, задержке и стоимости?
• Достаточно ли здоров этот upstream, чтобы принимать ещё трафик?
• Можно ли безопасно повторить запрос?
• Какой fallback сохранит контракт ответа?
• Как команда позже объяснит маршрут, стоимость и сбой?

Это руководство переводит эти обязанности в производственную архитектуру. Оно также показывает, где помогает один API-ключ, где не помогает, и как мигрировать OpenAI-compatible клиента, не превращая шлюз в невидимый источник сюрпризов маршрутизации.

Референсная архитектура в одном пути запроса

Практический запрос через AI gateway проходит через пять слоёв:

1. Контракт клиента: приложение отправляет аутентифицированный запрос на один стабильный base URL.
2. Контроль допуска: шлюз проверяет идентичность, квоту, разрешения на модель, ограничения на размер payload и метаданные запроса.
3. Политика маршрутизации: policy engine преобразует запрошенную модель или capability в допустимые upstream targets.
4. Контроль выполнения: правила health, concurrency, timeout, retry, fallback и streaming определяют, как вызывается выбранный target.
5. Телеметрия и учёт: шлюз записывает выбранный маршрут, статус ответа, задержку, использование token или media и распределение стоимости.

Application / agent
        |
        |  one API key + stable request schema
        v
AI API gateway
  ├─ authentication and tenant policy
  ├─ model alias and capability registry
  ├─ routing policy and budget rules
  ├─ health, timeout, retry, and fallback controls
  └─ logs, traces, usage, and cost attribution
        |
        ├────────> Provider or deployment A
        ├────────> Provider or deployment B
        └────────> Provider or deployment C

Таким образом, шлюз одновременно является control plane и data plane. Control plane хранит политики, учётные данные, aliases, квоты и конфигурацию маршрутизации. Data plane обрабатывает живые запросы, потоковые ответы, повторы и телеметрию. Концептуальное разделение этих обязанностей делает изменения безопаснее: операторы могут обновлять политику маршрутизации, не заставляя каждую команду приложения выпускать новый клиентский код.

Что должно означать «один ключ»

«Один ключ» должен означать один контракт учётных данных на стороне приложения, а не один credential, общий для каждого человека, сервиса и окружения.

Хорошая архитектура выдаёт отдельные gateway credentials для production, staging, local development, CI и независимых workloads. Каждый ключ должен иметь узкую область действия, владельца, квоту и путь отзыва. Затем шлюз хранит учётные данные провайдера на стороне сервера и сопоставляет входящую идентичность с upstream credentials, которые ему разрешено использовать.

Это создаёт полезную границу безопасности:

Ключ gateway никогда не следует рассматривать как повод ослаблять гигиену ключей. Храните его в секрет-менеджере, никогда не помещайте в код браузера или публичный репозиторий, регулярно ротируйте его и разделяйте по окружениям. Более подробный операционный чек-лист см. в статье secure API key management for AI products.

Алиасы моделей отделяют контракт клиента от провайдеров

Первая абстракция маршрутизации — это alias модели. Вместо жесткого кодирования идентификатора модели, специфичного для провайдера, по всему приложению клиент запрашивает стабильное имя, например:

support-fast
reasoning-high
code-review-default
image-generation-standard

Реестр, стоящий за каждым alias, определяет контракт возможностей. Текстовый alias может задавать вызов инструментов, структурированный вывод, минимальный размер контекста, поддержку streaming и утвержденное семейство fallback. Для image- или video-alias нужны другие поля, такие как допустимые типы входных данных, размеры выходного изображения, поведение асинхронных задач и ограничения безопасности.

Alias не должен обещать, что каждая кандидатная модель ведет себя одинаково. Он должен определять минимальное поведение, на которое приложение может опираться.

alias: support-fast
contract:
  modality: text
  streaming: true
  tools: optional
  structured_output: required
  maximum_latency_ms: 3500
routes:
  - target: provider-a/model-fast
    priority: 1
  - target: provider-b/model-balanced
    priority: 2

Именно эта косвенность делает стабильный base URL ценным. Приложения интегрируются с контрактом alias; владельцы платформы могут изменить набор целей после оценки, инцидента у провайдера, изменения цен или регионального требования.

Решение о маршрутизации должно быть явным

Маршрутизация в production обычно сочетает жесткие фильтры и мягкое ранжирование.

1. Примените жесткие фильтры допустимости

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

• Требуемая модальность и тип входных данных
• Требование к окну контекста или размеру вывода
• Поддержка вызова инструментов или структурированного вывода
• Резидентность данных или региональная доступность
• Allowlist арендатора или проекта
• Политика безопасности или соответствия требованиям
• Текущее состояние квоты, rate-limit или concurrency
• Совместимость со streaming

Цель, которая не проходит жесткое требование, никогда не должна выигрывать только потому, что она дешевле.

2. Ранжируйте допустимые цели

После фильтрации оцените оставшиеся маршруты. Простая политика может быть проще в эксплуатации, чем непрозрачный оптимизатор:

route score =
  quality_weight × evaluation_score
  - latency_weight × predicted_latency
  - cost_weight × estimated_cost
  - risk_weight × recent_error_rate

Весы должны различаться в зависимости от нагрузки. Интерактивный чат может отдавать приоритет времени до первого токена. Ночной job для извлечения данных может отдавать приоритет стоимости за успешно сформированную структурированную запись. Кодирующий агент может ценить надежность инструментов и поведение на длинном контексте выше, чем небольшую разницу в цене.

3. Записать причину

Каждое решение маршрутизации должно порождать машиночитаемые метаданные, например:

{
  "requested_alias": "support-fast",
  "selected_target": "provider-a/model-fast",
  "policy_version": "support-fast-2026-07-29.3",
  "selection_reason": "healthy_primary_within_latency_budget",
  "fallback_count": 0
}

Если команда не может восстановить, почему был выбран маршрут, она не сможет отлаживать дрейф стоимости, деградацию качества или инциденты у провайдера.

Проверки состояния требуют большего, чем HTTP 200

Вышестоящий сервис может успешно отвечать на health-проверки, но при этом не справляться с реальным трафиком модели. Поэтому health для AI gateway должен включать несколько сигналов:

• Состояние транспорта: сбои соединения, ошибки TLS, ошибки DNS и таймауты вышестоящего сервиса
• Состояние API: ответы об ограничении частоты запросов, ошибки аутентификации, ошибки провайдера и некорректные ответы
• Состояние модели: пустой вывод, некорректный структурированный вывод, сломанные вызовы инструментов или несовместимые чанки стриминга
• Состояние производительности: время до первого токена, общая задержка, время в очереди и пропускная способность
• Состояние емкости: количество одновременных запросов, давление по токенам в минуту, баланс аккаунта или квота развертывания

Используйте скользящее окно, а не единичный сбой. Circuit breaker может временно удалить target после превышения порога ошибок или задержки, а затем разрешить ограниченные проверки перед восстановлением полного трафика. Обнаружение выбросов также может исключить одно нездоровое развертывание, оставив доступными здоровые развертывания того же провайдера.

Этот принцип хорошо известен в инфраструктуре gateway и service mesh: retries, circuit breaking и outlier detection — это отдельные механизмы, и каждому нужна ограниченная политика. Envoy документирует эти механизмы отдельно в своих руководствах по HTTP retries, circuit breaking и outlier detection.

Повторяйте запрос только если он безопасен

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

Для нестримингового текстового completion, который завершился сбоем до того, как пришли какие-либо байты ответа, один повтор к тому же target может быть разумным. Для запроса, который запускает инструмент, стартует задачу на изображение или видео, списывает средства с внешнего аккаунта или уже начал стримить частичный вывод, слепой повтор может создать дубликаты или испортить пользовательский опыт.

Определяйте право на retry с помощью трех вопросов:

1. Был ли запрос принят upstream? Сбой соединения до принятия отличается от тайм-аута после того, как провайдер начал работу.
2. Дошёл ли какой-либо вывод до клиента? Как только начинается потоковая передача, переключение провайдеров может привести к разрывному ответу.
3. Есть ли ключ идемпотентности или запись дедупликации? Долгоживущие медиа- и агентные workflows требуют стабильной идентичности операции.

Консервативная матрица повторных попыток выглядит так:

Сохраняйте один end-to-end дедлайн. Если клиент допускает восемь секунд, gateway не может потратить семь секунд на primary, а затем дать fallback ещё восемь. Каждая попытка расходует тот же бюджет запроса.

Fallback должны сохранять контракт

Fallback — это не просто «попробовать другую модель». Это соглашение о том, что может измениться, когда основной маршрут выходит из строя.

Определяйте fallback на трёх уровнях:

1. Та же модель, но другое развёртывание или аккаунт: самый низкий поведенческий риск; полезно при сбоях квоты или региона.
2. Эквивалентное семейство моделей: умеренный риск; требует regression-тестов для схемы, tools, safety и стиля вывода.
3. Пониженная способность: самый высокий риск; может отключать tools, уменьшать контекст или возвращать queued-ответ вместо live-ответа.

Для каждого alias документируйте:

• Какие классы сбоев запускают fallback
• Какие targets совместимы по контракту
• Сообщается ли клиенту о том, что произошёл fallback
• Максимальное число попыток и общий дедлайн
• Как измеряются изменения качества и стоимости
• Можно ли кэшировать или воспроизводить ответ

Региональный доступ провайдера добавляет ещё одно измерение. Провайдер или модель могут быть доступны в одной географии, типе аккаунта или коммерческом соглашении и недоступны в другой. Региональная маршрутизация провайдеров LLM объясняет отдельные проверки доступа, политики и failover, необходимые для таких маршрутов.

Streaming — часть контракта gateway

OpenAI-compatible формы запросов могут упростить миграцию клиента, но совместимость streaming требует осознанного преобразования. Gateway должен сохранять порядок событий, причины завершения, метаданные использования, фрагменты вызовов tools, сигнализацию ошибок и отмену соединения.

Прежде чем направлять две модели за одним streaming alias, протестируйте:

• Время до первого события и поведение heartbeat
• Формат инкрементального текстового delta
• Сбор аргументов tool-call
• Передача сведений об использовании в финальном событии
• Передача отмены со стороны клиента
• Поведение таймаута до и после первого события
• Формат ошибки после того, как заголовки уже были отправлены

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

Наблюдаемость связывает маршрутизацию с результатами

Панели управления gateway полезны, но для диагностики в production требуется структурированная телеметрия, которая может связать запрос к модели с окружающим трассировочным следом приложения.

Как минимум фиксируйте:

По умолчанию избегайте логирования сырых промптов и выводов. Записывайте содержимое только тогда, когда это допускают сценарий использования, политика хранения и ожидания пользователя. Проект OpenTelemetry поддерживает развивающиеся семантические соглашения для генеративных ИИ-систем, которые помогают командам использовать единообразные имена span и метрик, а не придумывать отдельную схему для каждого провайдера.

Контроль затрат должен быть до вызова upstream

Отчеты о расходах задним числом не могут предотвратить инцидент. Политика admission и маршрутизации должна оценивать стоимость до отправки трафика.

Полезные механизмы контроля включают:

• Жесткие квоты на уровне ключа и проекта
• Мягкие уведомления о превышении бюджета
• Максимальное количество входных или выходных единиц
• Allowlist моделей по среде
• Маршрутизация с учетом стоимости для гибких нагрузок
• Политика кэша для повторяемых запросов
• Ограничения параллелизма для дорогих медиазадач
• Аварийные выключатели для модели, провайдера, tenant или маршрута

Движку маршрутизации нужна версионированная таблица цен и согласованный слой нормализации использования. Иначе политика «самая дешевая модель» может сравнивать несовместимые единицы или устаревшие цены. О фреймворке, который разделяет тарифы провайдеров, плату платформы и операционные механизмы контроля, см. ценообразование AI gateway.

Минимальная миграция с совместимостью OpenAI

Наименьшее изменение для клиента обычно заключается в новом API key, base URL и имени модели. При использовании gateway, совместимого с OpenAI, код приложения может сохранить ту же клиентскую библиотеку:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="your-model-or-alias",
    messages=[
        {"role": "user", "content": "Кратко изложите этот отчет об инциденте."}
    ],
)

Это изменение кода — самая простая часть. Безопасная миграция состоит из четырех этапов:

1. Инвентаризируйте текущий контракт. Зафиксируйте модели, параметры, потоковую передачу, инструменты, схемы, тайм-ауты и обработку ошибок.
2. Запустите теневые или офлайн-оценки. Сравните качество вывода, корректность схемы, задержку и стоимость на репрезентативных запросах.
3. Проведите канареечный запуск одной нагрузки. Начните с ограниченного процента трафика и немедленного пути отката.
4. Включайте функции маршрутизации по отдельности. Сначала измените endpoint, затем добавьте алиасы, затем отказоустойчивость на основе состояния здоровья, а затем оптимизацию по стоимости или качеству.

Разделение этих изменений делает инциденты диагностируемыми. Если миграция endpoint, замена модели, политика повторных попыток и оптимизатор стоимости запускаются одновременно, команда не поймет, какой именно параметр вызвал регрессию. Flatkey integration starter подробнее описывает шаблон миграции base URL.

Чек-лист готовности к production

Используйте этот чек-лист, прежде чем считать gateway общей инфраструктурой.

Контракт клиента

• Стабильный base URL и версионированная схема запроса
• Именованные алиасы с документированными минимальными возможностями
• Единообразная оболочка ошибок и идентификаторы запросов
• Протестированные потоковая передача, вызовы инструментов и структурированный вывод

Идентификация и безопасность

• Отдельные ключи для каждого сервиса и окружения
• Учетные данные провайдера на стороне сервера
• Области действия ключей, квоты, ротация и отзыв
• Логирование prompt и response отключено или явно регулируется

Маршрутизация и надежность

• Жесткие фильтры допустимости перед ранжированием по стоимости
• Версионированные политики маршрутизации и данные о ценах
• Состояние здоровья на основе реального поведения запросов
• Ограниченные повторные попытки с одним сквозным дедлайном
• Цели резервного перехода, совместимые по контракту
• Circuit breaker и проверочные запросы на восстановление

Эксплуатация

• Телеметрия причины маршрута, ошибки провайдера, задержки и использования
• Оповещения о частоте fallback, частоте ошибок, дрейфе стоимости и давлении квот
• Kill switch для каждого модели и каждого маршрута
• Runbook для сбоя провайдера и сбоя gateway
• Прямой или альтернативный аварийный путь для критически важных нагрузок

Как Flatkey вписывается в эту архитектуру

Flatkey предоставляет один API-ключ, один совместимый с OpenAI base URL и одну панель управления для доступа к поддерживаемым моделям, использования и биллинга. Его router создан для сокращения отдельных аккаунтов у провайдеров и фрагментированных путей интеграции, при этом поддерживая переключение upstream и балансировку нагрузки.

Для команды приложения архитектурное преимущество заключается в стабильной клиентской границе: направьте OpenAI-совместимый клиент на https://router.flatkey.ai/v1, выберите поддерживаемую модель и оставьте доступ к моделям за тем же endpoint шлюза. Командам по-прежнему следует определять собственные контракты на уровне приложения, пороги оценки, области действия ключей, бюджеты отказов и ожидания по fallback.

Лучшая архитектура шлюза не делает маршрутизацию невидимой. Она делает маршрутизацию изменяемой, ограниченной и объяснимой.

FAQ

Что такое AI API gateway?

AI API gateway — это промежуточный слой между приложениями и провайдерами моделей. Он централизует аутентификацию, доступ к моделям, маршрутизацию, управление надежностью, отслеживание использования и политики, при этом предоставляя стабильный API для клиентских приложений.

Означает ли один API-ключ, что все сервисы используют один и тот же ключ?

Нет. Это означает, что приложения используют учетные данные, выданные gateway, вместо прямой обработки учетных данных каждого провайдера. Продакшн-сервисы, окружения и команды по-прежнему должны получать отдельные ключи с ограниченными правами.

Что такое маршрутизация моделей?

Маршрутизация моделей — это процесс фильтрации подходящих моделей или развертываний и выбора целевого варианта в соответствии с возможностями, политикой, состоянием, задержкой, качеством, стоимостью, регионом или емкостью.

Какая стратегия fallback является самой безопасной?

Начинайте с той же модели в другом исправном развертывании или учетной записи. Межмодельный fallback следует использовать только после тестов, показывающих, что альтернативный целевой вариант сохраняет схему, инструменты, потоковую передачу, безопасность и контракт качества приложения.

Может ли gateway повторно попытаться обработать потоковый ответ на другой модели?

Обычно нет, если вывод уже дошел до клиента. Переключение в середине потока может объединить несовместимые частичные ответы. Используйте понятную ошибку потока, если только клиент и gateway не реализуют явный протокол возобновления.

Достаточно ли OpenAI-совместимого API для миграции без изменений?

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