Чек-лист перед внедрением модели

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

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

Что проверить перед запуском: короткий список

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

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

Зафиксирован ли идентификатор модели

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

В каталоге рядом живут позиции с похожими именами и разной ставкой — например, gemini-3-7-flash за 8 ₽ и gemini-3-7-flash-tiered за 6 ₽ за миллион токенов. Отличие в одном слове, разница в счёте — заметная.

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

Какие протоколы открыты у позиции

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

Минимум, который стоит проверить своими руками:

• Обычный ответ. Работает всегда, с него начинают.
• Потоковая передача. Нужна там, где пользователь видит ответ по мере набора; когда она обязательна, а когда нет — в разборе потоковой передачи.
• Вызов функций. Без него агент не соберётся; перечень поддерживающих позиций — в статье про вызов функций в API.
• Работа с изображениями на входе. В каталоге часть позиций отмечена как проверенная, часть — как непроверенная. Непроверенная означает «мы этого не проверяли», а не «работает».

Последнее стоит подчеркнуть отдельно. Если возможность в каталоге не подтверждена, планировать под неё сценарий нельзя — сначала пробный запрос, потом архитектура.

Что с лимитами частоты запросов

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

Рабочая схема состоит из трёх частей: очередь на стороне вашего сервиса, повтор с нарастающей паузой и потолок числа повторов. Без потолка одна волна отказов превращается в лавину собственных запросов. Подробный разбор кодов и стратегий — в статье про лимиты запросов.

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

Есть ли проверенная запасная позиция

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

Запасная позиция закрывает три случая: основная отвечает ошибкой, основная молчит дольше таймаута, основная выключена вендором. Первые два происходят регулярно, третий — по расписанию, о котором вы узнаёте заранее. Механика переключения разобрана в статье про отказы маршрута и запасной вариант.

Запасную позицию имеет смысл держать в том же каталоге и на том же ключе. В KeyDealer 53 позиции, 40 доступны сейчас, и переключение между ними — смена одной строки, а не второй договор: ключ один, оплата российской картой в рублях, расход по обеим позициям виден в одном журнале.

Проверка простая: выключите основную позицию в конфигурации и прогоните весь сценарий. Если где-то развалился формат ответа или перестали вызываться инструменты — запас не готов.

Работает ли кэш

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

Причина почти всегда одна: в начало запроса подставляется что-то переменное — текущая дата, имя пользователя, идентификатор сессии. Неизменная часть должна идти первой, переменная — последней. Условия и порядок проверки — в разборе кэша промптов.

Это единственный пункт чек-листа, который влияет только на счёт и никогда — на качество ответа. Его пропускают чаще прочих именно поэтому.

Как ловится неверный ответ

Проверьте, что мусорный вход не проходит дальше по системе. Подайте на вход заведомую чушь и посмотрите, что уйдёт в базу данных или клиенту.

Три уровня защиты, которые стоит иметь до запуска:

Проверка формата. Ответ разбирается по схеме, и всё, что не разбирается, уходит в отдельную очередь. Как добиться предсказуемой структуры — в статье про строгий JSON от нейросети.

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

Правило отказа. У сценария должен быть путь «не знаю»: передача человеку, повторный запрос, возврат пустого результата. Сценарий без пути отказа выдумывает ответ вместо того, чтобы его не дать.

Где хранится ключ

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

Три запрета без исключений: ключ не попадает в репозиторий, не уезжает во фронтенд или мобильное приложение и не пересылается в переписке. Ключ во фронтенде считается скомпрометированным с момента первой загрузки страницы — не потому, что кто-то его обязательно найдёт, а потому, что предполагать обратное нельзя.

Дополнительно стоит завести отдельные ключи для разработки и для продакшена и уметь отозвать любой из них за минуту. Практики хранения разобраны в статье как хранить API-ключи.

Что пишется в журнал

Проверьте, открыв запись одного вчерашнего запроса. Если по ней нельзя восстановить, что произошло, журнала у вас нет.

Обязательный состав записи: идентификатор модели, число входных и выходных токенов, код ответа, текст ошибки, длительность, признак повторной попытки и идентификатор операции для связи со своей системой. Что ещё имеет смысл писать и как это хранить — в разборе логирования запросов к моделям.

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

В каком порядке это делать

Сверху вниз по таблице, за один заход. Первые четыре пункта — про то, будет ли сценарий работать; последние четыре — про то, сможете ли вы его чинить.

Практический совет: пройдите чек-лист на тестовом контуре до того, как напишете основную логику. Три из восьми пунктов влияют на архитектуру — протоколы, запасная позиция и отлов неверного ответа, — и узнавать о них после написания кода дороже, чем до.

Чего мы не утверждаем

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

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

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

Что нужно, чтобы попробовать

Ключ заводится за минуту на keydealer.ru/login — почта и пароль, без документов и без зарубежной карты. Оплата российской картой в рублях, один ключ на весь каталог.

Приветственный бонус даёт доступ к платным позициям сразу. Пройти по чек-листу целиком можно до первого пополнения: пробные запросы каждым протоколом, переключение на запасную позицию и просмотр журнала укладываются в один вечер.

Что держать в голове

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

Три пункта влияют на архитектуру: протоколы, запасная позиция и отлов неверного ответа. Их проверяют до кода, остальные пять — до запуска.

Журнал и хранение ключа не улучшают сценарий, но определяют, сможете ли вы его починить и не заплатите ли за чужой расход. Как мы проверяем факты и почему у каждой цифры стоит дата — на странице о проекте. Завести ключ и пройти чек-лист: keydealer.ru/login.