Help:XSvacer:AIAssistant: Difference between revisions

From Svacer Wiki
VisualWikitext
m (svacer-ai-1.0.0-linux.tar.gz link)
(AI-model short description)
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Note|text=Данная функциональность входит в набор расширений XSvacer}}
{{Note|text=Данная функциональность входит в набор расширений XSvacer}}


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


Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.
Данная функциональность позволяет использовать модель машинного обучения (ИИ) для помощи при разметке предупреждений.
Line 9: Line 9:
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.
Все данные предупреждений хранятся в Svacer и получаются ИИ-ассистентом с помощью REST API.


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


ИИ-ассистент реализован в виде отдельного сервиса, взаимодействующего со Svacer по REST API. Для его запуска необходимо:
== Описание интерфейса ИИ-ассистента==
=== Разметка одного маркера ===
Чтобы разметить один маркер с помощью ИИ-ассистента:
:1. Нажмите кнопку [[File:Icon AI.png|25px]] [[Help:UI manual#Функции правой панели|на правой панели]] или в виджете маркера на [[Help:UI manual#Вкладка с исходным кодом|вкладке с исходным кодом]].
:[[File:221 Правая панель. Переход к ИИ-разметке.png|thumb|none|x200px|Правая панель. Переход к ИИ-разметке]]
:[[File:222 Виджет элемента трассы. Переход к ИИ-разметке.png|thumb|none|x150px|Виджет маркера на вкладке с исходным кодом. Переход к ИИ-разметке]]
:2. В открывшемся окне разметки:
::а) Выберите модель AI, с помощью которой ИИ-ассистент рассчитает статус разметки.
::Спрогнозированный статус и уровень доверия прогнозу отобразятся в этом же окне.
::Если маркер уже размечен и его статус совпадает с прогнозным, то в окне отобразится сообщение об этом и дальнейшая разметка станет недоступна.
::б) Введите комментарий.
::в) Нажмите кнопку '''Применить'''.
:<gallery mode="packed" heights="250px" style="float:left; clear:right; margin-right:1em; margin-left:1em">
  223 Окно ИИ-разметки.png|Окно ИИ-разметки
  224 Окно ИИ-разметки. Статус совпадает.png|Окно ИИ-разметки. Прогнозный статус совпадает с существующим
</gallery>
<br clear=all />
:Статус, установленный с помощью ИИ-ассистента, отобразится в верхней части правой панели и в виджете маркера на вкладке с исходным кодом с отметкой [[File:Icon AI 2.png|15px]]. Также этой иконкой будет отмечен статус в комментарии, добавленном при разметке, который дополнительно содержит информацию о проведенной разметке: время, имя модели машинного обучения, уровень доверия прогнозу.
:Дополнительная информация также отображается при наведении курсора на иконку [[File:Icon AI 2.png|15px]].
<gallery mode="packed" heights="250px" style="float:left; clear:right; margin-right:1em; margin-left:1em">
  225 Правая панель. Результат ИИ-разметки.png|Правая панель. Результат ИИ-разметки
  227 Правая панель. Комментарий об ИИ-разметке.png|Правая панель. Комментарий об ИИ-разметке
</gallery>
<br clear=all />
[[File:226 Виджет элемента трассы. Результат ИИ-разметки.png|thumb|none|x150px|Виджет элемента трассы. Результат ИИ-разметки]]


# Активировать функциональность при запуске Svacer и настроить доступ к ИИ-асстистенту;
=== Групповая разметка маркеров ===
# Развернуть и запустить сервис ИИ-ассистента;
Чтобы разметить несколько маркеров с помощью ИИ-ассистента одновременно:
:1. Если планируется разметить большое количество маркеров, то для ускорения составления прогноза запустите предварительный рассчет (опционально) – на вкладке [[Help:UI manual#Вкладка «Информация о снимке»|'''Информация о снимке''']] [[Help:UI manual#Функции центральной панели|центральной панели]] нажмите кнопку '''Проанализировать с AI'''.
:Расчет прогнозируемого статуса для каждого маркера запустится в фоновом режиме. В это время на месте кнопки будет отображаться анимированная иконка ожидания.
:[[File:228 Информация о снимке. Предварительный расчет.png|thumb|none|x200px|Информация о снимке. Кнопка перехода к предварительному расчету статусов маркеров]]
:2. Выберите маркеры для разметки – установите флажки в строках [[Help:UI manual#Таблица маркеров|таблицы]].
:3. Нажмите кнопку [[File:Icon AI.png|25px]] (доступна, если выбраны маркеры в таблице).
:4. В открывшемся окне разметки:
::а) Выберите модель AI, с помощью которой ИИ-ассистент рассчитает статус разметки.
::Спрогнозированные статусы и уровни доверия прогнозу отобразятся в этом же окне в таблице маркеров. При этом размеченные ранее маркеры окрашены в цвет, соответствующий выставленному статусу.
::В таблице доступна сортировка значений в столбцах '''Детектор''', '''Файл''', '''Строка''' и '''Уровень доверия''', а в столбце '''Статус разметки''' доступна фильтрация по значению прогнозируемого статуса.
::б) Введите комментарий.
::в) Выберите маркеры, которые требуется разметить, – установите флажки в столбце '''Статус разметки'''.
::Если маркер уже размечен и его статус совпадает с прогнозным, то он недоступен для установки флажка.
::г) Нажмите кнопку '''Применить'''.
:[[File:229 Окно групповой ИИ-разметки.png|thumb|none|x300px|Окно групповой ИИ-разметки]]
:Прогресс разметки отображается в соответствующем окне. Запущенный процесс можно полностью отменить нажатием кнопки '''Отмена'''.
:[[File:56 Окно прогресса разметки.png|thumb|none|x100px|Окно прогресса разметки]]
=== Фильтрация маркеров по режиму разметки ===
По умолчанию в [[Help:UI manual#Таблица маркеров|таблице маркеров]] отображаются все маркеры: как размеченные вручную, так и размеченные с помощью ИИ-ассистента.
Чтобы отобразить маркеры только с одним режимом разметки, воспользуйтесь [[Help:UI manual#Настройка и использование пользовательских фильтров|пользовательскими фильтрами]]:
* для отображения только маркеров, размеченных вручную, выберите фильтр '''Режим разметки''' – '''Вручную''';
* для отображения только маркеров, размеченных с помощью ИИ-ассистента, выберите фильтр '''Режим разметки''' – '''С помощью ИИ'''.
[[File:230 Пользовательские фильтры. Режимы разметки.png|thumb|none|x400px|Пользовательские фильтры. Режимы разметки]]


== Активация функциональности <code style="white-space: pre;">xsvacer</code> при запуске Svacer ==
== Описание модели xgb.joblib ИИ-ассистента ==


Для активации функциональности необходимо указать флаг <code style="white-space: pre;">--xsvacer.features aiAssistant</code> при запуске Svacer.
Модель обучена на базе 50000+ размеченных предупреждений.


=== Настройка доступа к ИИ-ассистенту в Svacer ===
Для предсказания статуса разметки нами используются:
 
# языковая модель codebert-base для получения эмбеддингов кода;
По умолчанию Svacer будет пытаться подключиться к ИИ-ассистенту по адресу <code style="white-space: pre;"><nowiki>http://localhost:8081/</nowiki></code>
# метод градиентного бустинга (xgboost) для решения задачи классификации.
 
Изменить адрес по которому 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>
 
== Развёртывание и запуск ИИ-ассистента ==
 
При развёртывании ИИ-ассистента необходимо выполнить следующие действия:
 
# Запустить 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'а.
 
=== Запуск ИИ-ассистента ===
 
Исполняемый файл ИИ-ассистента можно скачать по ссылке - https://svacer.ispras.ru/releases/svacer-ai/svacer-ai-1-0-0-linux.tar.gz
 
После этого ИИ-ассистент может быть запущен командой <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"
|+
!Название
!Тип данных
!Описание
|-
|pg
|string
|Строка подключения к базе данных ИИ-ассистента
|-
|host
|string
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент
|-
|svacer-host
|string
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент
|-
|ai-host
|[]string
|Адреса сервиса с моделями машинного обучения
|}
 
== Конфигурация ИИ-ассистента ==
 
Управление настройками ИИ-ассистента осуществляется с помощью конфигурационного yaml-файла <code>svacer-ai.cfg</code> в рабочей директории сервиса.
 
{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|db/url
|string
|Строка подключения к базе данных ИИ-ассистента
|postgres://postgres:postgres@localhost:5432/svacer_ai?sslmode=disable
|-
|http/host
|string
|Адрес сетевого интерфейса и порт на которых будет запущен ИИ-ассистент
|localhost:8081
|-
|http/svacerHostUrl
 
ai/svacerHostUrl
|string
|Адрес сервиса Svacer к API которого будет обращаться ИИ-ассистент
|http://localhost:8080/
|-
|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
|Список названий меток, которые будут установлены маркерам, размеченным с помощью ИИ-ассистента
|[AI]
|-
|hosts
|map[string]object
|Список параметров подключения к сервисам с моделями машинного обучения, которые будет использовать ИИ-ассистент
|<pre style="white-space: pre;">
{id сервиса}:
  {параметры подключения}
  (см. описание ниже)
</pre>
|}
 
=== Параметры подключения сервиса модели машинного обучения ===
 
Параметры подключения сервисов модели задаются в виде map, ключами которой являются идентификаторы сервисов. В значении содержатся следующие параметры:
 
{| class="wikitable"
|+
!Название
!Тип данных
!Описание
!Значение в конфигурации по умолчанию
|-
|url
|string
|Адрес сервиса с моделями машинного обучения
|http://localhost:7000
|-
|settings/requestBatchSize
|int
|Количество предупреждений отправляемых для анализа моделью за раз
|512
|-
|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-файла, который отправляется в сервис моделей
|","
|-
|defaults/dataCollector/additionalLineNumber
|int
|Количество строк исходного кода, которые добавляются до и после строки предупреждения при отправке в сервис моделей
|0
|-
|defaults/dataCollector/csvColumns
|[]string
|Названия столбцов csv-файла, который отправляется в сервис моделей
|[id, warnClass, 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>

Latest revision as of 08:48, 4 June 2025

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

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

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

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

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

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

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

Разметка одного маркера

Чтобы разметить один маркер с помощью ИИ-ассистента:

1. Нажмите кнопку на правой панели или в виджете маркера на вкладке с исходным кодом.
Правая панель. Переход к ИИ-разметке
Виджет маркера на вкладке с исходным кодом. Переход к ИИ-разметке
2. В открывшемся окне разметки:
а) Выберите модель AI, с помощью которой ИИ-ассистент рассчитает статус разметки.
Спрогнозированный статус и уровень доверия прогнозу отобразятся в этом же окне.
Если маркер уже размечен и его статус совпадает с прогнозным, то в окне отобразится сообщение об этом и дальнейшая разметка станет недоступна.
б) Введите комментарий.
в) Нажмите кнопку Применить.
  • Окно ИИ-разметки

    Окно ИИ-разметки

  • Окно ИИ-разметки. Прогнозный статус совпадает с существующим

    Окно ИИ-разметки. Прогнозный статус совпадает с существующим


    • Статус, установленный с помощью ИИ-ассистента, отобразится в верхней части правой панели и в виджете маркера на вкладке с исходным кодом с отметкой . Также этой иконкой будет отмечен статус в комментарии, добавленном при разметке, который дополнительно содержит информацию о проведенной разметке: время, имя модели машинного обучения, уровень доверия прогнозу.
    Дополнительная информация также отображается при наведении курсора на иконку .
    • Правая панель. Результат ИИ-разметки

      Правая панель. Результат ИИ-разметки

    • Правая панель. Комментарий об ИИ-разметке

      Правая панель. Комментарий об ИИ-разметке


    Виджет элемента трассы. Результат ИИ-разметки

    Групповая разметка маркеров

    Чтобы разметить несколько маркеров с помощью ИИ-ассистента одновременно:

    1. Если планируется разметить большое количество маркеров, то для ускорения составления прогноза запустите предварительный рассчет (опционально) – на вкладке Информация о снимке центральной панели нажмите кнопку Проанализировать с AI.
    Расчет прогнозируемого статуса для каждого маркера запустится в фоновом режиме. В это время на месте кнопки будет отображаться анимированная иконка ожидания.
    Информация о снимке. Кнопка перехода к предварительному расчету статусов маркеров
    2. Выберите маркеры для разметки – установите флажки в строках таблицы.
    3. Нажмите кнопку (доступна, если выбраны маркеры в таблице).
    4. В открывшемся окне разметки:
    а) Выберите модель AI, с помощью которой ИИ-ассистент рассчитает статус разметки.
    Спрогнозированные статусы и уровни доверия прогнозу отобразятся в этом же окне в таблице маркеров. При этом размеченные ранее маркеры окрашены в цвет, соответствующий выставленному статусу.
    В таблице доступна сортировка значений в столбцах Детектор, Файл, Строка и Уровень доверия, а в столбце Статус разметки доступна фильтрация по значению прогнозируемого статуса.
    б) Введите комментарий.
    в) Выберите маркеры, которые требуется разметить, – установите флажки в столбце Статус разметки.
    Если маркер уже размечен и его статус совпадает с прогнозным, то он недоступен для установки флажка.
    г) Нажмите кнопку Применить.
    Окно групповой ИИ-разметки
    Прогресс разметки отображается в соответствующем окне. Запущенный процесс можно полностью отменить нажатием кнопки Отмена.
    Окно прогресса разметки

    Фильтрация маркеров по режиму разметки

    По умолчанию в таблице маркеров отображаются все маркеры: как размеченные вручную, так и размеченные с помощью ИИ-ассистента. Чтобы отобразить маркеры только с одним режимом разметки, воспользуйтесь пользовательскими фильтрами:

    • для отображения только маркеров, размеченных вручную, выберите фильтр Режим разметки – Вручную;
    • для отображения только маркеров, размеченных с помощью ИИ-ассистента, выберите фильтр Режим разметки – С помощью ИИ.
    Пользовательские фильтры. Режимы разметки

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

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

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

    1. языковая модель codebert-base для получения эмбеддингов кода;
    2. метод градиентного бустинга (xgboost) для решения задачи классификации.
    Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Help:XSvacer:AIAssistant&oldid=3010"