Настройка интеграции с AI-сервисом DB Advisor#

Настройка интеграции с AI-сервисами (DB Advisor) делится на следующие части:

Включение сервиса AI-диагностики#

Примечание

Сервис AI-диагностики (DB Advisor) является опциональным компонентом и не разворачивается по умолчанию.

Для включения сервиса AI-диагностики выполните следующие шаги:

  1. Задайте значение true параметру application.enabled в файле конфигурации Helm-шаблона ./helm/application/dbadvisor.

    Данный параметр отвечает за разворачивание сервиса в Kubernetes-кластере. При значении false ресурсы сервиса не создаются (под не запускается).

  2. Для включения раздела «AI-диагностика» в пользовательском интерфейсе задайте значение true параметру KINTSUGI_ENABLE_AI_DIAGNOSTICS в файле environment.json фронтенда.

    Примечание

    Параметр application.enabled отвечает только за разворачивание сервиса и не влияет на видимость раздела в пользовательском интерфейсе. Эти два параметра настраиваются независимо.

Настройка LLM-провайдера#

Сервис AI-диагностики использует большие языковые модели (LLM) для анализа данных и формирования рекомендаций. Поддерживаются следующие провайдеры:

  • GigaChat — приоритетный провайдер (доверенный периметр);

  • AIHub — внутренний OpenAI-совместимый периметр;

  • OpenAI-совместимый — self-hosted модели внутри контура.

Примечание

Проверка работоспособности и устранение ошибок производились на основе моделей GigaChat-2-Max и Qwen/Qwen3.6-27B.

Настройка провайдера LLM#

Определите параметры LLM-провайдера в секции llm конфигурации:

Параметр

Пример

Обязательный

Описание

llm.provider

openai

Да

Тип провайдера: gigachat / aihub / openai / mock

llm.max_tokens

8192

Нет

Потолок токенов генерации на один вызов LLM (по умолчанию равен 0)

Провайдер GigaChat#

Параметр

Пример

Обязательный

Описание

llm.provider

gigachat

Да

Активный провайдер LLM

llm.gigachat.scope

GIGACHAT_API_PERS

Нет

OAuth-scope GigaChat

llm.gigachat.oauth_url

https://oauth.gigachat.example.com/token

Да

Адрес OAuth-конечной точки

llm.gigachat.api_base_url

https://api.gigachat.example.com/v1/chat/completions

Да

Базовый URL API chat-completions

llm.gigachat.model

GigaChat-2-Max

Нет

Модель GigaChat

llm.gigachat.auth_key.file

/kintsugi/dbadvisor/secrets/gigachat_auth_key.secret

Да

Путь к файлу с ключом авторизации

Провайдер AIHub#

Параметр

Пример

Обязательный

Описание

llm.provider

aihub

Да

Активный провайдер LLM

llm.aihub.base_url

https://aihub.internal.example.com/v1

Да

URL AIHub (OpenAI-совместимый API)

llm.aihub.model

GigaChat-2-Max

Нет

Модель AIHub

llm.aihub.api_key.file

/kintsugi/dbadvisor/secrets/aihub_api_key.secret

Да

Путь к файлу с ключом API

Провайдер OpenAI-совместимый (self-hosted)#

Параметр

Пример

Обязательный

Описание

llm.provider

openai

Да

Активный провайдер LLM

llm.openai.base_url

http://web.stage.ai.sbt:8080/api

Да

Базовый URL API

llm.openai.model

Qwen/Qwen3.6-27B

Да

Имя модели

llm.openai.api_key.file

/kintsugi/dbadvisor/secrets/openai_api_key.secret

Да

Путь к файлу с ключом API

Примечание

API-ключи LLM-провайдеров передаются сервису через файлы в каталоге /kintsugi/dbadvisor/secrets/, монтируемые из k8s Secrets.

Настройка маскирования данных#

Перед отправкой данных в LLM чувствительная информация маскируется компонентом Redactor. Политика маскирования настраивается параметром redactor.policy.

Параметр

Пример

Описание

redactor.policy

strict

Политика маскирования: standard / strict / off

Доступные значения:

  • standard — базовое маскирование чувствительных данных (строки подключения, IP-адреса, имена БД и пользователей, секреты);

  • strict — строгое маскирование: тексты SQL целиком не передаются за контур, отправляются только структурированные метрики;

  • off — маскирование отключено (только для development/тестирования).

Примечание

Политика strict совместима только с провайдером llm.provider: mock. С сетевым провайдером (GigaChat, AIHub, OpenAI) сервис не стартует при redactor.policy: strict (ограничение КБ-3). Для промышленной эксплуатации с сетевым провайдером используйте политику standard.

Настройка кастомных паттернов маскирования#

Для дополнительного маскирования пользовательских паттернов определите параметр redactor.custom_patterns в ConfigMap сервиса. Параметр принимает список объектов с полями regex (регулярное выражение) и replacement (строка замены).

Настройка прав доступа#

Доступ к разделу «AI-диагностика» управляется двумя asset-привилегиями, вычисляемыми сервисом curator по модели ABAC:

Привилегия

Описание

asset_pg_ai_view

Просмотр раздела и результатов диагностики экземпляра

asset_pg_ai_run

Запуск прогона диагностики и принятие решений по находкам

Примечание

Раздел «AI-диагностика» дополнительно закрыт фронтовым флагом функций KINTSUGI_ENABLE_AI_DIAGNOSTICS. Даже при наличии привилегий раздел не будет виден в интерфейсе, если флаг функций отключен.

Для заведения привилегий выполните следующие шаги:

  1. Зарегистрируйте ключи привилегий в бэкенде. Добавьте ключи asset_pg_ai_view и asset_pg_ai_run в перечисление asset-привилегий бэкенда, по которому curator валидирует privilege_key.

  2. Выполните SQL-миграцию. Заведите привилегии как тип asset с локализованными названиями (ru/en) и грантуйте их по модели ABAC выделенной группе пользователей AI-диагностики (user_group_key).

  3. Зарегистрируйте ключи привилегий во фронтенде. Добавьте те же ключи asset_pg_ai_view и asset_pg_ai_run в перечисление asset-привилегий пользовательского интерфейса.

Назначение прав пользователям#

Права asset_pg_ai_view и asset_pg_ai_run назначаются выделенной группе пользователей AI-диагностики (user_group_key). Членство в группе задается одним из способов:

  • списком пользователей;

  • ассоциацией с RBAC-ролью через поле role_name.

Настройка промптов агентов#

Поведение агентов диагностики задается текстовыми промптами, которые можно изменять без пересборки сервиса через ConfigMap.

Структура промпт-файлов#

Файлы промптов располагаются в каталоге services/aiagent/prompts/:

Файл

Агент

workload.yaml

Workload (нагрузка)

index.yaml

Index (индексы)

vacuum.yaml

Vacuum (очистка)

configuration.yaml

Configuration (конфигурация)

connection.yaml

Connection (соединения)

planner.yaml

Планировщик (сводка рекомендаций)

Варианты промптов#

Для каждого агента поддерживаются два варианта промптов:

  • strict — с форматным контролем (используется по умолчанию);

  • lean — без форматного контроля (для моделей с надежным следованием формату).

Выбор профиля промптов осуществляется через override-ConfigMap при развертывании.

Проверка корректности настройки#

Минимальный набор параметров для деплоя#

Для корректной работы сервиса AI-диагностики убедитесь, что заданы следующие параметры:

  1. application.enabled=true (Helm-конфигурация);

  2. KINTSUGI_ENABLE_AI_DIAGNOSTICS=true (файл environment.json фронтенда);

  3. llm.provider и соответствующие параметры выбранного провайдера (URL, модель, секреты);

  4. global.database.dbadvisordb.* (подключение к собственной БД сервиса);

  5. abac.curator_url (адрес сервиса curator, генерируется через common.endpoints.service.curator);

  6. Привилегии asset_pg_ai_view и asset_pg_ai_run зарегистрированы в curator;

  7. Конфигурация edge-прокси iam (aiagent.server.conf) развернута.

Проверка работоспособности#

Проверка

Конечная точка

Ожидаемый результат

Живость процесса

GET /aiagent/v1/liveness

200 OK

Готовность сервиса

GET /aiagent/v1/readiness

200 OK (собственная БД доступна, промпты загружены)

Доступность метрик

GET /metrics

Prometheus-метрики с префиксом aiagent_

Запуск диагностики

POST /aiagent/v1/investigations

202 Accepted с investigation_id

Фиксированные параметры сервиса#

Следующие параметры не настраиваются и имеют фиксированные значения:

Параметр

Значение

Описание

api.port

8080

Порт REST + WebSocket API

api.http_read_timeout_ms

5000 мс

Тайм-аут чтения HTTP-запроса

api.http_read_header_timeout_ms

5000 мс

Тайм-аут чтения заголовков HTTP-запроса

api.http_write_timeout_sec

300 с

Тайм-аут записи HTTP-ответа

api.http_idle_timeout_min

30 мин

Тайм-аут неактивного HTTP-соединения

api.rate_limit_investigations_per_min_per_user

10

Лимит запусков диагностики на пользователя в минуту

limits.max_concurrent_runs

8

Максимальное количество одновременных прогонов диагностики

limits.max_tokens_per_run

1000000

Бюджет LLM-токенов на один прогон диагностики

llm.max_tokens

8192

Потолок токенов генерации на один вызов LLM

db.max_conns

10

Максимальное количество соединений с собственной БД сервиса

backend.service_port

8080

Порт подключения к сервису backend

backend.server_hello_timeout

10 с

Тайм-аут ожидания ответа от сервера backend при установке соединения

backend.max_reconnect_attempts

3

Максимальное количество попыток переподключения к backend

backend.max_reconnect_delay_time

5 с

Максимальная задержка между попытками переподключения к backend