Help:XSvacer:AIAssistant: Difference between revisions

From Svacer Wiki
VisualWikitext
No edit summary
(Separate deployment manual from common description)
Tag: Replaced
Line 9: Line 9:
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.


 
{{Note|text=[[Help:XSvacer:AIAssistant:Deploy|Инструкция по активации и запуску функциональности]] ИИ-ассистента}}


== Описание интерфейса ИИ-ассистента==
== Описание интерфейса ИИ-ассистента==
== Активация и запуск функциональности ==
ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:
# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-ассистенту;
# Развернуть и запустить сервис ИИ-ассистента;
=== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ===
Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.
==== Настройка доступа к ИИ-ассистенту в Svacer ====
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code>
Изменить адрес, по которому Svacer будет подключаться к ИИ-ассистенту, можно одним из способов:
# При запуске Svacer установить переменную окружения <code style="white-space: pre;"><nowiki>XSVACER_AIASSISTANT_ASSISTANTHOSTURL=http://{адрес ИИ-ассистента}:{порт}/</nowiki></code>
# В конфигурационном файле <code>svacer.cfg</code> добавить раздел
<pre style="white-space: pre;">
...
xsvacer:
  ...
  aiAssistant:
    assistantHostUrl: http://{адрес ИИ-ассистента}:{порт}/
...
</pre>
==== Настройка значения флага <code>--public-url</code> ====
В связи с тем, что ИИ-ассистент использует REST API Svacer, необходимо добавить url ИИ-ассистента в список публичных url Svacer. Это можно сделать, добавив при запуске Svacer флаг:
--public-url {url ИИ-ассистента}
Пример:
<nowiki>--xsvacer.features aiAssistant --public-url https://svacer-ai-demo.ispras.ru</nowiki>
{{Note|text=Данная настройка связана с функциональностью генерации коротких ссылок}}
=== Развёртывание и запуск ИИ-ассистента ===
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:
# Запустить docker-контейнер с моделью машинного обучения;
# При необходимости: развернуть postresql-сервер для хранения базы данных ИИ-ассистента;
# Запустить сервис ИИ-ассистента.
==== Запуск 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
Том <code style="white-space: pre;">cache</code> будет содержать кэш сервиса взаимодействия с моделью машинного обучения.
Том <code style="white-space: pre;">pgdata</code> будет содержать файлы с данными встроенного в docker-образ postgres'а.
Порт <code>7000</code> будет использоваться по умолчанию, если не были изменены [[#Параметры подключения сервиса модели машинного обучения|параметры подключения сервиса машинного обучения]]
==== Запуск ИИ-ассистента ====
Исполняемый файл ИИ-ассистента можно скачать по ссылке: https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz (53MB)
После этого ИИ-ассистент может быть запущен командой <code>svacerai-server run</code>
===== Флаги команды запуска ИИ-ассистента =====
Глобальные флаги <code>svacerai-server help</code>
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
{| class="wikitable"
|+
!Название
!Тип данных
!Описание
|-
|debug
|bool
|Отладочный режим логирования
|-
|log-level
|string
|Уровень логирования
|-
|log
|string
|Путь к файлу с логами
|-
|config
|string
|Путь к [[#Конфигурация по умолчанию|конфигурационному файлу]]
|}
Флаги запуска ИИ-ассистента <code>svacerai-server run help</code>
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 <nowiki>{host id}:{http://{host address}}</nowiki>
    --help, -h                          show help
{{Note|text=С помощью флагов запуска можно переопределять наиболее часто меняющиеся [[#Конфигурация по умолчанию|параметры конфигурации]] без необходимости создания файла <code>svacer-ai.cfg</code>}}
{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Формат
|-
|style="width: 80px"|pg
|string
|Строка подключения к базе данных ИИ-ассистента
|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
|-
|host
|string
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент
|<code>{ip адрес}:{порт}</code>
|-
|svacer-host
|string
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент
|https://en.wikipedia.org/wiki/URL#Syntax
|-
|ai-host
|[]string
|Url сервиса с моделями машинного обучения
|https://en.wikipedia.org/wiki/URL#Syntax
|}
Пример:
<nowiki>svacerai-server run --pg postgres://svace:svace@127.0.0.1:5432/svacer_ai --host localhost:8095 --svacer-host http://localhost:8094</nowiki>
=== Конфигурация ИИ-ассистента ===
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.
{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|db/url
|string
|Строка подключения к базе данных ИИ-ассистента
|<code>postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable</code>
|-
|http/host
|string
|Адрес сетевого интерфейса и порт, на которых будет запущен ИИ-ассистент
|<code>localhost:8081</code>
|-
|http/svacerHostUrl
ai/svacerHostUrl
|string
|Url сервиса Svacer, к API которого будет обращаться ИИ-ассистент
|<code><nowiki>http://localhost:8080/</nowiki></code>
|-
|http/svacerClientTlsCfg?
ai/svacerClientTlsCfg
|[https://pkg.go.dev/crypto/tls#Config *tls.Config]
|Настройки безопасного подключения к Svacer
|<pre style="white-space: pre;">
svacerClientTlsCfg:
  insecureSkipVerify: true
</pre>
|-
|ai/svacerReviewCommentTemplate
|string
|Шаблон для формирования комментария к разметке выполненной с помощью ИИ-ассистента. В шаблон передаётся структура <code>processing.MarkerResult</code>
|См. [[#Конфигурация по умолчанию|конфигурацию по умолчанию]]
|-
|ai/svacerReviewTags
|[]string
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента
|<code>[AI]</code>
|-
|hosts
|map[string]object
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент
|<pre style="white-space: pre;">
{id сервиса}:
  {параметры подключения}
  (см. описание ниже)
</pre>
|}
==== Параметры подключения сервиса модели машинного обучения ====
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:
{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|url
|string
|Url сервиса с моделями машинного обучения
|<code><nowiki>http://localhost:7000</nowiki></code>
|-
|settings/requestBatchSize
|int
|Количество предупреждений, отправляемых для анализа моделью за раз
|<code>512</code>
|-
|settings/httpMultipartParameterName
settings/httpMultipartFileName
settings/httpMultipartContentType
|string
|Параметра multipart-запроса вызова модели
|<pre style="white-space: pre;">
httpMultipartParameterName: "file"
httpMultipartFileName: "file.csv"
httpMultipartContentType: "application/vnd.ms-excel"
</pre>
|-
|resources/modelList
resources/modelInference
resources/logs
|string
|Сопоставление названий ресурсов сервиса моделей
|<pre style="white-space: pre;">
modelList: "/models_info"
modelInference: "/use_model_for_file"
logs: "/log_file"
</pre>
|-
|defaults/dataCollector/csvSeparator
|string
|Разделитель csv-файла, который отправляется в сервис моделей
|<code>","</code>
|-
|defaults/dataCollector/additionalLineNumber
|int
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей
|<code>0</code>
|-
|defaults/dataCollector/csvColumns
|[]string
|Названия столбцов csv-файла, который отправляется в сервис моделей
|<code>[id, warnClass, code]</code>
|-
|defaults/interpretation/defaultValue
defaults/interpretation/defaultValue
defaults/interpretation/defaultValue
|string
|Названия статусов, которые присваиваются результату вызова модели
|<pre style="white-space: pre;">
defaultValue: "Undecided"
leftClassValue: "False Positive"
rightClassValue: "Confirmed"
</pre>
|}
=== Конфигурация по умолчанию ===
Данная конфигурация применяется по умолчанию при запуске ИИ-ассистента, если отсутствует конфигурационный файл <code>svacer-ai.cfg</code>.
{{Note|type=error|text=Если файл <code>svacer-ai.cfg</code> существует, в нём должны содержаться все указанные параметры конфигурации.'''}}
<pre style="white-space: pre;">
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"
</pre>

Revision as of 10:30, 30 May 2025

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

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

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

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

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

Инструкция по активации и запуску функциональности ИИ-ассистента

Описание интерфейса ИИ-ассистента

Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&oldid=2989"