Использование ИИ-ассистента#

Предусловия#

​ Установленный продукт DataGrid. Подробнее об установке продукта написано в документе «Руководство по установке».

Типовой сценарий использования#

1. Распакуйте дистрибутив документации:

   unzip IGN-doc-<version>-<build>-distrib.zip -d /opt/ign/docs
   

2. Укажите корневую директорию документации в ./config/ignite-doc-assistant.yaml:

   YAML#

   assistant:
     sources:
       docs-path: /opt/ign/docs
   

   Внутри этой директории должны располагаться страницы документации по пути вида: IGN/<version>/html/documents.

3. Настройте подключение к провайдеру моделей: в файле ./config/ignite-doc-assistant.yaml укажите базовый URL (base-url), ключ доступа (api-key) и идентификатор выбранной модели (model). Подробнее о конфигурировании ИИ-ассистента написано в разделе «Настройки ИИ-ассистента» документа «Руководство по установке».

4. Постройте индекс:

   ./ignite-doc-assistant.sh reindex
   

5. Запустите консольный чат:

   ./ignite-doc-assistant.sh
   

Команда без параметров запускает режим console. Подробнее о команде и параметрах написано в следующем разделе.

Команды#

Команда quality-check использует проверки из quality/questions.json и выводит найденные источники, ответ модели и время выполнения. Коды завершения:

• 0 — все проверки пройдены;

• 1 — одна или несколько проверок не пройдены;

• 2 — проверку не удалось выполнить из-за ошибки.

Команда reindex извлекает текст из HTML, делит его на фрагменты и сохраняет их векторные представления в индекс. При обработке вопроса ассистент находит в индексе наиболее подходящие фрагменты и передает их чат-модели как контекст.

Подготовка документации#

Индексатор рекурсивно ищет директории html/documents и обрабатывает находящиеся в них файлы .html. Из каждой страницы извлекается содержимое article[role=main] или article.md-content__inner. Markdown-, TXT- и ZIP-файлы напрямую не поддерживаются.

Чтобы источники в ответах открывались как веб-страницы, задайте base-url, например:

assistant:
  sources:
    docs-path: /opt/ign/docs
    base-url: https://platformv.sbertech.ru/docs/public/IGN/17.8.0/common

Например, страница IGN/17.8.0/html/documents/administration-guide/control-sh.html будет представлена ссылкой https://platformv.sbertech.ru/docs/public/IGN/17.8.0/common/documents/administration-guide/control-sh.html.

base-url должен:

• указывать на публичную директорию, внутри которой находится documents/;

• быть HTTP(s)-адресом без параметров запроса и фрагмента.

Если base-url не задан, ИИ-ассистент выводит локальные пути. После изменения docs-path выполните reindex. Изменение base-url переиндексации не требует.

Настройка моделей#

Для работы с ИИ-ассистентом нужны чат-модель и модель эмбеддингов. Можно подключить GigaChat или провайдера с API, совместимым с OpenAI-протоколом. Адрес API, названия моделей и учетные данные задаются в ./config/ignite-doc-assistant.yaml.

spring:
  ai:
    model:
      chat: openai
      embedding: openai
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.example.com
      chat:
        options:
          model: provider/chat-model
      embedding:
        options:
          model: provider/embedding-model

Замените адрес API (параметр base-url), название модели и имя переменной с ключом в соответствии с настройками выбранного провайдера:

spring:
  ai:
    model:
      chat: gigachat
      embedding: gigachat
    gigachat:
      auth:
        scope: GIGACHAT_API_PERS
        unsafe-ssl: false
        bearer:
          api-key: ${GIGACHAT_AUTH_KEY}
      base-url: https://gigachat.devices.sberbank.ru/api/v1
      chat:
        options:
          model: GigaChat-2-Max
          temperature: 0.1
          max-tokens: 10000
      embedding:
        enabled: true
        options:
          model: EmbeddingsGigaR
          dimensions: 2560

Применение подхода RAG#

Пример применения подхода RAG в конфигурационном файле ./config/ignite-doc-assistant.yaml:

assistant:
  rag:
    top-k: 8
    similarity-threshold: 0.0
    chunk-size: 160
    chunk-overlap: 20
    max-chunk-chars: 2000
    max-context-chars: 14000

Начните со значений по умолчанию и подбирайте top-k и similarity-threshold с помощью команды quality-check.

После изменения модели эмбеддингов, размерности вектора (параметр dimensions задается в настройках провайдера), chunk-size, chunk-overlap или max-chunk-chars перестройте индекс. Параметры top-k, similarity-threshold и max-context-chars можно менять без переиндексации.

Векторное хранилище#

По умолчанию используется локальное хранилище SimpleVectorStore. Индекс сохраняется в ignite-doc-assistant-vector-store.json, поэтому отдельная векторная база данных не нужна.

Для удаленного хранения можно использовать Qdrant (задается в конфигурационном файле ./config/ignite-doc-assistant.yaml):

spring:
  ai:
    vectorstore:
      type: qdrant
      qdrant:
        host: ${QDRANT_HOST}
        port: ${QDRANT_PORT}
        api-key: ${QDRANT_API_KEY}
        collection-name: ign-docs
        initialize-schema: true

После изменения размерности вектора пересоздайте коллекцию Qdrant или укажите новое collection-name.

JVM и журналы#

JVM-параметры задаются в ./config/jvm.opts, настройки Log4j2 — в ./config/log4j2.xml.

Относительные пути в конфигурации отсчитываются от корня дистрибутива, где находится скрипт запуска.

Диагностические сообщения записываются в ./log/ignite-doc-assistant.log. Архивные журналы хранятся до 30 дней, их общий размер ограничен 100 МБ.

Рекомендации по работе с ИИ-ассистентом#

1. Не используйте ИИ-функции DataGrid для обработки персональных или конфиденциальных данных во избежание утечки чувствительной информации.

2. Не передавайте пароли, токены, криптографические ключи и другие чувствительные данные в строки ввода при использовании ИИ‑функции DataGrid.

3. Используйте ИИ‑функции DataGrid только для законных и разрешенных сценариев в соответствии с эксплуатационной документацией продукта, корпоративной политикой и регуляторными требованиями.

4. Не применяйте ИИ‑функции для принятия критических решений без проверки специалистом.

5. Проверяйте корректность и актуальность ответов ИИ перед использованием или распространением информации.

6. Сообщайте об аномальной активности, некорректных результатах или подозрении на инциденты безопасности ответственным лицам или в службу ИБ.