Session RAG — инструкция администратора

Yonote: этот документ — источник для раздела «Session RAG» в Инструкции администратора.

Канон: wilix-site/content/one/docs/admin/session-rag.md (этот файл).

Session RAG индексирует транскрипты сессий агентов (сообщения, tool calls, ошибки) в OpenSearch с векторным поиском. Используется:

семантический поиск по сессиям в agents-api (GET /sessions/search);
MCP-инструмент platform.sessions.search_transcripts (platform MCP gateway);
UI и реиндекс в Settings → Platform.

Архитектура

Компонент	Назначение	Где настраивается
Redis	очередь индексации (Streams), debounce	Helm: `dashboard.agents.env.REDIS_URL`
OpenSearch	хранение чанков + k-NN	Helm: `dashboard.agents.env.OPENSEARCH_URL`
Embeddings API	OpenAI-compatible `/embeddings`	Settings → Platform (runtime)
Postgres	состояние индекса, jobs реиндекса	миграции agents-api (авто)

Индексатор работает внутри pod dashboard-agents. Настройки embeddings agents-api подтягивает из dashboard-api при каждом GET /session-rag/status и поллинге каждые 10 секунд — перезапуск pod после сохранения в UI не нужен. Сервис создаётся при наличии Redis+OpenSearch даже без embeddings; воркер стартует, как только embeddings появятся в Settings → Platform.

Production (Wilix One)

1. Helm / деплой

В .helm/values-production.yaml должны быть включены:

opensearch:
  enabled: true
  auth:
    securityPluginEnabled: true
    adminPassword: "<из secret-values-production.yaml>"

dashboard:
  agents:
    env:
      REDIS_URL: 'redis://wilix-one-platform-production-redis:6379/1'
      OPENSEARCH_URL: "https://admin:<пароль>@wilix-one-platform-production-opensearch.wilix-one-platform.svc.cluster.local:9200"

Важно:

URL OpenSearch — in-cluster FQDN, с учётными данными admin и паролем из opensearch.auth.adminPassword.
OpenSearch использует self-signed TLS; клиент agents-api отключает проверку сертификата для https:// (как у freescout-mcp).
Пароль OpenSearch не храните в открытом виде в git — переносите в secret-values-production.yaml (werf encrypt), когда будет удобно.

Опциональные переменные (обычно defaults достаточно):

Переменная	Default	Описание
`SESSION_RAG_INDEX`	`session-transcript-chunks`	имя индекса OpenSearch
`SESSION_RAG_DEBOUNCE_MS`	`3000`	debounce перед flush в очередь
`SESSION_RAG_MAX_WAIT_MS`	`30000`	max wait перед принудительным flush

2. Секреты dashboard-api

Для хранения API key embeddings в UI нужен INTEGRATION_ENCRYPTION_KEY в dashboard.envSecret (тот же ключ, что для MCP OAuth и интеграций). Без него сохранить API key в Settings → Platform нельзя.

Миграция 027_platform_settings_session_rag.sql применяется init-контейнером dashboard-api при деплое.

3. Runtime: Settings → Platform

После деплоя зайдите в Dashboard → Settings → Platform (нужна роль settings.admin).

В блоке Embeddings (OpenAI-compatible API) укажите:

Поле	Пример (production)
Base URL	`https://token-router.wilix.dev/v1`
Model	`qwen3-embedding-0.6b`
Vector dimensions	`1024`
API key	ключ token-router / OpenAI-compatible провайдера

Правила:

Base URL — без trailing slash; запросы идут на {baseUrl}/embeddings.
Dimensions должны совпадать с моделью; при смене модели/размерности нужен полный реиндекс (см. ниже).
API key — write-only: в UI не показывается, хранится зашифрованным. Пустое поле при сохранении не меняет ключ. Чтобы удалить ключ — очистите поле и сохраните (если поддерживается сценарием «очистить и сохранить»; иначе PATCH с null через API).

4. Проверка

Settings → Platform → карточка Session RAG:
- «Индексатор настроен (индекс: session-transcript-chunks)» — OK;
- «Session RAG не настроен» — не хватает OpenSearch URL, Redis, или embeddings в platform settings / env.
Логи pod dashboard-agents:
- при старте: [session-rag] worker and sweeper started;
- если disabled: [session-rag] disabled — set OPENSEARCH_URL and configure embeddings in Settings → Platform.
Проведите тестовую сессию агента с несколькими сообщениями, подождите ~5–10 с, затем поиск:
- GET /agents-api/sessions/search?q=... (с JWT и правами agents.run);
- или MCP platform.sessions.search_transcripts.

Реиндекс

В Settings → Platform → Session RAG:

Кнопка	Действие
Быстрый реиндекс	доиндексировать только новые/изменённые чанки
Полный реиндекс	переэмбеддить все чанки (долго, нагрузка на embeddings)

Полный реиндекс нужен после смены model или dimensions в platform settings.

Полный реиндекс также нужен после смены mapping/analyzers текстовых полей (RU/EN multi-fields). ensureSessionRagIndex не меняет mapping у уже существующего индекса:

Удалить индекс OpenSearch SESSION_RAG_INDEX (default session-transcript-chunks), или задать новое имя индекса через env и задеплоить.
Дождаться создания пустого индекса agents-api (или создать через ensure при старте воркера).
Settings → Platform → Полный реиндекс.

Без шага 1 lexical поиск продолжит использовать старый analyzer (без .ru / .en).

Dev / локальный запуск

Без Helm можно включить RAG env-переменными процесса agents-api:

REDIS_URL=redis://127.0.0.1:6379/1
OPENSEARCH_URL=https://admin:admin@127.0.0.1:9200
EMBEDDINGS_BASE_URL=https://token-router.wilix.dev/v1
EMBEDDINGS_MODEL=qwen3-embedding-0.6b
EMBEDDINGS_DIMENSIONS=1024
EMBEDDINGS_API_KEY=sk-...

Если заданы и env, и platform settings — platform settings имеют приоритет (через internal API), когда настроены DASHBOARD_API_INTERNAL_URL + AGENTS_INTERNAL_TOKEN.

Troubleshooting

Симптом	Возможная причина
«Session RAG не настроен»	нет `OPENSEARCH_URL` / `REDIS_URL` / пустой embeddings Base URL в platform settings
Индексатор не стартует после сохранения UI	подождите до 30 с; проверьте `DASHBOARD_API_INTERNAL_URL` и `AGENTS_INTERNAL_TOKEN` у agents
Ошибка сохранения API key	пустой `INTEGRATION_ENCRYPTION_KEY` на dashboard-api
OpenSearch connection refused	`opensearch.enabled: false`, NetworkPolicy, неверный FQDN
Embeddings 401/403	неверный API key в Settings → Platform
Поиск пустой после сессии	debounce 3 с; проверьте worker в логах; DLQ stream `agents:session-rag:dlq`

Связанные документы

OpenSearch subchart: .helm/values.yaml (секция opensearch)
freescout-mcp (тот же кластерный OpenSearch): mcp/freescout-mcp/README.md
Platform MCP search tool: dashboard/modules/mcp-gateway/src/platform-catalog.ts