Help:XSvacer:AIAssistant

From Svacer Wiki
Revision as of 12:49, 27 May 2025 by M.vinogradov (talk | contribs) (--public-url description)

Данная функциональность входит в набор расширений 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 ИИ-ассистента}.

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

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

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

  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

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

Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного 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"
Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&oldid=2984"