Если вы пользуетесь API моделей, то могли столкнуться с вопросом — прямой вызов API через OpenAI-совместимый шлюз или создать свою прослойку? Если у вас один агент или один разработчик — то тут, понятное дело, лучше не городить лишний шлюз.
Но если система больше? Сотрудников несколько, нужен сбор статистики, аккаунты, валидация или ограничения — то тут уже стоит задуматься о создании своего шлюза поверх провайдера. Эта некая прослойка между вашим кодом и API провайдера, которая держит ключи, решает, куда и с какой моделью уйдёт запрос, повторяет упавшие вызовы, считает токены и деньги, а заодно пишет логи так, чтобы через месяц можно было разобраться, что вообще произошло.
Звучит солидно. Так ли это — мы узнаем в этой статье. Я расскажу о том, какие фичи может принести свой шлюз, какие ограничения создаст, и как сделать всё это эффективно. Код тут будет второстепенный, примеры будут приведены на Python.
В этой статье мы узнаем, почему в половине случаев шлюз вообще не нужен и чем это оправдано, в какой момент он становится обязательным, и как выглядит тонкий слой на FastAPI с Pydantic, если вы всё-таки решились.
О шлюзах
BotHub уже говорит на языке OpenAI — эндпоинт https://openai.bothub.chat/v1 работает с официальным SDK после банальной замены base_url, так что адаптер протокола писать не придётся (и слава богу, потому что это самая скучная часть работы). Есть Chat Completions, есть Responses API, а для медиамоделей второй шлюз в формате Replicate — на случай, если ваш продукт умеет не только в текст.
Но вот это — всего лишь сырая шахта. Иногда ресурсы можно продавать просто так — но иногда хочется пооперировать логистикой. Поэтому дополнительные шлюзы и создают, дабы управлять ключами, маршрутами, пользователями, бюджетом и учётом токен-экономики.
Но прежде чем создавать веб-приложение и писать роуты, стоит вычислить, нужен ли вам шлюз, изучить функциональные и нефункциональные требования. Я-то сам люблю создавать свои прослойки, но иногда можно поставить желание выше потребностей и увеличить затраты на проект с пустого места. Жалко ведь.
Если API дергает сугубо один сервис (и вы не планируете расширяться), разработчик один-два, и главная фича одна — шлюз добавляет лишний этап, лишний контейнер для деплоя и лишнюю точку отказа. Также стоит учитывать, что шлюз надо проектировать с замахом на абстрагирование провайдера. Абстракция провайдеров — весомый аргумент в пользу шлюза, когда вам нужно иметь несколько провайдеров для фоллбэка или для разных задач. Кроме того, хочу отметить, что шлюз может заниматься не только прямой работой с ИИ — но и приведением данных в порядок. Например, шлюз посвящён линтингу, тестам и код-ревью, и помимо ИИ-ревью, прогонять сами линтеры, и их результат прикреплять уже к запросам к LLM-провайдеру.
Раз мы затронули тему фоллбеков, то важно спросить себя, а какой эффект будет, если вдруг провайдер упадёт? Это будет неудобство, которое можно нивелировать плавной деградацией (так называемой graceful degradation), или настоящий инцидент? Если падение провайдера будет громким инцидентом, или нужна настройка плавной деградации более абстрактно и поверх сервисов — то нужно присмотреться к разработке проекта.
А когда вы присмотрелись, то стоит сразу обозначить — вы можете назвать конкретную фичу, которая тратит больше всех? Атрибуция — чуть ни главная причина в том, чтобы взять полноценный шлюз. И после того как вы ответили, поймите масштаб разработки. Может вам хватит одной таблицы и middleware, а не полноценный новый элемент цепочки.
Как и любые добавления элемента в цепочку на этапе планирования — шлюз кажется обманчиво лёгок на старте, но дорого на финише. Семантика ретраев и бэкоффов, учёт токенов с учётом инвойса, инвалидация кэша и наблюдаемости — всё это вещи важные.
Какие проблемы могут быть без шлюза?
Про то, почему не стоит заводить шлюз, мы уже поговорили. Но давайте подробнее разберём некоторые кейсы, наглядно показывающие, что может ломаться без шлюза. Список фич можно перечислять лет 500, но я попытался выделить основные.
Например, разобщённость. В частности — когда ключ живёт, например, в 4 местах, где-то он лежит в .env, где-то задаётся в другом месте. Если есть несколько сервисов, оперирующие ИИ — то чтобы поменять провайдер, придётся менять все сервисы. Это конечно, не так сложно, но муторно и вы легко можете что-то забыть. А ещё вы можете иногда забыть обезопасить .env и в итоге вам безопасники популярно объяснят, почему так делать нельзя.
Ещё стоит помнить, что повторная попытка может умножать счёт — чаще всего при 429 или 500 многие пишут try/except с ретрайем. Но иногда это приводит к тому, что при стриминге повторная попытка после частично полученного ответа может стоить дважды, ибо провайдер уже сгенерировал токены, и вы за них заплатили.
А ещё так называемый circuit breaker должен срабатывать на «провайдер деградировал», тогда как «функция упала» — это совсем другой сценарий, и путать их не стоит. По факту LLM-шлюз — это в первую очередь обработка отказа на одном пути запроса: таймауты, circuit breaker, идемпотентные ключи, лимиты.
А ещё есть стриминг — он может ломать наивный способ учёта. Используемые токены оцениваются часто по примерным формулам. Если вы строите свой шлюз, решение о том, как считать стоимость стримингового запроса, придётся принять явно. Резервировать до запроса, оценивать после, брать usage из последнего чанка — у каждого варианта свои компромиссы.
Давайте попробуем подвести и суммаризировать причины. Разберём в таблице:
Группа
Фича
Строить самому?
Почему
Доступ
Виртуальные ключи, скоупинг по команде/фиче, RBAC
Да, если нужна интеграция с вашим IAM
Готовые шлюзы дают ключи, но не вашу модель тенантов
Надёжность
Fallback между провайдерами, circuit breaker, таймауты
Скорее готовое
Это стандартные паттерны, и их много раз реализовывали; своя реализация оправдана только особым сценарием (например, shadow routing)
Маршрутизация
Выбор модели по стоимости, латентности, сложности запроса
Готовое + тонкая настройка
Cost-based и latency-based routing уже есть в LiteLLM, Bifrost, Hyperion
Кэш
Exact-match и семантический кэш
Готовое, если нет особой логики инвалидации
Семантический кэш требует embeddings и векторного хранилища — это инфраструктура
Безопасность
PII-редакция, prompt-injection guardrails
Да, если политики специфичны
Готовые guardrails есть, но ваши правила редакции почти всегда уникальны
Наблюдаемость
per-request trace ID, latency, token usage, cost attribution
Да, под вашу систему метрик
Шлюз — естественная точка, где появляется request_id, которого нет ни в приложении, ни у провайдера
Бюджеты
Hard/soft cap на команду, прогноз перерасхода
Готовое, если нет иерархии бюджетов
Hyperion и Portkey дают бюджеты, но не вашу оргструктуру
Стриминг
Нормализация SSE, учёт отмены
Да, если стриминг — ключевой UX
Отмена стриминга — отдельная проблема: пользователь закрыл вкладку, а запрос уже оплачен
Собственный шлюз полезно строить там, где фича должна знать что-то о бизнес-требованиях. Примечательно, что даже в опенсорсных шлюзах, которые позиционируются как «всё в одном», наборы фич заметно различаются: у Bifrost из коробки нет auth, keys и limits, а LiteLLM, наоборот, закрывает бюджеты и виртуальные ключи, но добавляет 18 мс на запрос и держит 55 rps на воркер, тогда как Bifrost укладывается в 1.2 мс и 970 rps. Но тема готовых шлюзов — эта тема для другой статьи, в этой мы говорим о разработке своего шлюза.
Доступ: виртуальные ключи и RBAC
Виртуальные ключи — это, пожалуй, самая очевидная фича, с которой начинают почти все. Приложение получает ключ шлюза, реальный ключ BotHub остаётся внутри, и когда нужно отозвать доступ у одной фичи, вы отзываете её виртуальный ключ, не трогая остальные. Более того, ключ можно привязать к конкретным моделям или провайдерам, выставить срок действия и префикс для удобной идентификации в логах. Звучит несложно и красиво, можно генерировать красивые графики и статистику использования.
Но вот RBAC (Role-Based Access Control) — штука поинтереснее. Готовые шлюзы дают скоупинг по ключу, но вашу модель тенантов, ролей и иерархию доступа они не знают. Если у вас есть команды, проекты, окружения и правила вроде «тимлид может выпускать ключи для своей команды, но не для продакшена», это придётся писать самому, потому что ни LiteLLM, ни Portkey не знают, как устроен ваш IAM.
Надёжность: fallback и circuit breaker
Здесь я буду краток, ведь как я думаю, это база и она известна всем. Fallback между провайдерами, circuit breaker и таймауты — это стандартные паттерны, которые много раз реализованы в готовых шлюзах. Vercel в своём наборе паттернов для production-шлюза ставит унифицированную абстракцию провайдера и автоматический failover на первые места, до cost attribution и семантического кэша. Datadog в обзоре best practices для AI-шлюзов 2026 года тоже подчёркивает, что централизованные fallback, retries и rate limiting — базовая гигиена для продакшен-агентов.
Если у вас нестандартный сценарий вроде shadow routing (когда запрос уходит в два провайдера параллельно, а результат одного используется для сравнения качества) или если ваш health-check должен учитывать специфику бизнеса — то создание своего шлюза пойдёт на пользу.
Маршрутизация: модель как политика
Маршрутизация по стоимости, латентности или сложности запроса — ещё одна фича, которую готовые шлюзы (LiteLLM, Bifrost, Hyperion) уже закрывают. В своём шлюзе имеет смысл строить только те правила, которые отражают хитрые особенности бизнеса — к примеру, клиентам с SLA всегда отдавать Claude Opus, а внутренним инструментам — Haiku, которая проходит по качеству.
К примеру вот как может выглядеть на Python:
ROUTING_TABLE = { "cheap": {"provider": "bothub", "model": "claude-haiku-5"}, "default": {"provider": "bothub", "model": "claude-opus-5"},}def resolve_route(req: ChatRequest) -> dict: if req.max_tokens and req.max_tokens < 512: return ROUTING_TABLE["cheap"] return ROUTING_TABLE["default"]
Собственно можно улучшить резолвинг, и сделать более сложные проверки, тут я показал пример.
Кэш: exact-match и семантический
Exact-match кэш — это просто, и его можно строить самому без особых сожалений. Семантический кэш — совсем другая история. По данным из практики, реальные hit rates для семантического кэша составляют 20–40%, а главная проблема — false hits, когда эмбеддинги близки, а смысл разный («столица Франции» и «столица Германии» в плотном векторном пространстве выглядят похоже).
Если вы всё-таки строите семантический кэш сами, закладывайте admission-гейт (не кэшировать ошибки, отказы и ответы с низкой обоснованностью) и версионирование ключей через эпохи, чтобы при обновлении эмбеддера или схемы старые записи инвалидировались.
Безопасность: PII и prompt-инъекция
PII-редакция и защита от prompt-инъекций — это также фича для вашего шлюза. Только вы знаете, какие типы данных и паттерны нужно скрывать и защищать, какие действия разрешены — а какие нет.
Кстати, о безопасности AI-агентов есть хороший пост от создателя FastStream и AG2.
Наблюдаемость: trace ID и cost attribution
А наблюдаемость и логгирование — вещи крайне нужные. Например, унификация запросов — чтобы понимать, какие запросы к провайдеру к какому запросу к приложению относятся, например когда задача в приложении состоит из нескольких разных запросов.
Реализовать это можно как middleware, с условным X-Request-ID, который сохраняется вдоль всех операций. Дальше можно записывать его в трейсинг, вместо с входящими-выходящими токенами, стоимостью, моделями и всем чем вы пожелаете.
Стриминг: учёт и отмена
Стриминг стоит продумать, ведь иногда после закрытия вкладки задача может работать, и токены будут тратиться просто так. А также нужно также точно считать использованные токены, стоимость, аналитику и историю.
FastAPI + Pydantic — наброски для шлюза
С теорией покончено, а теперь перейдём к практике. Сразу хочу оговориться, что это не полноценный туториал по созданию своего шлюза — с этим, я думаю, вы и сами способны справиться. Так что попробую сфокусироваться на главном.
А ещё хочу упомянуть Pydantic AI (я как-то писал про него статью), который позволяет создавать типизированных ИИ-агентов.
Начнём с банального. Любой запрос к шлюзу должен нести информацию о том, кто платит, иначе cost attribution превращается в гадание по логам провайдера, где никакой атрибуции нет.
Вот пример кода:
from pydantic import BaseModel, Fieldfrom typing import Literalclass ChatRequest(BaseModel): model: str = Field(..., examples=["claude-opus-5"]) messages: list[dict] stream: bool = False max_tokens: int | None = Field(default=None, le=4096) consumer: Literal["feature-a", "feature-b"] # кто платит
Pydantic AI — это фреймворк для агентов, который делает команда Pydantic, и он умеет ходить в любой OpenAI-совместимый эндпоинт через OpenAIChatModel с кастомным OpenAIProvider. Вот пример кода на нашем шлюзе:
from pydantic_ai import Agentfrom pydantic_ai.models.openai import OpenAIChatModelfrom pydantic_ai.providers.openai import OpenAIProviderprovider = OpenAIProvider( base_url="https://openai.bothub.chat/v1", api_key="your-bothub-token",)model = OpenAIChatModel("claude-opus-5", provider=provider)agent = Agent( model, instructions="Отвечай коротко, одним предложением.",)result = agent.run_sync("Откуда взялась фраза hello world?")print(result.output)
Внутри Pydantic AI всё построено на asyncio, а run_sync — синхронная надстройка для блокнотов и скриптов; в FastAPI вы будете использовать обычный await agent.run(...).
Примечательно, что OpenAIProvider читает OPENAI_API_KEY и OPENAI_BASE_URL из окружения, так что в контейнере можно обойтись без хардкода ключа в коде — достаточно прокинуть переменные при деплое. А если модель ведёт себя странно (например, не принимает несколько system-сообщений или требует старое поле max_tokens вместо max_completion_tokens), в Pydantic AI есть OpenAIModelProfile.
Маршрутизация в Pydantic AI не прибита к эндпоинту, ибо агент создаётся с конкретной моделью, а модель можно выбрать до создания агента. Получается функция, которая принимает ChatRequest и возвращает готового агента — с нужной моделью и, если хочется, с нужными инструкциями:
ROUTING_TABLE = { "cheap": {"provider": "bothub", "model": "claude-haiku-5"}, "default": {"provider": "bothub", "model": "claude-opus-5"},}def build_agent(req: ChatRequest) -> Agent: route = ROUTING_TABLE["cheap"] if req.max_tokens and req.max_tokens < 512 else ROUTING_TABLE["default"] provider = OpenAIProvider(base_url="https://openai.bothub.chat/v1", api_key=BOTHUB_KEY) model = OpenAIChatModel(route["model"], provider=provider) return Agent(model, instructions="...")
Да, маршрут становится политикой. Можно даже интегрировать через Dependency Injection — стандартный Depends в FastAPI или DI-фреймворки по типу dishka. Если завтра вы добавите второго провайдера или решите, что клиентам с SLA всегда нужен Opus, меняется таблица и, может быть, пара условий в build_agent. В общем — любимый SOLID и DRY.
А возвращаясь к теме стриминга, то в Pydantic AI для этого есть run_stream, и usage доступен после завершения стрима:
async def stream_with_usage(req: ChatRequest): agent = build_agent(req) async with agent.run_stream(req.messages) as response: async for text in response.stream_text(): yield text usage = response.usage() record_usage(req.consumer, usage.input_tokens, usage.output_tokens)
response.usage() возвращает объект с input_tokens, output_tokens и стоимостью, если модель её знает. Это не отменяет решения о том, как считать стоимость стримингового запроса — резервировать до, оценивать после или брать usage из последнего чанка. Но, по крайней мере, вам не нужно парсить SSE вручную и надеяться, что провайдер прислал usage в финальном чанке. Кстати, если клиент отвалился, Pydantic AI не обязательно отменит запрос автоматически, так что проверку await request.is_disconnected() в цикле всё равно придётся добавить.
А ещё не стоит забывать про идентификацию запросов. Можно реализовать, как я уже говорил, через Middleware:
import uuid@app.middleware("http")async def add_trace_id(request, call_next): request.state.trace_id = request.headers.get("X-Request-ID") or str(uuid.uuid4()) response = await call_next(request) response.headers["X-Request-ID"] = request.state.trace_id return response
Дальше этот trace_id живёт в RunContext как зависимость и попадает в логи вместе с consumer, model, tokens_in, tokens_out и стоимостью.
В Pydantic AI весьма хорошо сделаны зависимости. Агент объявляет deps_type, каждый запуск получает deps, а инструменты и output-валидаторы читают их из RunContext. Для шлюза это удобно, потому что consumer и team_id можно прокинуть как зависимость.
from dataclasses import dataclassfrom pydantic_ai import Agent, RunContext@dataclassclass GatewayDeps: consumer: str team_id: stragent = Agent(model, deps_type=GatewayDeps, instructions="...")@agent.toolasync def check_budget(ctx: RunContext[GatewayDeps]) -> str: """Проверить, не превышен ли бюджет команды.""" return await budget_service.status(ctx.deps.team_id)
В FastAPI это выглядит почти как DI: agent.run(..., deps=GatewayDeps(consumer=req.consumer, team_id=req.team_id)), и дальше инструменты сами разбираются, куда смотреть. Тесты тоже выигрывают: agent.override(deps=test_deps) подсовывает заглушку без изменения продакшен-кода.
Если хочется совсем модно, в Pydantic AI v2 появились «capabilities» — композиционные блоки, которые собирают инструкции, инструменты, хуки и настройки модели в одну единицу, и CodeMode, где модель пишет один скрипт вместо череды вызовов инструментов. Для шлюза это скорее задел на будущее, чем необходимость, но звучит красиво.
Наш OpenAI-совместимый эндпоинт https://openai.bothub.chat/v1 работает с официальным SDK без адаптера, и Pydantic AI тоже цепляется к нему через OpenAIProvider с base_url — никаких танцев с бубном. Есть Chat Completions и Responses API; Responses API поддерживает JSON-схемы и инструменты, но не требует официального SDK, что для некоторых сценариев удобнее. Для медиамоделей используется второй шлюз в формате Replicate.
В личном профиле можно посмотреть и скачать статистику транзакций, как и потраченное количество CAPS, так и количество токенов, а также время и конкретный ключ, с которого прошла транзакция.

Если вы читаете это и понимаете, что шлюз вам пока не нужен, но нужен доступ к моделям через один OpenAI-совместимый эндпоинт — BotHub закрывает именно эту часть. По реферальной ссылке начисляют 300 000 CAPS, официальный SDK OpenAI и Pydantic AI работают после замены base_url.
Заключение
Стоит помнить, что шлюз — это ещё один продакшен-сервис. У него будет и деплой, и алерты, и база данных, и сеть, и если он упадёт — это будет инцидент. А если он ещё и единая точка отказа — то вообще караул. И не забывайте про тесты.
Бюджет может расходиться из-за кэша, стриминга, и прочих плавающих затрат.
Но если вы готовы принимать архитектурные решения и проектируйте масштабируемую систему — то шлюз может помочь. Да и не только управлением ИИ-запросами, а в принципе статистикой, связанной с использованием ИИ-функций в вашем проекте.
И всегда задавайте вопрос — какую конкретную дыру вы закрываете, и почему именно такое решение хотите? Хотите потому что вы великий инженер, или же исходя из ситуации? Да и одно дело на(ш)кодить — это может и ИИ сделать, а другое дело — поддерживать.
Источник: habr.com