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

Примечание

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

Примечание

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

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

Для включения сервиса в редакции Standard используйте профиль dbadvisor в docker-compose конфигурации и установите переменную окружения KINTSUGI_ENABLE_AI_DIAGNOSTICS=true.

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

Определите параметры LLM-провайдера в файле standard/conf/.env:

Переменная

Пример

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

Описание

LLM_PROVIDER

openai

Да

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

LLM_MAX_TOKENS

8192

Нет

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

Провайдер 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

/run/secrets/gigachat_auth_key

Да

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

LLM_GIGACHAT_SCOPE

GIGACHAT_API_PERS

Нет

OAuth-scope GigaChat

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

Переменная

Пример

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

Описание

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

/run/secrets/openai_api_key

Да

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

Примечание

API-ключи LLM-провайдеров передаются сервису через файлы в каталоге /kintsugi/dbadvisor/secrets/, монтируемые из .env-файлов как Docker Secrets (через docker compose secrets или volumes с опцией :ro).

Настройка CA-сертификатов и mTLS#

Переменная

Пример

Описание

LLM_CA_CERT_FILE

/run/secrets/llm_ca_cert.pem

Путь к файлу CA-сертификата LLM-провайдера

LLM_CLIENT_CERT_FILE

/run/secrets/llm_client_cert.pem

Путь к файлу клиентского сертификата (опционально, для mTLS)

LLM_CLIENT_KEY_FILE

/run/secrets/llm_client_key.pem

Путь к файлу клиентского ключа (опционально, для mTLS)

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

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

Переменная

Пример

Описание

REDACTOR_POLICY

standard

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

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

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

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

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

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

Для дополнительного маскирования пользовательских паттернов определите параметр REDACTOR_CUSTOM_PATTERNS в файле .env. Параметр принимает список JSON-объектов с полями regex (регулярное выражение) и replacement (строка замены).

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

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

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

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

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

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

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

Проверка

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

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

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

GET /<service>/v1/liveness

200 OK

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

GET /<service>/v1/readiness

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

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

GET /metrics

Prometheus-метрики с префиксом <service>_

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

POST /<service>/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-токенов на один прогон диагностики

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

Маппинг секретов#

В редакции Standard секреты маппятся через Docker volumes с опцией :ro:

Секрет

Путь на VM

Путь в контейнере

GigaChat API key

/kintsugi/dbadvisor/secrets/gigachat_auth_key

/run/secrets/gigachat_auth_key

OpenAI-совместимый API key

/kintsugi/dbadvisor/secrets/openai_api_key

/run/secrets/openai_api_key

DB password

/kintsugi/dbadvisor/secrets/dbadvisor_db_password

/run/secrets/dbadvisor_db_password

LLM CA cert

/kintsugi/dbadvisor/secrets/llm_ca_cert.pem

/run/secrets/llm_ca_cert.pem

mTLS client cert

/kintsugi/dbadvisor/secrets/llm_client_cert.pem

/run/secrets/llm_client_cert.pem

mTLS client key

/kintsugi/dbadvisor/secrets/llm_client_key.pem

/run/secrets/llm_client_key.pem

Права на файлы: директория 750 (владелец, группа 10001), файлы 640.