Программный интерфейс

Как вызывать коннектор из своего кода — модули, место вызова, единый результат и расход.

Из своего кода коннектор вызывается через два общих модуля:

Модуль	Для чего
РаботаСМоделямиИИ_зи	Основное: запрос к модели по промту, параметры промта для кода, проверка подключения, обновление каталога моделей.
ДиспетчерПровайдеровИИ_зи	Прочие возможности сервисов — эмбеддинги, изображения, речь, видео — и операции из нескольких обращений с общим расходом.

Остальные модули расширения внутренние: их состав и методы меняются без предупреждения, вызывать их нельзя.

Где вызывать

Оба модуля только серверные, без вызова сервера. С клиента обращайтесь к ним через свою серверную процедуру: &НаСервереБезКонтекста в модуле формы или общий модуль с флагом «Вызов сервера».

Откуда вызывать:

ваша конфигурация с установленным расширением (.cfe) или конфигурация из поставки (.cf) — модули вызываются напрямую из любого серверного кода;
внешняя обработка или отчёт в базе с коннектором — так же, из серверного кода;
внешнее соединение — недоступно.

Вне транзакции

Внутри активной транзакции запрос к сервису отклоняется сразу, до обращения к сети: Успешно = Ложь, КодСостояния = 400. Ответа сервиса порой ждут минутами, и всё это время транзакция держала бы блокировки. Вызывайте коннектор до транзакции, а результат записывайте отдельно.

Права

Код выполняется с правами текущего пользователя. Для запросов к моделям достаточно роли «Чтение просмотр ИИ». СохранитьПараметрыВПромт и ОбновитьКаталогМоделей пишут в справочники коннектора, им нужна роль «Добавление / изменение ИИ». О ролях — в статье Установка.

Единый результат

Методы, которые обращаются к сервису, возвращают структуру:

Поле	Тип	Смысл
`Успешно`	Булево	Истина — ответ получен и прошёл проверки коннектора.
`Данные`	Произвольный	Результат; что именно — описано у каждого метода. При неуспехе обычно `Неопределено`.
`КодСостояния`	Число	HTTP-код ответа сервиса или код отказа коннектора.
`ОписаниеОшибки`	Строка	Причина неуспеха — готовый текст для пользователя с именем провайдера. При успехе пусто.

Методы дополняют структуру своими полями — они перечислены в описании методов. Решение принимайте по Успешно, а код помогает понять причину:

Код	Что произошло
200	Сервис ответил. Если при этом `Успешно = Ложь`, ответ не прошёл проверку коннектора (например, не соответствует схеме ответа промта).
400	Запрос отклонён до отправки: не заполнены обязательные данные, не подходит файл, у провайдера не задан ключ или провайдер не используется, возможность не поддерживается, вызов в транзакции. Тот же код возвращает и сервис, если не принял запрос.
504	Сервис не ответил за время таймаута.
500	Нет связи с сервисом, его ответ не удалось разобрать или сервис сообщил о сбое.
Прочие	Ответ сервиса: 401 — неверный ключ, 402 — на балансе провайдера недостаточно средств, 403 — доступ запрещён, 429 — превышен лимит запросов, 502 и 503 — сервис недоступен.

Расход

Расход операции — структура в поле Расход результата ВыполнитьЗапросПоПромту; её же возвращает ДиспетчерПровайдеровИИ_зи.ЗавершитьОперацию.

Поле	Тип	Смысл
`Обращений`	Число	Обращений к сервису, включая отклонённые до отправки.
`ТокеныЗапроса`	Число	Токены запроса, в том числе взятые из кеша.
`ТокеныОтвета`	Число	Токены ответа, в том числе потраченные на рассуждения.
`ТокеныРассуждений`	Число	Из них — на рассуждения.
`ТокеныИзКеша`	Число	Токены запроса, которые сервис взял из кеша.
`ТокеныВсего`	Число	Итог токенов, как его сообщил сервис. Если сервис итога не сообщил (так отвечают модели решений), — сумма токенов запроса и ответа.
`Стоимость`	Число	Сумма стоимостей, сообщённых сервисом. Сам коннектор стоимость не рассчитывает.
`ВалютаСтоимости`	Строка	Пусто — сервис стоимость не сообщил, и нулевая `Стоимость` ничего не значит. Заполнена при нулевой `Стоимость` — обращения бесплатны.
`СтоимостьПолная`	Булево	Ложь — часть обращений израсходовала токены, но стоимость не сообщила; тогда `Стоимость` — оценка снизу.
`Длительность`	Число	Суммарное время обращений, мс.

Стоимость в рублях сообщает RouterAI, Yandex её не сообщает. Ответ модели решений стоимости не содержит: коннектор сразу после ответа запрашивает её у RouterAI отдельным обращением и записывает в ту же запись журнала. Если сервис стоимость так и не отдал, обращение остаётся успешным, а стоимость — не сообщённой. Готовую строку для пользователя возвращает РаботаСМоделямиИИ_зи.ПредставлениеРасхода.

Журнал запросов

Каждое обращение к сервису — одна запись в журнале запросов, включая отклонённые до отправки и прерванные исключением. Обращения одной операции объединены идентификатором операции. Не попадают в журнал только вызовы внутри транзакции и отказы ВыполнитьЗапросПоПромту по настройкам промта, найденные до обращения к сервису. Как смотреть журнал — в статье Журнал запросов и расход.

Пример

Промт «Ответ на вопрос клиента» заранее создан в пользовательском режиме (см. Промты): в нём выбраны провайдер и модель, задан системный текст, имя для кода — ОтветНаВопросКлиента. Наименование промта можно менять: код находит его по имени.

&НаСервереБезКонтекста
Функция ОтветНаВопрос(ТекстВопроса)

	ПараметрыЗапроса = Новый Структура;
	ПараметрыЗапроса.Вставить("Промт", "ОтветНаВопросКлиента");
	ПараметрыЗапроса.Вставить("СообщениеПользователя", ТекстВопроса);

	Результат = РаботаСМоделямиИИ_зи.ВыполнитьЗапросПоПромту(ПараметрыЗапроса);
	Если НЕ Результат.Успешно Тогда
		ВызватьИсключение Результат.ОписаниеОшибки;
	КонецЕсли;

	Возврат Результат.Данные;

КонецФункции

Журнал запросов и расход

РаботаСМоделямиИИ_зи