Help:XSvacer:AIAssistant

Данная функциональность входит в набор расширений XSvacer

Поддержка ИИ-ассистента для разметки предупреждений

Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.

ИИ-ассистент предназначен для разметки предупреждений статусами Confirmed и False Positive, которые были предсказаны моделью машинного обучения.

Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.

Активация и запуск функциональности

ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:

1. Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту;
2. Развернуть и запустить сервис ИИ-ассистента;

Активация функциональности xsvacer при запуске Svacer

Для активации функциональности необходимо указать флаг --xsvacer.features aiAssistant при запуске Svacer.

Настройка доступа к ИИ-ассистенту в Svacer

По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу http://localhost:8081/

Изменить адрес, по которому Svacer будет подключаться к ИИ-ассистенту, можно одним из способов:

1. При запуске Svacer установить переменную окружения XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/
2. В конфигурационном файле svacer.cfg добавить раздел

...
xsvacer:
  ...
  aiAssistant:
    assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/
...

Настройка значения флага --public-url

В связи с тем, что ИИ-ассистент использует REST API Svacer, необходимо добавить url ИИ-ассистента в список публичных url Svacer. Это можно сделать, добавив при запуске Svacer флаг:

--public-url {url ИИ-ассистента}

Пример:

--xsvacer.features aiAssistant --public-url https://svacer-ai-demo.ispras.ru

Данная настройка связана с функциональностью генерации коротких ссылок

Развёртывание и запуск ИИ-ассистента

При развёртывании ИИ-ассистента необходимо выполнить следующие действия:

1. Запустить docker-контейнер с моделью машинного обучения;
2. При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;
3. Запустить сервис ИИ-ассистента.

Запуск docker-контейнера с моделью машинного обучения

Docker-образ контейнера с моделью можно скачать по ссылке: https://svacer.ispras.ru/docker/images/svacer-ai-model-host.1.0.0.tar.gz (3.3GB)

Далее docker-образ необходимо загрузить на docker-хост с помощью команды

docker image load -i /path/to/svacer-ai-model-host.1.0.0.tar.gz

После этого docker-контейнер может быть запущен следующей командой

docker volume create svacer-ai-cache
docker volume create svacer-ai-pgdata
docker run -d --name svacer-ai-model-host -p 7000:8000 -v svacer-ai-pgdata:/var/lib/postgresql/data -v svacer-ai-cache:/root/.cache svacer-ai-model-host:1.0.0

Том cache будет содержать кэш сервиса взаимодействия с моделью машинного обучения.

Том pgdata будет содержать файлы с данными встроенного в docker-образ postgres'а.

Порт 7000 будет использоваться по умолчанию, если не были изменены параметры подключения сервиса машинного обучения

Запуск ИИ-ассистента

Исполняемый файл ИИ-ассистента можно скачать по ссылке: https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz (53MB)

После этого ИИ-ассистент может быть запущен командой svacerai-server run

Флаги команды запуска ИИ-ассистента

Глобальные флаги svacerai-server help

NAME:
   svacerai-server - Svace AI server

USAGE:
   svacerai-server [global options] command [command options] [arguments...]

COMMANDS:
   run
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --debug            (default: false) [$SVACER_AI_DEBUG]
   --log-level value  Defines log level. Available: info, warn, error [$SVACER_AI_LOG_LEVEL]
   --log value        Defines path to log file. By default file /tmp/svacer-ai-*.log will be created.
   --config value     Define path to file with config in YAML format (by default svacer-ai.cfg).
   --help, -h         show help

Название	Тип данных	Описание
debug	bool	Отладочный режим логирования
log-level	string	Уровень логирования
log	string	Путь к файлу с логами
config	string	Путь к конфигурационному файлу

Флаги запуска ИИ-ассистента svacerai-server run help

NAME:
   svacerai-server run

USAGE:
   svacerai-server run [command options] [arguments...]

OPTIONS:
   --pg value                           Defines PostgreSQL connection URL
   --host value                         Defines host name for the server
   --svacer-host value                  Defines remote Svacer host
   --ai-host value [ --ai-host value ]  Specify the address of the service with AI models in the format {host id}:{http://{host address}}
   --help, -h                           show help

С помощью флагов запуска можно переопределять наиболее часто меняющиеся параметры конфигурации без необходимости создания файла svacer-ai.cfg

Название	Тип данных	Описание	Формат
pg	string	Строка подключения к базе данных ИИ-ассистента	https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
host	string	Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент	{ip адрес}:{порт}
svacer-host	string	Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент	https://en.wikipedia.org/wiki/URL#Syntax
ai-host	[]string	Url сервиса с моделями машинного обучения	https://en.wikipedia.org/wiki/URL#Syntax

Пример:

svacerai-server run --pg postgres://svace:svace@127.0.0.1:5432/svacer_ai --host localhost:8095 --svacer-host http://localhost:8094

Конфигурация ИИ-ассистента

Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла svacer-ai.cfg в рабочей директории сервиса.

Название	Тип данных	Описание	Значение в конфигурации по умолчанию
db/url	string	Строка подключения к базе данных ИИ-ассистента	postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable
http/host	string	Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент	localhost:8081
http/svacerHostUrl ai/svacerHostUrl	string	Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент	http://localhost:8080/
http/svacerClientTlsCfg? ai/svacerClientTlsCfg	*tls.Config	Настройки безопасного подключения к Svacer	svacerClientTlsCfg: insecureSkipVerify: true
ai/svacerReviewCommentTemplate	string	Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура processing.MarkerResult	См. конфигурацию по умолчанию
ai/svacerReviewTags	[]string	Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента	[AI]
hosts	map[string]object	Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент	{id сервиса}: {параметры подключения} (см. описание ниже)

Параметры подключения сервиса модели машинного обучения

Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:

Название	Тип данных	Описание	Значение в конфигурации по умолчанию
url	string	Url сервиса с моделями машинного обучения	http://localhost:7000
settings/requestBatchSize	int	Количество предупреждений, отправляемых для анализа моделью за раз	512
settings/httpMultipartParameterName settings/httpMultipartFileName settings/httpMultipartContentType	string	Параметра multipart-запроса вызова модели	httpMultipartParameterName: "file" httpMultipartFileName: "file.csv" httpMultipartContentType: "application/vnd.ms-excel"
resources/modelList resources/modelInference resources/logs	string	Сопоставление названий ресурсов сервиса моделей	modelList: "/models_info" modelInference: "/use_model_for_file" logs: "/log_file"
defaults/dataCollector/csvSeparator	string	Разделитель csv-файла, который отправляется в сервис моделей	","
defaults/dataCollector/additionalLineNumber	int	Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей	0
defaults/dataCollector/csvColumns	[]string	Названия столбцов csv-файла, который отправляется в сервис моделей	[id, warnClass, code]
defaults/interpretation/defaultValue defaults/interpretation/defaultValue defaults/interpretation/defaultValue	string	Названия статусов, которые присваиваются результату вызова модели	defaultValue: "Undecided" leftClassValue: "False Positive" rightClassValue: "Confirmed"

Конфигурация по умолчанию

Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл svacer-ai.cfg.

Если файл svacer-ai.cfg существует, в нём должны содержаться все указанные параметры конфигурации.

varSvacerHostUrl: &svacerHostUrl "http://localhost:8080/"
varSvacerClientTlsCfg: &svacerClientTlsCfg
  insecureSkipVerify: true
db:
  url: "postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable"
http:
  host: "localhost:8081"
  svacerHostUrl: *svacerHostUrl
  svacerClientTlsCfg: *svacerClientTlsCfg
ai:
  svacerHostUrl: *svacerHostUrl
  svacerClientTlsCfg: *svacerClientTlsCfg
  svacerReviewCommentTemplate: |+
    `Timestamp: {{now.UTC.Format "2006-01-02T15:04:05Z"}}`

    `AI model: {{.Pipeline.Name}}`

    `Confidence level: {{ printf "%.2f" (index .Interpretation 0).Confidence }}`

  svacerReviewTags:
    - AI
  hosts:
    server-status:
      url: "http://localhost:7000"
      settings:
        requestBatchSize: 512
        httpMultipartParameterName: "file"
        httpMultipartFileName: "file.csv"
        httpMultipartContentType: "application/vnd.ms-excel"
      resources:
        modelList: "/models_info"
        modelInference: "/use_model_for_file"
        logs: "/log_file"
      defaults:
        dataCollector:
          csvSeparator: ","
          additionalLinesNumber: 0
          csvColumns:
            - "id"
            - "warnClass"
            - "code"
        interpretation: 
          defaultValue: "Undecided"
          leftClassValue: "False Positive"
          rightClassValue: "Confirmed"