Встроенная документация и использование SenDev: AI Core в других модулях

Страница «Документация» внутри AI Core содержит справочную информацию о возможностях общего AI-слоя и предназначена прежде всего для администраторов и специалистов, которые подключают к нему другие решения.

Для повседневной настройки провайдеров или промптов использовать эту страницу необязательно. Она полезна, когда нужно понять общий принцип работы AI Core, проверить возможности текущей версии или подготовить подключение нового функционального модуля.

[Скриншот 1: встроенная страница «Документация» AI Core]

Зачем нужен отдельный AI Core

Основная идея модуля — не хранить настройки AI в каждом продукте отдельно. AI Core централизует:

• подключения к текстовым и графическим AI-сервисам;
• ключи доступа;
• списки моделей;
• промпты и сценарии;
• маршрутизацию запросов;
• кэш;
• очередь;
• журнал;
• расчёт стоимости;
• локальные лимиты;
• настройки маскирования и безопасности.

За счёт этого функциональный модуль отвечает за свою прикладную задачу, а работа с конкретными AI-провайдерами остаётся в AI Core.

Что это даёт администратору

Если несколько модулей используют AI, не нужно вводить один и тот же ключ в каждом из них. Можно централизованно:

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

Текстовые запросы

Для текста подключаемый модуль передаёт AI Core задачу и сценарий. AI Core подбирает активный совместимый профиль, использует нужный промпт, отправляет запрос и возвращает нормализованный результат.

Администратору не требуется настраивать формат HTTP-запроса в каждом функциональном модуле. Для стандартных сервисов достаточно настроить профиль в разделе «Провайдеры».

Генерация изображений

Графические задачи используют отдельные профили и сценарии. AI Core приводит ответы разных сервисов к общему виду, а функциональный модуль решает, как использовать полученное изображение.

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

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

Маршрутизация

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

Для большинства интеграций удобнее оставить выбор провайдера централизованным. Тогда смена основного сервиса выполняется в AI Core, а не в коде каждого модуля.

Сценарий как стабильный контракт

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

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

Поэтому при редактировании стандартных или уже используемых промптов не меняйте сценарий без необходимости.

Переменные промптов

Функциональный модуль передаёт значения переменных, а AI Core подставляет их в шаблон. Такой подход позволяет держать общий текст инструкции в библиотеке и не создавать отдельный промпт для каждого объекта.

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

Кэш

Кэш позволяет не отправлять повторно одинаковый запрос, если актуальный результат уже сохранён. Это может уменьшить время ответа и расход внешней квоты.

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

Очередь

Очередь предназначена для задач, которые удобно выполнять в фоне. Функциональный модуль может поставить задачу, а AI Core обработает её штатным worker/агентом.

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

Журнал как общая точка диагностики

Каждый интегрированный модуль передаёт AI Core собственный идентификатор и сценарий. Поэтому в журнале можно увидеть, какой продукт инициировал конкретный вызов.

Это позволяет разбирать проблему без просмотра логов каждого модуля отдельно:

1. найдите модуль и сценарий;
2. проверьте провайдера и модель;
3. посмотрите статус и ошибку;
4. повторите тот же тип вызова в Песочнице.

Лимиты

AI Core может контролировать расход до отправки внешнего запроса. Область лимита можно задавать по:

• модулю;
• сценарию;
• пользователю.

Это особенно удобно для общего AI-слоя: один дорогой сценарий можно ограничить, не отключая остальные функции сайта.

Structured output

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

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

Безопасность

При подключении функциональных модулей соблюдайте несколько правил:

• ключи провайдеров хранятся только в AI Core, а не дублируются по модулям;
• перед сохранением секретов проверяется готовность защищённого хранилища;
• журнал маскирует чувствительные значения;
• не следует сохранять полный запрос/ответ, если для поддержки достаточно служебной информации;
• публичный Bitrix24 endpoint остаётся выключенным, если не используется;
• для endpoint обязательно применяется предусмотренная проверка входящего запроса.

Порядок подключения нового модуля к AI Core

С точки зрения администратора удобный процесс выглядит так:

1. Установить и проверить AI Core.
2. Настроить рабочий текстовый и/или графический профиль.
3. Создать или выбрать сценарий в библиотеке промптов.
4. Проверить сценарий в Песочнице.
5. Убедиться, что журнал записывает ожидаемые сведения.
6. При необходимости создать лимит для нового модуля или сценария.
7. Настроить AI-возможность уже в функциональном модуле.
8. Выполнить тест из самого функционального модуля.
9. Сверить получившуюся запись в общем журнале AI Core.

[Скриншот 2: пример связки «Провайдеры → Промпты → Песочница → Журнал»]

Что проверять после обновления AI Core

• открыть «Диагностику» и проверить версию схемы;
• убедиться, что пользовательские профили и ключи сохранились;
• добавить отсутствующие стандартные профили, если появились новые;
• проверить стандартную библиотеку промптов;
• выполнить Dummy-тест;
• выполнить короткий запрос через основной рабочий профиль;
• проверить запись в журнале.

Обновление 1.1.0 рассчитано на добавочное изменение структуры без очистки существующих рабочих данных.

Встроенная документация и эта база знаний

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

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

Когда нужны технические подробности

Большинство администраторов может работать с AI Core без программирования. Техническая часть нужна, когда разрабатывается новый функциональный модуль, нестандартный драйвер, собственный endpoint или специальный сценарий фоновой обработки.

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

[Скриншот 3: блок встроенной документации с описанием возможностей AI Core 1.1.0]

Итог

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