Help:XSvacer:AIAssistant

Disclaimer

• Это экспериментальная Proof of Concept версия, предоставляемая для ознакомления по принципу "как есть".
• Данная функциональность не связана с AI-ассистентом из анализатора Svace. Функционал AI-ассистента из анализатора Svace будет интегрирован в Svacer в будущих версиях сервера.

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

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

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

Активация и запуск ИИ-ассистента

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

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

docker compose

Самый простой способ деплоя — развернуть всё в докер-контейнерах, воспользовавшиcь подготовленным нами docker compose файлом:

curl -LO https://svacer.ispras.ru/extra/docker-compose-with-ai.yml
docker compose -f docker-compose-with-ai.yml up -d

deb/rpm

Если Svacer установлен из deb/rpm пакета:

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

docker run --rm -d --name svacerai-model -p 8000:8000 ispras/svacerai-model:latest

2. В PostgreSQL создайте отдельную БД для ИИ-сервера, запустив psql-консоль и выполнив команды:

sudo su -l postgres
psql
postgres=# create database svacerai;
postgres=# grant all privileges on database svacerai to svace;

(предполагается, что пользователь svace уже был создан для сервера Svacer)

3. В конфиг-файле ИИ-сервера /etc/default/svacerai укажите аргументы запуска

# URL подключения к БД из второго шага
SVACERAI_PG_URL="postgres://svace:svace@127.0.0.1:5432/svacerai?sslmode=disable"

# адрес и порт модели из первого шага
SVACERAI_MODEL_URL="server-status:http://localhost:8000"

# интерфейс и порт, на котором будет запущен ИИ-сервер
SVACERAI_HOST="0.0.0.0:7001"

# URL сервера Svacer, который будет подключен к ИИ-серверу
SVACER_HOST="http://localhost:8080"

4. Запустите systemd-сервис ИИ-сервера

systemctl start svacerai

5. В конфиг-файле сервера Svacer /etc/default/svacer включите фичу ИИ-ассистента, добавив флаг --xsvacer.features aiAssistant и укажите URL ИИ-сервера

SVACER_ARGS="--pg ... --store ... --xsvacer.features aiAssistant"
 
# соответствует переменной SVACERAI_HOST из шага 3
XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://localhost:7001/

6. Перезапустите сервер Svacer

systemctl restart svacer

Дополнительная конфигурация

Подключение к ИИ-ассистенту

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

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

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

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

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

docker volume create svacer-ai-cache
docker volume create svacer-ai-pgdata
docker run --rm -d --name svacerai-model -p 8000:8000 -v svacer-ai-pgdata:/var/lib/postgresql/data -v svacer-ai-cache:/root/.cache ispras/svacerai-model:latest

• Вольюм cache будет содержать кэш сервиса взаимодействия с моделью машинного обучения
• Вольюм pgdata будет содержать файлы с данными встроенного в docker-образ PostgreSQL

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

Глобальные флаги 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	Список адресов сервисов с моделями машинного обучения. host-id — идентификатор сервиса моделей в конфигурации	{host id}:{url сервиса моделей}

При использовании конфигурации по умолчанию, {host id} должен быть равен server-status

Пример:

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

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

Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного 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"

Описание модели xgb.joblib ИИ-ассистента

Модель обучена на базе 50000+ размеченных предупреждений.

Для предсказания статуса разметки нами используются:

1. языковая модель codebert-base для получения эмбеддингов кода;
2. метод градиентного бустинга (xgboost) для решения задачи классификации.