Веб-сервис взаимодействия с ИИ¶

Веб-сервис предназначен для работы с LLM по протоколу OpenAI. Он абстрагирует потребителя от деталей протокола, обеспечивая необходимое взаимодействие и предоставляя при этом потребителю простой API для работы в режиме чата с использованием файловых вложений.

Tip

arti входит в состав TESSA, начиная с версии 4.2.

Important

Для работы с модулем ИИ нужна соответствующая лицензия.

Настройки сервиса `arti`¶

Для корректной работы веб-сервиса arti необходимо задать ряд обязательных параметров.

Important

Настройки, заданные в аргументах командной строки, имеют приоритет перед настройками, заданными в конфигурационном файле.

Аргументы командной строки¶

Аргументы командной строки и их назначение:

Аргумент	Описание
`-address <address>`	Указывает адрес в формате `host:port`, который будет использован `arti` для работы. По умолчанию `localhost:20202`
`-logsPath <path>`	Указывает путь к директории для создания файлов протоколов. По умолчанию `logs`
`-configPath <config>`	Указывает путь к файлу конфигурации в формате YAML, содержащему настройки `arti`. По умолчанию `config.yaml`
`-verbose`	Флаг использования многословного режима. В этом режиме на консоль будут выводится подробные диагностические сообщения. По умолчанию не задан
`-dbg`	Флаг использования отладочного режима. Рекомендуется использовать только в диагностических целях для проверки работы сервиса. По умолчанию не задан

Tip

Рекомендуется указывать номер порта целым числом больше 10000, не кратным 10, что в большей степени поможет исключить попытку запустить arti на уже занятом кем-то порту, например, 20202. Как правило, номера портов меньше 8000 (реже - 10000) резервируются системными службами и приложениями.

Конфигурационный файл¶

Important

Для удобства работы и проверки корректности конфигурационного файла создана схема config.schema.json, которая отражает самое актуальное состояние настроек arti.

Для создания и редактирования конфигурационного файла рекомендуется использовать редактор или IDE с поддержкой YAML Schema, например, VS Code с установленным расширением redhat.vscode-yaml. В этом случае будет обеспечена полноценная работа технологии IntelliSense.

Конфигурационный файл должен иметь формат YAML и соответствовать схеме config.schema.json. При этом сам файл может иметь любое имя.

Далее представлено описание схемы конфигурационного файла. Корневым является YAML объект. Обязательные поля помечены звёздочкой.

Поле	Описание
`address`	Адрес для прослушивания в формате: `Host:Port`. По умолчанию `localhost:20202`
`timeout`	Таймаут ответа модели, задаваемый в формате `time.Duration` языка Go. По умолчанию `3m`
`logsPath`	Путь к директории с протоколами работы. По умолчанию `logs`
`fileCachePath`	Путь к директории для хранения временных файлов. По умолчанию `file_cache`
`accessTokens` *	Перечень токенов доступа. Ключ - название токена, значение - сам токен доступа
`endpoints`	Глобальные именованные настройки маршрутов (провайдеров) для доступа к моделям. Используется чтобы не дублировать роуты, ключи доступа, таймауты и прокси в каждой модели, если модели подключаются к одному и тому же удалённому хосту/провайдеру
`tokenizer` *	Модель токенизатора. Доступные значения: `gpt-5` `gpt-4` `gpt-oss` `qwen3` `qwen2.5`
`chunking` *	Параметры для разбиения текста
`localRag` *	Настройки для локального RAG
`maxFileSize` *	Максимальный размер файла в байтах
`maxFilesSize` *	Максимальный размер всех файлов в байтах
`prompts`	Специализированные промпты
`denseEmbeddingModels` *	Описание доступных плотных моделей эмбеддингов
`rerankModels` *	Описание доступных моделей переранжирования
`textGenerationModels` *	Описание доступных генеративных моделей

Tip

Токены доступа accessTokens рекомендуется генерировать при помощи утилиты командной строки token, находящейся рядом с arti.

Поле endpoints главного объекта конфигурационного файла. YAML объект, в котором ключ - является псевдонимом, а значение YAML объектом, описывающим провайдер, со следующей структурой.

Поле	Описание
`endpoint` *	Базовый путь провайдера. Например, `http://127.0.0.1:11434/v1` или `https://api.llm.com`
`apiKey` *	Аутентификационный ключ для провайдера
`additionalHeaders`	Дополнительные HTTP-заголовки. Ключ - имя заголовка, значение - содержимое заголовка. Можно использовать для передачи идентификатора проекта, требуемого `Yandex API`
`timeout`	Таймаут ответа модели, задаваемый в формате `time.Duration` языка Go. Значение переопределяет настройку `timeout` из главного объекта конфигурационного файла
`ignoreCertErrors`	Признак, что нужно игнорировать ошибки SSL сертификатов
`proxy`	Настройки прокси сервера

Note

В поле endpoint для пути необходимо явно указывать суффикс /v1.

Important

Поле apiKey относится к чувствительной информации. В случае необходимости передачи конфигурационного файла рекомендуется очищать или удалять это поле.

Important

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

Поле endpoints → proxy. YAML объект, в котором определены настройки прокси сервера.

Поле	Описание
`url` *	Адрес прокси сервера в формате `scheme://host:port`
`user`	Имя пользователя
`password`	Пароль пользователя

Note

Поля user и password должны быть заданы совместно.

Поле chunking главного объекта конфигурационного файла. YAML объект, который определяет параметры для разбиения текста на фрагменты.

Поле	Описание
`splitter` *	Тип разделителя текста на фрагменты. Доступные значения: `character` - простой разделитель по одному разделителю (символы) `recursive_character` - рекурсивный разделитель по символам `token` - разделитель по токенам фиксированного размера `recursive_token` - рекурсивный разделитель по токенам `markdown_character` - разделитель markdown-документа с длиной фрагментов в символах `markdown_token` - разделитель markdown-документа с длиной фрагментов в токенах
`chunkSize` *	Длина фрагмента текста. Зависит от типа разделителя
`chunkOverlap` *	Длина перекрытия фрагмента текста. Зависит от типа разделителя

Tip

Значение chunkSize содержит в себе значение chunkOverlap.

Поле localRag главного объекта конфигурационного файла. YAML объект, который задаёт настройки для локального RAG.

Поле	Описание
`disabled`	Признак, что локальный RAG не используется. По умолчанию `false`
`tokenizer`	Модель токенизатора. Значение переопределяет настройку `tokenizer` из главного объекта конфигурационного файла
`chunking`	Параметры для разбиения текста. Значение переопределяет настройку `chunking` из главного объекта конфигурационного файла
`retrievalLimit` *	Максимальное количество фрагментов в результатах поиска
`retrievalSimilarity` *	Порог, начиная с которого фрагменты считаются подобными искомому запросу в пределах [0.0;1.0]
`embeddingModel`	Идентификатор плотной модели эмбеддингов из перечня `denseEmbeddingModels`, используемой для поиска

Note

Если для поля embeddingModel не задано значение, то используется первая доступная модель из перечня denseEmbeddingModels.

Поле prompts главного объекта конфигурационного файла. YAML объект, который определяет специализированные промпты.

Поле	Описание
`jsonObject`	Промпт для структурированного вывода при использовании типов `text`, `json_object` в поле `structuredOutput` для используемой модели

YAML объект model, который задаёт базовые настройки для моделей в объектах denseEmbeddingModel, rerankModel, textGenerationModel.

Поле	Описание
`id` *	Уникальный идентификатор модели в arti. Например, `test-model-v1:5b/local`
`name` *	Уникальное имя модели, отображаемое пользователю. Например, `Test model V1 5b (local version)`
`family` *	Название семейства моделей. Например, `Testing`
`model` *	Имя модели в провайдере. Например, `model-v1:5b`
`disabled`	Признак, что модель отключена и не используется. По умолчанию `false`
`contextLength` *	Размер контекста модели в токенах
`kwargs`	Дополнительные параметры, которые будут переданы в теле запроса к модели в формате JSON
`endpoint` *	Имя глобального `endpoint`-а в настройке `endpoints` из главного объекта конфигурационного файла или базовый путь провайдера, если перечисляются поля из объекта `endpoint`
…`endpoint`	Поля из объекта `endpoint`

Important

При задании в поле endpoint ссылки на глобальный эндпойнт, поля apiKey, ignoreCertErrors, proxy являются не обязательными, иначе - обязательными.

Tip

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

Поле denseEmbeddingModel главного объекта конфигурационного файла. YAML объект, который задаёт настройки для модели плотных эмбеддингов.

Поле	Описание
`dimensions`	Размер выходного вектора. Значение является опциональным и не используется для локального RAG
`tokenizer`	Модель токенизатора. Значение переопределяет настройку `tokenizer` из главного объекта конфигурационного файла
`chunking`	Параметры для разбиения текста. Значение переопределяет настройку `chunking` из главного объекта конфигурационного файла
`prefixes`	Настройки префиксов для модели эмбеддингов
…`model` *	Базовые настройки для модели в arti

Tip

Значение dimensions может быть не задано - тогда используется значение по умолчанию для используемой model.

Если значение для dimensions задано, то оно может быть переопределено в запросе к веб-сервису arti на вычисление эмбеддингов. По умолчанию при формировании запроса из веб-сервиса web передаётся размерность вектора.

Поле denseEmbeddingModel → prefixes, YAML объект, который определяет настройки префиксов для модели плотных эмбеддингов.

Поле	Описание
`query`	Префикс для запроса
`document`	Префикс для документа

Поле rerankModels главного объекта конфигурационного файла. YAML объект, который задаёт настройки для модели переранжирования.

Поле	Описание
`top_n`	Количество документов, возвращаемых после сортировки. Если не задано, используется значение по умолчанию модели
`kwargs`	Дополнительные параметры, которые будут переданы в теле запроса к модели в формате JSON
…`model` *	Базовые настройки для модели в arti

Поле textGenerationModels главного объекта конфигурационного файла. YAML список YAML объектов следующей структуры.

Поле	Описание
`systemRole`	Имя роли для системного сообщения. По умолчанию `developer`
`structuredOutput`	Режим получения структурированного вывода (json). По умолчанию `text`. Доступные значения: `json_schema` - использовать одноимённый формат результата `json_object` - использовать системный промпт для генерации json и специальный формат результата `text` - использовать системный промпт для генерации json (наиболее общий и универсальный вариант) `function_call` - использовать принудительный вызов функции `tool_call` - использовать принудительный вызов инструмента с указанием его имени (поддерживается не всеми моделями) `tool_call_required` - использовать принудительный вызов инструмента без указания его имени (не такой явный как tool_call)
`capabilities`	Описание возможностей модели
`ocr`	Признак, что модель используется исключительно для задач OCR. По умолчанию `false`
`localRag`	Настройки для локального RAG. Значение переопределяет настройку `localRag` из главного объекта конфигурационного файла
`prompts`	Специализированные промпты. Значение переопределяет настройку `prompts` из главного объекта конфигурационного файла
`maxFileSize`	Максимальный размер файла в байтах. Значение переопределяет настройку `maxFileSize` из главного объекта конфигурационного файла
`maxFilesSize`	Максимальный размер всех файлов в байтах. Значение переопределяет настройку `maxFilesSize` из главного объекта конфигурационного файла
…`model` *	Базовые настройки для модели в arti

Поле textGenerationModels → capabilities. YAML объект.

Поле	Описание
`imageInput`	Признак, что модель поддерживает распознавание изображений
`videoInput`	Признак, что модель поддерживает распознавание видео
`audioInput`	Признак, что модель поддерживает распознавание аудио
`imageOutput`	Признак, что модель поддерживает генерацию изображений

Important

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

Следует задавать только актуальные возможности модели.

Пример конфигурационного файла.

# yaml-language-server: $schema=config.schema.json
address: "localhost:20202"
timeout: 3m

logsPath: "logs"
fileCachePath: "file_cache"

accessTokens:
  testing: сгенерированный_токен_доступа

endpoints:
  localhost:
    endpoint: "http://127.0.0.1:11434/v1"
    apiKey: none
    ignoreCertErrors: false

chunking:
  splitter: recursive_token
  chunkSize: 512
  chunkOverlap: 64

localRag:
  disabled: false
  retrievalLimit: 5
  retrievalSimilarity: 0.6
  embeddingModel: "test-dense-embedding-v1:1b/local"

maxFileSize: 10048576
maxFilesSize: 500048576

prompts:
  jsonObject: |-
      You must format your output as a JSON value that adheres to a given "JSON Schema" instance.

      "JSON Schema" is a declarative language that allows you to annotate and validate JSON documents.

      For example, the example "JSON Schema" instance {"properties": {"foo": {"description": "a list of test words", "type": "array", "items": {"type": "string"}}}, "required": ["foo"]}
      would match an object with one required property, "foo". The "type" property specifies "foo" must be an "array", and the "description" property semantically describes it as "a list of test words". The items within "foo" must be strings.
      Thus, the object {"foo": ["bar", "baz"]} is a well-formatted instance of this example "JSON Schema". The object {"properties": {"foo": ["bar", "baz"]}} is not well-formatted.

      Your output will be parsed and type-checked according to the provided schema instance, so make sure all fields in your output match the schema exactly and there are no trailing commas!

      Here is the JSON Schema instance your output must adhere to. Include the enclosing markdown codeblock:
      ~~~json
      {{.schema}}
      ~~~

denseEmbeddingModels:
  - id: "test-dense-embedding-v1:1b/local"
    name: "Test dense embedding v1 1B (local version)"
    family: "Testing"
    model: "dense-embedding-v1:1b"
    disabled: false
    dimensions: 1536
    contextLength: 32000
    prefixes:
      query: |-
        Given a question, retrieve passages that answer the question.
        Query:
      document: |-
        Passage:
    endpoint: localhost

rerankModels:
  - id: "test-rerank-v1:1b/local"
    name: "Test rerank v1 1B (local version)"
    family: "Testing"
    model: "rerank-v1:1b"
    disabled: false
    contextLength: 32000
    topN: 5
    endpoint: localhost

textGenerationModels:
  - id: "test-model-v1:5b/local"
    name: "Test model V1 5b (local version)"
    family: "Testing"
    model: "model-v1:5b"
    contextLength: 40960
    systemRole: "system"
    structuredOutput: "text"
    capabilities:
      imageInput: true
    ocr: false
    localRag:
      disabled: true
    disabled: false
    endpoint: "https://api.llm.com"
    apiKey: none
    ignoreCertErrors: false

Настройка веб сервера TESSA для работы с arti¶

Для использования arti из веб сервера TESSA, chronos и tadmin необходимо произвести настройку в конфигурационном файле app.json, которая описана в здесь.

Установка в Windows (`IIS`)¶

Для удобства управления рекомендуется устанавливать arti как приложение, работающее под управлением IIS. Этот процесс рассмотрен далее.

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

Пул должен иметь следующие настройки.

Tip

Если требуется, можно использовать другую схему именования.

Для данного пула рекомендуется использовать ту же учётную запись, которая была задана при установке веб-приложения TESSA (как правило, tessa). Для этого необходимо выделить пул и открыть его Дополнительные параметры.

Чтобы установить учётную запись, нужно нажать на кнопку ....

В открывшемся диалоге выбрать пункт Особая учетная запись, далее нажать на кнопку Установить... и в открывшемся окне указать нужную учетную запись (в формате имя домена\имя учетной записи и пароль). В результате требуемая запись будет установлена:

Tip

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

Необходимо настроить пул, чтобы он сразу запускал приложения и не останавливал их при простое:

параметр Режим запуска должен быть равен AlwaysRunning;
параметр Тайм-аут простоя (в минутах) должен быть равен 0;
параметр Максимальное число рабочих процессов должен быть равен 1 (по умолчанию).

На этом настройка пула завершена.

Самым простым способом создания приложения arti является копирование соответствующего каталога из архива установки TESSA в целевую директорию, в которой находится директория web (в случае стандартной установки это C:\inetpub\wwwroot\tessa).

Добавление виртуального каталога

Tip

Если директория arti появилась в менеджере IIS в результате предыдущего шага, добавление виртуального каталога пропускается. Далее выполняется преобразование каталога в приложение.

Если директория arti не появилась в менеджере IIS, необходимо добавить ссылку на неё. Выбрать директорию tessa в составе сайта (в данном случае Default Web Site) и в контекстном меню выбрать пункт Добавить виртуальный каталог.

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

Преобразование каталога в приложение

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

В открывшемся диалоге активировать настройку Включить предварительную загрузку и настроить пул приложений на созданный ранее (arti), нажав на кнопку Выбрать.

В появившемся диалоге выбрать нужный пул arti и нажать кнопку OK, чтобы подтвердить выбор.

В исходном окне также нажать кнопку OK.

Проверка конфигурационного файла arti web.config

Файл web.config для arti включен в состав поставки. Он должен выглядеть следующим образом.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
    </handlers>
    <!-- В атрибуте arguments указываются аргументы командной строки. -->
    <aspNetCore processPath=".\arti.exe" arguments="-configPath config.yaml" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="true" requestTimeout="00:10:00" startupTimeLimit="3600" hostingModel="OutOfProcess">
      <environmentVariables>
        <!-- В атрибуте value можно указать номер порта для управляемого IIS приложения. -->
        <environmentVariable name="ASPNETCORE_PORT" value="20202" />
      </environmentVariables>
    </aspNetCore>
  </system.webServer>
</configuration>

Следует также обратить внимание на следующие моменты.

Аргументы запуска arti настраиваются в узле configuration → system.webServer → aspNetCore, атрибут arguments.

Порт для работы arti под управлением IIS указывается в узле configuration → system.webServer → aspNetCore → environmentVariables → environmentVariable (name="ASPNETCORE_PORT"), атрибут value.

Установка в Linux¶

Необходимо скопировать каталог arti из директории linux, расположенной в директории основного дистрибутива, в директорию, в которой расположен веб-сервис TESSA. Если выполнялись пункты стандартной инструкции, то базовый путь /home/tessa/tessa/.

В архиве сборки выполните скрипт linux/init.sh, как указано в инструкции, или добавьте разрешение на исполняемый файл arti вручную. Для этого необходимо перейти в директорию arti в директории назначения и выполнить команду:

sudo chmod 755 arti

Данная команда устанавливает флаг “Исполняемый” для файла arti.

Important

arti необходимо настроить для той же системы управления сервисами, для которой настроена TESSA.

Для Calculate Linux используйте подраздел System-V, для всех остальных описанных дистрибутивов подойдёт System-D.

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

sudo stat /sbin/init

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

Настройка службы для `systemd`¶

Рассмотрим, как настроить службу arti для системы управления службами systemd.

В директории /etc/systemd/system/ создать файл arti.service со следующим содержимым:

[Unit]
Description=Arti - platform web service for AI interaction

[Service]
WorkingDirectory=/home/tessa/tessa/arti
ExecStart=/home/tessa/tessa/arti/arti -configPath config.yaml
Restart=always
RestartSec=10
SyslogIdentifier=arti
User=tessa

[Install]
WantedBy=multi-user.target

Important

Переменные файла конфигурации User, WorkingDirectory, ExecStart зависят от установки arti. В случае необходимости запуска от другого пользователя, необходимо указать его имя в User. В случае установки arti в директорию, отличную от /home/tessa/tessa/, необходимо изменить переменные WorkingDirectory, ExecStart таким образом, чтобы они соответствовали директории установки arti.

Настроить автозапуск сервиса arti и запустить его, выполнив команду:

sudo systemctl enable arti

Tip

Здесь arti соответствует имени сервиса arti.service без расширения .service.

Управление сервисом.

Запуск:
```
sudo systemctl start arti
```
Останов:
```
sudo systemctl stop arti
```
Перезапуск:
```
sudo systemctl restart arti
```
Получение сведений о текущем состоянии:
```
sudo systemctl status arti
```

Настройка службы для `systemv`¶

Рассмотрим, как настроить службу arti для системы управления службами systemv.

Необходимо перейти в директорию /etc/init.d/ и создать в ней файл arti следующего содержимого:

#!/bin/sh
### BEGIN INIT INFO
# Provides:          arti - platform web service for AI interaction
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Stop/start arti
### END INIT INFO

PATH=/sbin:/usr/sbin:/bin:/usr/bin

if [ -L $0 ]; then
    SCRIPTNAME=`/bin/readlink -f $0`
else
    SCRIPTNAME=$0
fi

NAME="arti"
DAEMONUSER="tessa"
DAEMONDIR="/home/$DAEMONUSER/tessa/arti"
DAEMON="$DAEMONDIR/arti"
DAEMON_ARGS="-configPath config.yaml"
LOGDIR="/home/$DAEMONUSER/tessa/logs/"
LOGFILE="$LOGDIR/arti.log"
PIDFILE="/var/run/arti.pid"

# Exit if the package is not installed
[ -x "$DAEMON" ] || exit 0

. /lib/init/vars.sh

. /lib/lsb/init-functions

do_start()
{
    log_daemon_msg "Starging system $NAME daemon"
    su - $DAEMONUSER -c "mkdir -p '$LOGDIR'"
    su - $DAEMONUSER -c "rm -f '$LOGFILE'"
    start-stop-daemon --start --name "$NAME" --user $DAEMONUSER \
        --background --make-pidfile --pidfile "$PIDFILE" \
        --stdout "$LOGFILE" --stderr "$LOGFILE" \
        --chdir "$DAEMONDIR" \
        --exec "$DAEMON" -- $DAEMON_ARGS
    RETVAL="$?"
    log_end_msg $?
    return "$RETVAL"
}

do_stop()
{
    # Return
    #   0 if daemon has been stopped
    #   1 if daemon was already stopped
    #   2 if daemon could not be stopped
    #   other if a failure occurred
    log_daemon_msg "Stopping system $NAME daemon"
    start-stop-daemon --stop --quiet --oknodo --retry=5 --pidfile "$PIDFILE"
    RETVAL="$?"
    log_daemon_msg $?
    rm -f $PIDFILE
    return "$RETVAL"
}

case "$1" in
    start)
        [ "$VERBOSE" != no ] && log_daemon_msg "Starting " "$NAME"
        do_start
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
    stop)
        [ "$VERBOSE" != no ] && log_daemon_msg "Stopping " "$NAME"
        do_stop
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
  restart)
        log_daemon_msg "Restarting $DESC" "$NAME"
        do_stop
        case "$?" in
            0|1)
                do_start
                case "$?" in
                    0) log_end_msg 0 ;;
                    1) log_end_msg 1 ;; # Old process is still running
                    *) log_end_msg 1 ;; # Failed to start
                esac
                ;;
            *)
                # Failed to stop
                log_end_msg 1
                ;;
        esac
        ;;
    status)
        status_of_proc -p "$PIDFILE" "$DAEMON" "$NAME" && exit 0 || exit $?
        ;;
    *)
        echo "Usage: $SCRIPTNAME {start|stop|restart|status}" >&2
        exit 3
        ;;
esac

exit $RETVAL

Tip

Для создания и редактирования файла допускается использовать команду sudo nano /etc/init.d/arti, или команду вызова другого текстового редактора от имени пользователя с повышенными привилегиями.

Important

Переменные скрипта DAEMONUSER, DAEMONDIR, LOGDIR зависят от установки arti. В случае необходимости запуска от другого пользователя необходимо указать его имя в DAEMONUSER. В случае установки arti в директорию, отличную от /home/$DAEMONUSER/tessa/, изменить переменные DAEMONDIR, LOGDIR таким образом, чтобы они соответствовали директории установки arti.

Important

Необходимо ознакомиться с документацией start-stop-daemon для вашей операционной системы. В некоторых версиях вместо двух аргументов --stdout и --stderr используется один --output. В этом случае нужно скорректировать соответствующую часть функции do_start (--stdout "$LOGFILE" --stderr "$LOGFILE" заменить на --output "$LOGFILE").

Необходимо задать права на исполнение данного сервиса.

sudo chmod 755 /etc/init.d/arti

Добавление сервиса в автозапуск.

Наиболее надёжный способ:

sudo ln -s /etc/init.d/arti /etc/rc0.d/S01arti

Если доступна команда chkconfig:
```
sudo chkconfig --add /etc/init.d/arti
```
Если доступна команда update-rc.d:
```
sudo update-rc.d arti defaults
```
Если доступна команда rc-update:
```
sudo rc-update add arti default
```

Управление сервисом.

Запуск:
```
sudo service arti start
```
Останов:
```
sudo service arti stop
```
Перезапуск:
```
sudo service arti restart
```
Получение сведений о текущем состоянии:
```
sudo service arti status
```

Описание REST API¶

Important

Самое актуальное описание предоставляемого REST API содержится в файле arti.openapi.yaml, входящем в поставку arti.

Общие маршруты:
- GET /hcheck - проверка работоспособности;
- GET /check - проверка доступа к моделям ИИ.
Маршруты работы с моделями ИИ:
- GET /v1/models - получить список доступных моделей.
- POST /v1/chat - генерация ответа ИИ по чату сообщений.
- POST /v1/recognize - распознавание текста на изображении.
- POST /v1/embeddings - получение векторного представления для заданного входного значения.
- POST /v1/rerank - переранжирование списка документов относительно заданного запроса.

Important

Для всех запросов, кроме /hcheck и /check, требуется передача токена доступа в заголовке Authorization: Bearer <token>.

`GET /hcheck` проверка работоспособности¶

Возвращает текстовый ответ с состоянием работоспособности приложения.

Ответы

Код	Формат	Описание
200	`text/plain`	Текущее состояние работы

При нормальном выполнении выводится одна из строк:

Healthy - компонент работоспособен, нормальная работа;
Unhealthy - компонент не работоспособен, требуется перезапуск.

Tip

Необходимо использовать этот маршрут для проверок работоспособности компонента типа health check в среде, в которой запускается сервис arti. Например, systemd в ОС Linux или Docker.

`GET /check` проверка доступа к моделям ИИ¶

Возвращает общую диагностическую информацию о доступных моделях и их состоянии.

Ответы

Код	Формат	Описание
200	`text/plain`	Диагностическая информация о моделях

`GET /v1/models` получение списка доступных моделей¶

Возвращает список доступных моделей и их возможностей.

Запрос

Запрос не содержит тела. Тип моделей передаётся в обязательном query-параметре type.

Параметр	Обязательный	Описание
`type`	Да	Тип моделей, список которых необходимо получить. Поддерживаются значения: `TextGeneration` - модели генерации текста `DenseEmbedding` - модели плотных векторных представлений `Rerank` - модели переранжирования

Ответы

Код	Формат	Описание
200	`application/json`	`JSON` массив с информацией о доступных моделях
404	`plain/text`	Ответ при неудачной авторизации

При нормальном выполнении выводится JSON массив объектов со следующей структурой:

Поле	Описание
`id`	Идентификатор модели, передаваемый в запросах к модели
`family`	Название семейства моделей, к которому относится модель
`name`	Уникальное название модели, отображаемое пользователю
`ocr`	Признак, что модель используется исключительно для целей OCR
`capabilities`	Массив строк, описывающих возможности модели

`POST /v1/chat` взаимодействие с ИИ на основе чата¶

Взаимодействие с моделями генеративного ИИ по протоколу чата.

Запрос

Мультипарт

Поле	Описание
`request`	Сообщения чата
`files`	Файлы вложений чата, если есть

Запрос является JSON объектом следующей структуры.

Поле	Описание
`model`	Идентификатор модели. Один из возвращаемых роутом `/v1/models`
`messages`	Список сообщений, составляющий чат. Запросы пользователя, ответы ИИ и вызовы инструментов (функций)
`local_rag`	Флаг, нужно ли принудительно включить или выключить локальный RAG для данного запроса. Если не задано, используются настройки модели
`instructions`	Системное сообщение, добавляемое первым в контекст модели, задающее руководящие инструкции для использования моделью
`json_schema`	Описание JSON схемы, согласно которой должна ответить модель
`tools`	Опциональный список инструментов (функций), которые модель может использовать
`temperature`	Какую температуру использовать при генерации ответа. Значения из отрезка [0.0;2.0]
`top_p`	Альтернатива указания температуры, называемая выборкой ядра, где модель учитывает результаты токенов с вероятностью массы top_p

Сообщение чата является JSON объектом следующей структуры.

Поле	Описание
`content`	Массив объектов, текстовых и файловых частей сообщения
`role`	Имя роли. Поддерживаются: `user` - сообщение пользователя `assistant` - сообщение ИИ `tool` - с результатом выполнения инструмента
`name`	Опциональное имя участника чата
`tool_calls`	Опциональный список вызовов инструментов, сгенерированных моделью. Используется только для роли `assistant`
`tool_call_id`	Опциональный идентификатор вызова инструмента, на который отвечает сообщение. Используется только для роли `tool`

Текстовая часть сообщения является JSON объектом следующей структуры.

Поле	Описание
`type`	Тип части сообщения. Для тестовой части всегда `text`
`text`	Текст части сообщения

Файловая часть сообщения является JSON объектом следующей структуры.

Поле	Описание
`type`	Тип части сообщения. Для файловой части всегда `file`
`name`	Имя файла
`id`	Уникальный идентификатор файла. Должен соответствовать идентификатору приложенного файла в `multipart`-е
`fileType`	Тип файла. Поддерживаются: `text` - текстовый файл `image` - изображение
`url`	Ссылка на файл, как на доступный извне ресурс. Только для изображений

Вызовов инструмента является JSON объектом следующей структуры.

Поле	Описание
`id`	Идентификатор вызова
`name`	Имя вызываемого инструмента (функции)
`arguments`	Аргументы в формате JSON для вызываемого инструмента (функции)

Инструмент (функция) чата является JSON объектом, который представляет собой описание JSON схемы.

Описание JSON схемы является JSON объектом следующей структуры.

Поле	Описание
`description`	Описание того, для чего используется формат
`name`	Имя схемы
`schema`	Описание JSON схемы

Ответы

Код	Формат	Описание
200	`application/json`	`JSON` объект ответа модели
400	`plain/text`	Ответ при ошибках запроса
404	`plain/text`	Ответ при неудачной авторизации

В случае нормального выполнения, формируется ответ в виде JSON объекта следующей структуры.

Поле	Описание
`model`	Идентификатор модели. Один из возвращаемых роутом `/models`
`created`	Время создания ответа в UTC
`messages`	Массив строк. Сгенерированные моделью ответы. В большинстве случаев 1.
`tool_calls`	Опциональный список вызовов инструментов, сгенерированных моделью. Используется только для роли `assistant`
`error`	Сообщение об ошибке
`usage`	Статистика по использованным токенам

Статистика по использованным токенам является JSON объектом следующей структуры.

Поле	Описание
`prompt`	Количество входных токенов
`completion`	Количество сгенерированных токенов
`total`	Общее количество токенов

`POST /v1/recognize` взаимодействие с ИИ для анализа изображений¶

Взаимодействие с моделями ИИ для целей анализа изображения.

Запрос

Мультипарт

Поле	Описание
`request`	Запрос на распознавание данных
`file`	Контент файла из запроса

Запрос является JSON объектом следующей структуры.

Поле	Описание
`model`	Идентификатор модели с поддержкой видения. Один из возвращаемых роутом `/v1/models`
`name`	Имя файла
`fileType`	Тип файла. Должен быть `image`
`prompt`	Промт к ИИ-модели с запросом на распознавание текста
`temperature`	Какую температуру использовать при генерации ответа. Значения из отрезка [0.0;2.0]
`top_p`	Альтернатива указания температуры, называемая выборкой ядра, где модель учитывает результаты токенов с вероятностью массы top_p

Ответы

Код	Формат	Описание
200	`application/json`	`JSON` объект с ответом модели
400	`plain/text`	Ответ при ошибках запроса
404	`plain/text`	Ответ при неудачной авторизации

В случае нормального выполнения, формируется ответ в виде JSON объекта следующей структуры.

Поле	Описание
`name`	Имя файла
`text`	Распознанный текст
`usage`	Статистика по использованным токенам

Статистика по использованным токенам является JSON объектом следующей структуры.

Поле	Описание
`prompt`	Количество входных токенов
`completion`	Количество сгенерированных токенов
`total`	Общее количество токенов

`POST /v1/embeddings` взаимодействие с ИИ для создания числовых векторов¶

Взаимодействие с моделями ИИ для создания числового векторного представления для входного значения.

Запрос

Запрос является JSON объектом следующей структуры.

Поле	Описание
`model`	Идентификатор модели для вычисления векторного представления. Один из возвращаемых роутом `/v1/models`
`input`	Входной текст для генерации векторного представления, представленный в виде строки или массива строк
`kind`	Вид входного значения. Может быть `"query"` или `"document"`
`dimensions`	Количество измерений, которое должны иметь результирующие выходные числовые вектора. Если не задан, то значение берётся из конфигурационного файла

Ответы

Код	Формат	Описание
200	`application/json`	`JSON` объект с ответом модели
400	`plain/text`	Ответ при ошибках запроса
404	`plain/text`	Ответ при неудачной авторизации

В случае нормального выполнения, формируется ответ в виде JSON объекта следующей структуры.

Поле	Описание
`data`	Массив числовых векторов, сгенерированных моделью
`usage`	Статистика по использованным токенам

Массив числовых векторов является JSON объектом следующей структуры.

Поле	Описание
`index`	Индекс вектора в массиве числовых векторов
`embedding`	Числовой вектор, представляющий собой список чисел с плавающей запятой. Длина вектора зависит от модели
`chunk`	Опциональный фрагмент (чанк), для которого был вычислен числовой вектор. Значение актуально если входное значение было представлено в виде одной строки и она не вмещалась в единичный фрагмент

Статистика по использованным токенам является JSON объектом следующей структуры.

Поле	Описание
`prompt`	Количество входных токенов
`completion`	Количество сгенерированных токенов
`total`	Общее количество токенов

`POST /v1/rerank` переранжирование документов¶

Взаимодействие с моделями ИИ для переранжирования списка документов относительно заданного запроса.

Запрос

Запрос является JSON объектом следующей структуры.

Поле	Описание
`model`	Идентификатор модели переранжирования. Один из возвращаемых роутом `/v1/models?type=Rerank`
`query`	Поисковый запрос, относительно которого выполняется переранжирование
`documents`	Массив строк - список документов для переранжирования (минимум 1 элемент)
`top_n`	Опционально, количество документов, возвращаемых после сортировки. Если не задано, используется значение из конфигурации

Ответы

Код	Формат	Описание
200	`application/json`	`JSON` объект с результатами переранжирования
400	`plain/text`	Ответ при ошибках запроса
404	`plain/text`	Ответ при неудачной авторизации

В случае нормального выполнения, формируется ответ в виде JSON объекта следующей структуры.

Поле	Описание
`results`	Массив объектов с результатами переранжирования, упорядоченный по убыванию релевантности
`usage`	Статистика по использованным токенам

Каждый объект в results имеет следующую структуру.

Поле	Описание
`index`	Индекс документа в исходном списке документов
`relevance_score`	Оценка релевантности документа запросу (число с плавающей запятой)

Статистика по использованным токенам является JSON объектом следующей структуры.

Поле	Описание
`prompt`	Количество входных токенов
`completion`	Количество сгенерированных токенов
`total`	Общее количество токенов

Веб-сервис взаимодействия с ИИ¶

Настройки сервиса arti¶

Аргументы командной строки¶

Конфигурационный файл¶

Настройка веб сервера TESSA для работы с arti¶

Установка в Windows (IIS)¶

Установка в Linux¶

Настройка службы для systemd¶

Настройка службы для systemv¶

Описание REST API¶

GET /hcheck проверка работоспособности¶

GET /check проверка доступа к моделям ИИ¶

GET /v1/models получение списка доступных моделей¶

POST /v1/chat взаимодействие с ИИ на основе чата¶

POST /v1/recognize взаимодействие с ИИ для анализа изображений¶

POST /v1/embeddings взаимодействие с ИИ для создания числовых векторов¶

POST /v1/rerank переранжирование документов¶

Настройки сервиса `arti`¶

Установка в Windows (`IIS`)¶

Настройка службы для `systemd`¶

Настройка службы для `systemv`¶

`GET /hcheck` проверка работоспособности¶

`GET /check` проверка доступа к моделям ИИ¶

`GET /v1/models` получение списка доступных моделей¶

`POST /v1/chat` взаимодействие с ИИ на основе чата¶

`POST /v1/recognize` взаимодействие с ИИ для анализа изображений¶

`POST /v1/embeddings` взаимодействие с ИИ для создания числовых векторов¶

`POST /v1/rerank` переранжирование документов¶