Документация для разработчиков
Темная тема

ai.engine.register

Scope: ai_admin Права на выполнение: администратор

ai.engine.register

REST-метод для добавления пользовательского сервиса. Метод регистрирует engine, при повторном вызове обновляет его. Это не совсем место встройки, так как endpoint партнера должен следовать четким форматам.

Параметры

Параметр Описание С версии
name Осмысленное и короткое название, которое будет появляться в интерфейсе пользователя.
code Уникальный код engine
category Может быть либо text (генерация текста), либо image (генерация картинок), либо audio (распознавание текста).
completions_url endpoint для обработки пользовательского запроса.
settings Тип AI (см. описание ниже). Необязательный. 23.800

Метод в случае успеха вернет ID добавленного engine.

Тип AI

Массив параметров:

Параметр Описание С версии
code_alias Тип AI. Доступны значения:
  • ChatGPT (Open AI)
  • GigaChat (Сбер)
  • YandexGPT (Яндекс)
(по умолчанию ChatGPT).

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

В текущий момент это завязка только на препромпты, в будущем возможно расширение влияния типа AI.

model_context_type Тип подсчета контекста (см. описание context ниже). Доступны значения:
  • token - токены В контексте нейросетей, термин "tokens" (токены) обычно относится к минимальным единицам, на которые разбивается входной текст или последовательность символов перед подачей на обработку модели. Токеном может быть одна буква, одно слово или даже целая фраза, в зависимости от типа и задачи модели.

    Подробнее...
  • symbol - символы. Обычная длина текста.
По умолчанию token.
model_context_limit Объем контекста (по умолчанию 16К). Перед отправкой вам запроса пользователя, проверяется лимит контекста согласно типу подсчета.

Пример

BX24.callMethod(
	'ai.engine.register',
	{
		name: 'Ivanov GPT',
		code: 'ivanov_gpt',
		category: 'text',
		completions_url: 'https://antonds.ru/ai/aul/completions/',
		settings: {
			code_alias: 'ChatGPT',
			model_context_type: 'token',
			model_context_limit: 16*1024,
		},
	},
	function(result)
	{
		if(result.error())
		{
			console.error(result.error());
		}
		else
		{
			console.info(result.data());
		}
	}
);

Endpoint

Внимание! В скрипте все в едином потоке кода, это для примера. В режиме production необходимо вынести строчки кода 30-54 в отдельную часть.

Шаблон для создания пользовательского endpoint можно использовать для кастомизации собственного сервиса.

Обратите внимание, скрипт должен:

  1. принять запрос, отработать его быстро, принять и добавить в свою внутреннюю очередь.
  2. уметь возвращать различные статусы ответа (есть в примере):
    • 200 — обычный переход по ссылке;
    • 202 — если вы приняли запрос и добавили в очередь;
    • 503 — если сервис недоступен.

Как делать ответ в случае готовности – указано в шаблоне.

Ответ ожидается в течение определенного времени (тоже упоминается в скрипте), потом колбек становится невалидным.

Важно! Помимо кода ответа, в случае успешной генерации, обработчик должен обязательно возвращать json_encode(['result' => 'OK']).

Если категория провайдера audio, то в ключе prompt вам вернётся массив:

  • file - ссылка до файла (обратите внимание, может быть без расширения!),
  • fields - вспомогательный внутренний массив, состоящий в свою очередь из:
    • type – content-type файла, как раз на случай, если он без расширения (например, "audio/ogg"),
    • prompt – вспомогательный промпт для аудио-файла (может содержать ключевую информацию для помощи в распознавании файла: например, название вашей компании).

В ответе провайдеру уходят так же дополнительные поля:

Поля Описание С версии
auth Данные по авторизации, 23.600.0
payload_raw Сырое значение промпта (при использовании Copilot там будет символьный код использованного промпта) 23.600.0
payload_provider Символьный код провайдера препромпта (при использовании Copilot там будет prompt). 23.600.0
payload_prompt_text Если payload_provider = prompt, будет содержаться сырая инструкция препромпта. Это не обработанный препромпт для самостоятельного анализа. Подробнее в документации по промптам. 23.800.0
payload_markers Массив дополнительных маркеров от пользователя (original_message, user_message, language), использованный при формировании промпта. Подробнее в документации по промптам. 23.800.0
payload_role Роль (инструкция), использованная при формировании промпта. В GPT-подобных системах вы должны отправлять эту роль как системную в массиве сообщений. 23.800.0
context. Массив предшествующих сообщений в хронологическом порядке. Например, список комментариев к посту. Первым в таком списке контекста считается авторское сообщение (сам пост).

Важно:

  • Объем контекста, отправляемого вашему провайдеру, зависит от указанного вами объема провайдера и типа подсчета (подробнее в документации по провайдеру). По умолчанию метод подсчета "токены", объем 16K.
  • Отправлять контекст непосредственной нейронке вы должны только если передан параметр collect_context, равный true (1). В остальных случаях он передается как доп.информация на ваше усмотрение.

23.800.0
max_tokens Максимальное число лексем. Параметр контролирует длину вывода. Необязательный.
temperature Температура. Параметр контролирует случайность вывода (низкие значения делают вывод более сфокусированным и детерминированным). Обязательный.

Пример

Допустим, к вам приходит (помимо прочей информации) три массива данных.

  • prompt - содержит текущий запрос, это просто текст;
  • payload_role - некий текст, содержащий инструкции;
  • context - массив (допустим, тоже не пустой).

В этом случае, результирующий массив мы получаем как:

[
	[
		'role' => 'system',
		'content' => $payload_role,
	],
	[
		// весь массив context, или его часть, если вы хотите сэкономить запрос
		// но помните, что он идет в хронологическом порядке (снизу самые последние сообщения)
	],
	[
		'role' => 'user',
		'content' => $prompt,// это текущий запрос, и он НЕ входит в контекст
	]
];

Пользовательские комментарии

Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
© «Битрикс», 2001-2024, «1С-Битрикс», 2024