Первое подключение модели выглядит просто: библиотека поставщика, ключ, вызов из кода. Работает, и на прототипе этого достаточно.
Проблемы начинаются позже и все сразу: цена изменилась, поставщик стал недоступен, вышла модель лучше, счёт вырос втрое без объяснений, а на вопрос «что мы отправляли в модель в прошлый вторник» ответить нечем.
Шлюз — слой между вашим кодом и моделями, который эти вопросы закрывает. Не потому, что он «правильная архитектура», а потому, что каждая из перечисленных ситуаций случается, и без него каждая решается переписыванием.
Что он делает
Единая точка обращения. Код не знает, какая модель отвечает. Смена поставщика — изменение настройки, а не правка кода в двадцати местах.
Маршрутизация. Простые шаги — на лёгкую модель, сложные — на тяжёлую. Один из самых действенных способов снизить расходы, и без общего слоя он превращается в развесистые условия по всему коду — «Малые модели».
Запасной путь. Основная модель недоступна — запрос уходит на запасную. Без этого недоступность поставщика останавливает процесс целиком.
Лимиты расходов. Потолок на проект, на пользователя, на единицу времени, с остановкой при превышении. Обязательно для агентских сценариев, где число обращений заранее неизвестно — «Зацикливание ИИ-агента».
Учёт. Кто, сколько и на что потратил. Без этого счёт — одно число в конце месяца, и разобраться в его росте невозможно.
Журнал запросов и ответов. Основа диагностики: без него на жалобу «система ответила неверно» вы видите результат и не видите, что было отправлено.
Кеширование. Повторяющиеся запросы не идут в модель дважды.
Повторы и ограничение частоты. Обработка временных отказов и соблюдение квот поставщика в одном месте.
Обезличивание. Если из запросов нужно вычищать персональные данные перед отправкой наружу — это делается здесь, а не в каждом месте вызова — «152-ФЗ и нейросети».
Что ломается без него
Список из практики, а не из теории.
Смена модели становится проектом. Вызовы разбросаны по коду, у каждого свои особенности. Замена, которая должна занимать день, занимает недели — «Миграция между моделями».
Недоступность поставщика останавливает всё. Запасного пути нет, потому что его негде было реализовать.
Расходы неуправляемы. Счёт вырос — непонятно, из-за какого процесса.
Нет данных для разбора. Что отправляли, что получили, сколько это стоило — неизвестно.
Нельзя использовать разные модели на разных шагах. Технически можно, практически превращается в кашу из условий.
Ключи доступа расползаются по конфигурациям сервисов.
Когда достаточно тонкой обёртки
Честная оговорка: полноценный шлюз нужен не всем.
Если у вас один процесс, одна модель, небольшой поток — хватит тонкой обёртки: функция, через которую идут все обращения, с логированием и лимитом. Это тридцать строк кода, и они закрывают главное.
Ключевое здесь не размер решения, а правило: обращения к модели идут через одно место. Даже если это место — простая функция.
Полноценный шлюз оправдан, когда:
- моделей несколько или предполагается смена;
- процессов несколько и нужен учёт по каждому;
- поток заметный и расходы нужно контролировать;
- есть требования к обезличиванию или журналированию;
- нужен запасной путь при недоступности.
Свой или готовый
Готовые решения — их несколько, включая открытые: обзор одного из них есть отдельно, «OmniRoute: бесплатный AI-шлюз». Дают маршрутизацию, учёт, лимиты и совместимый интерфейс из коробки. Разумный выбор, если нужен полный набор.
Свой тонкий слой — когда нужны две-три функции из списка и не хочется сопровождать ещё один компонент.
Чего делать не стоит — писать полноценный шлюз с нуля, если задача укладывается в готовое. Это отдельный продукт со своим сопровождением.
Разбор: смена поставщика за один день
Задача. Конвейер обработки обращений: классификация, извлечение данных, черновики ответов. Около 3 000 операций в сутки.
Как было устроено. Все обращения к моделям шли через собственный тонкий слой: единый интерфейс, настройка «какая модель на каком шаге», журнал, лимит расходов, кеш.
Слой писался не ради архитектурной красоты — просто с самого начала было понятно, что моделей будет несколько.
Что произошло. Поставщик основной модели изменил условия: выросла цена и появились ограничения по объёму.
Что сделали. Запасная модель другого поставщика уже была подключена и использовалась на части шагов. Прогнали на ней контрольный набор задач — качество оказалось сопоставимым на классификации и извлечении, чуть хуже на черновиках ответов.
Переключили классификацию и извлечение полностью, черновики оставили на прежней.
Сколько заняло. Прогон набора — пара часов. Переключение — изменение настройки. Наблюдение за первыми сутками — весь остальной день.
Что было бы без слоя. Обращения к модели в семи местах кода, у каждого свой формат запроса и разбора ответа. По опыту похожих ситуаций — недели работы плюс риск пропустить какое-то место.
Побочный результат. Журнал обращений, заведённый «на всякий случай», оказался главным инструментом при разборе качества: по нему было видно, какие именно запросы стали хуже после переключения.
Что стоит забрать. Слой доступа окупается не тем, что он элегантен, а тем, что первая же вынужденная смена модели проходит за день вместо месяца. А такая смена случается — по цене, по доступности или потому что вышло что-то лучше.
С чего начать
Минимум, который стоит завести сразу, даже на прототипе:
- Одно место в коде, через которое идут все обращения к модели.
- Журнал: запрос, ответ, модель, время, стоимость.
- Лимит расходов с остановкой.
- Модель в настройке, а не в коде.
Четыре пункта, несколько часов работы. Всё остальное добавляется по мере необходимости.
Частые вопросы
Зачем нужен шлюз моделей?
Чтобы код не зависел от конкретного поставщика: смена модели становится изменением настройки, а не правкой во многих местах. Плюс он даёт то, что иначе негде разместить: лимиты расходов, учёт по процессам, журнал запросов, запасной путь при недоступности и маршрутизацию простых задач на дешёвые модели.
Нужен ли он, если модель одна?
Полноценный — нет, но правило «все обращения идут через одно место» стоит соблюдать с самого начала. Это может быть простая функция на тридцать строк с журналом и лимитом. Модель одна ровно до момента, когда она станет дороже, недоступнее или хуже новой.
Свой шлюз или готовый?
Если нужен полный набор — маршрутизация, учёт, лимиты, запасные пути, — разумнее взять готовое решение, включая открытые. Свой тонкий слой оправдан, когда достаточно двух-трёх функций и не хочется сопровождать лишний компонент. Писать полноценный шлюз с нуля обычно не стоит.
Замедляет ли шлюз работу?
На фоне времени ответа модели его накладные расходы незначительны. При этом он часто ускоряет работу за счёт кеширования повторяющихся запросов.
Как он помогает экономить?
Тремя способами: маршрутизацией простых шагов на дешёвые модели, кешированием повторов и учётом расходов по процессам — последнее показывает, куда именно уходит счёт. Плюс лимит с остановкой защищает от лавины повторов при сбое.
Что записывать в журнал?
Запрос, ответ, использованную модель, время, длину контекста и стоимость. Этого достаточно и для разбора качества, и для контроля расходов. Учтите, что журнал содержит переданные данные и потому требует тех же ограничений доступа, что и сами данные.
Что дальше
Как пройти смену модели без переписывания — «Миграция между моделями». Что делать при недоступности поставщика — «Если зарубежная модель недоступна». Из чего складывается счёт — «Длина контекста и стоимость».
Проектирование слоя доступа к моделям — часть работы по разработке и внедрению ИИ и автоматизации процессов.