Состав системы и схемы установки

На этой странице описаны все компоненты AI-ассистента, их взаимосвязи, сетевые взаимодействия, зависимости и варианты размещения.

Диаграмма компонентов

Компоненты ассистента

AI-ассистент (LangGraph Assistant)

Это основной сервис, реализующий логику RAG-пайплайна, маршрутизацию вопросов, стриминг ответов, tool-calling (Platform API Tools) и управление сессиями.

Docker-образ ассистента собирается из Dockerfile на базе python:3.11-slim. Docker-образ устанавливает graphviz-dev, зависимости через uv и копирует код приложения.

Порты

Порт внутри контейнера

Порт на хосте

Протокол |Назначение

80

8090

HTTP (SSE)|API ассистента (/stream, /feedback)
Volumes:

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

Источник на хосте

Назначение

/app/clients.json

./clients.json

Файл с учётными данными клиентов для JWT-авторизации

/app/settings.json

./settings.json

Runtime-настройки ассистента (в т.ч. параметры LLM)

/hf_cache

./hf_cache или ./dev/hf_cache

Кэш моделей HuggingFace (эмбеддинги)

Переменные окружения

Группа LLM

Переменная

Описание

LLM_BASE_URL

URL LLM-провайдера (OpenAI-совместимый API)

LLM_API_KEY

API-ключ для авторизации у LLM-провайдера

USED_MODEL

Имя используемой модели

Переменные LLM_BASE_URL, LLM_API_KEY, USED_MODEL передаются из Платформы в endpoint ассистента и применяются для текущей конфигурации агента.

Переменные также могут быть заданы в env-файле или храниться в settings.json (volume /app/settings.json).

Группа Векторная БД (PGVector)

Переменная

Описание

DB_HOST

Хост PostgreSQL с PGVector

DB_PORT

Порт PostgreSQL

DB_NAME

Имя базы данных

DB_USER

Пользователь БД

DB_PASSWORD

Пароль БД
Группа Checkpoint DB (сессии)

Переменная

Описание

CHECKPOINT_DB_HOST

Хост PostgreSQL для checkpoint

CHECKPOINT_DB_PORT

Порт PostgreSQL

CHECKPOINT_DB_NAME

Имя базы данных

CHECKPOINT_DB_USER

Пользователь БД

CHECKPOINT_DB_PASSWORD

Пароль БД
Группа Dataset DB (feedback)

Переменная

Описание

DATASET_DB_HOST

Хост PostgreSQL для Dataset DB

DATASET_DB_PORT

Порт PostgreSQL

DATASET_DB_NAME

Имя базы данных

DATASET_DB_USER

Пользователь БД

DATASET_DB_PASSWORD

Пароль БД
Группа Phoenix (трейсинг)

Переменная

Описание

PHOENIX_ENDPOINT

URL Phoenix для отправки трейсов

PHOENIX_PROJECT_NAME

Имя проекта в Phoenix
Группа Tools (флаги включения)

Переменная

Описание

PLATFORM_API_TOOLS_ENABLED

Включить Platform API Tools
Группа Auth (авторизация)

Переменная

Описание

Примечание

AUTH_ENABLED

Включает авторизацию (true / false)

AUTH_MODE

Режим авторизации: ASSISTANT, PLATFORM или DUAL

Актуальна до модернизации JWT платформы

AUTH_CLIENTS_FILE

Путь к файлу с учётными данными клиентов (JSON)

TLS_INSECURE

Отключает проверку TLS-сертификатов (true / false)
Группа Прочее

Переменная

Описание

DEFAULT_LANGUAGE

Язык по умолчанию

WELCOME_NODE_ENABLED

Включает welcome-ноду (true / false)

HF_HOME

Путь к кэшу моделей HuggingFace

Зависимости при старте:

  • Векторная БД (PGVector) должна быть доступна и содержать данные базы знаний.

  • Checkpoint DB должна быть доступна. Таблицы создаются автоматически при старте через PostgresSaver.setup().

  • LLM-провайдер должен быть доступен по параметрам, указанным на странице настройки ассистента.

Опциональные зависимости (могут быть недоступны без потери основной функциональности):

  • Dataset DB — для сохранения обратной связи: like, dislike.

  • Phoenix — для отправки трейсов.

  • Platform API — для Platform API Tools (при PLATFORM_API_TOOLS_ENABLED=true).

Локальная БД (PostgreSQL + PGVector)

Локальная БД — единый контейнер PostgreSQL, обслуживающий две базы данных:

  • Векторная БД (PGVector) — используется для хранения документов базы знаний в виде векторных эмбеддингов для RAG-поиска;

  • Checkpoint DB — используется для хранения состояния сессий LangGraph — истории переписки.

Технологии:

  • PostgreSQL 16.9

  • Расширение pgvector 0.8.0

Docker-образ cобирается из dev/db/Dockerfile на базе postgres:16.9. Компилирует и устанавливает pgvector из исходников.

Порты

Порт внутри контейнера

Порт на хосте

Протокол

Назначение

5432

5433

TCP (PostgreSQL)

Подключение к PostgreSQL
Volumes

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

Источник на хосте

Назначение

/var/lib/postgresql/data/

./dev/db/data или ./db/data

Персистентное хранение данных PostgreSQL
Переменные окружения

Переменная

Описание

POSTGRES_DB

Имя основной БД (по умолчанию: rag)

POSTGRES_USER

Пользователь БД (по умолчанию: rag)

POSTGRES_PASSWORD

Пароль БД (по умолчанию: rag)

Инициализация:

  • При первом запуске PostgreSQL создаёт основную БД (rag) с учётными данными из переменных окружения.

  • В Checkpoint DB таблицы создаются автоматически при старте ассистента через PostgresSaver.setup() — отдельная миграция не требуется.

  • В векторной БД данные загружаются Flyway-миграциями.

Flyway-миграции базы знаний

Контейнер, выполняющий миграции для инициализации и обновления данных в векторной БД — база знаний. Запускается один раз при развёртывании, после завершения миграций останавливается.

Технологии: Flyway (официальный Docker-образ flyway/flyway:latest)

Фактическая схема таблиц векторной базы знаний:

  1. public.langchain_pg_collection

    • uuid (uuid, NOT NULL) — первичный ключ;

    • name (varchar, NOT NULL) — уникальное имя коллекции (UNIQUE);

    • cmetadata (json, NULL) — метаданные коллекции.

  2. public.langchain_pg_embedding

    • id (varchar, NOT NULL) — первичный ключ;

    • collection_id (uuid, NULL) — внешний ключ → langchain_pg_collection.uuid (ON DELETE CASCADE);

    • embedding (vector, NULL) — вектор эмбеддинга;

    • document (varchar, NULL) — текст документа/чанка;

    • cmetadata (jsonb, NULL) — метаданные чанка;

    • индекс ix_cmetadata_gin (GIN, jsonb_path_ops) по cmetadata.

Dataset DB

Используется для хранения обратной связи пользователей (like/dislike/neutral) по ответам ассистента. Полученные данные используются для анализа качества.

Размещается на внешнем контуре (TantorLabs).

Технологии: PostgreSQL

Схема данных: Таблица dataset (создаётся Flyway-миграцией V1__Create_datasets_table.sql):

  • message_id, session_id — идентификаторы сообщения и сессии

  • user_message, assistant_message — тексты

  • span_id — корреляция с трейсами Phoenix

  • feedback — оценка (like / dislike / neutral)

  • start_time, end_time, created_at, updated_at

Сетевое взаимодействие: Ассистент → Dataset DB по протоколу PostgreSQL (TCP, порт 5432). Подключение настраивается через DATASET_DB_* переменные окружения.

Phoenix (трейсинг)

Используется для сбора, хранения и визуализации трейсов запросов к ассистенту, а также для отладки, мониторинга качества и анализа производительности.

Размещается на внешнем контуре (TantorLabs).

Технологии: Arize Phoenix, OpenTelemetry (OTLP)

Порты (на внешнем контуре)

Порт

Протокол

Назначение

6006

HTTP

UI Phoenix + приём трейсов (OTLP/HTTP)

Сетевое взаимодействие: Ассистент → Phoenix по протоколу OTLP/HTTP (порт 6006). Подключение настраивается через PHOENIX_ENDPOINT.

LLM-провайдер

Ассистент использует языковую модель (LLM) для генерации ответов, классификации вопросов, извлечения ключевых слов и tool-calling.

Размещается на внешнем контуре.

Варианты подключения:

  • удалённый LLM-сервер Tantor — централизованный инференс-сервер;

  • локальный инференс-сервер — Ollama, vLLM или аналог, развёрнутый на контуре клиента или рядом;

  • публичный провайдер — OpenAI, z.ai, Claude и другие.

Протокол: OpenAI-совместимый API (HTTP/HTTPS). Подключение любого провайдера, поддерживающего этот API.

Сетевое взаимодействие: Ассистент → LLM-провайдер по HTTP/HTTPS. Подключение настраивается через следующие переменные:

  • LLM_BASE_URL — базовый URL API (например: http://127.0.0.1:11434/v1);

  • LLM_API_KEY — API-ключ для авторизации;

  • USED_MODEL — имя используемой модели.

Сетевые взаимодействия

Источник

Назначение

Протокол

Порт

Направление

Обязательность

Платформа UI

AI-ассистент

HTTP (SSE)

8090

Клиент — Клиент

Обязательно

Платформа UI

AI-ассистент

HTTP/HTTPS (REST)

8090

Клиент — Клиент

Обязательно

AI-ассистент

Локальная БД

PostgreSQL (TCP)

5432 (5433 хост)

Клиент — Клиент

Обязательно

AI-ассистент

LLM-провайдер

HTTP/HTTPS

настраивается

Клиент — Внешний

Обязательно

AI-ассистент

Platform API

HTTP/HTTPS

настраивается

Клиент — Клиент

Опционально

AI-ассистент

Dataset DB

PostgreSQL (TCP)

5432

Клиент — Внешний

Опционально

AI-ассистент

Phoenix

HTTP (OTLP)

6006

Клиент — Внешний

Опционально

Flyway-миграции

Локальная БД

PostgreSQL (TCP)

5432

Клиент — Клиент

При развёртывании

Инициализация с нуля

При развёртывании системы с нуля происходит следующее:

  1. PostgreSQL запускается и создаёт основную БД (rag) с пользователем из переменной POSTGRES_USER/POSTGRES_PASSWORD.

  2. Flyway подключается к БД и выполняет SQL-миграции, которые выполняют следующие шаги:

    • создают расширение pgvector, если миграция содержит CREATE EXTENSION vector;

    • загружают данные базы знаний — чанки документов с эмбеддингами.

  3. После старта AI-ассистент выполняет следующие шаги:

    • подключается к БД rag как к векторной БД через DB_* переменные;

    • подключается к той же БД rag как к checkpoint DB через CHECKPOINT_DB_* переменные;

      Важно

      Обе базы находятся в одном PostgreSQL-экземпляре.

    • вызывает PostgresSaver.setup(), который автоматически создаёт необходимые таблицы для checkpoint;

    • загружает модель эмбеддингов intfloat/multilingual-e5-large из кэша /hf_cache или скачивает из HuggingFace.

При развёртывании должны быть выполнены следующие условия:

  • volume /hf_cache должен содержать предзагруженную модель эмбеддингов или контейнер ассистента должен иметь доступ к HuggingFace для скачивания (~2.2 ГБ);

  • flyway-миграции должны содержать полный дамп базы знаний.

Конфигурация для контура клиента

При установке необходимо задать следующий набор переменных в env-файле:

# === Обязательные ===

# Локальная БД (обычно localhost внутри docker network) DB_HOST=postgres DB_PORT=5432 DB_NAME=rag DB_USER=rag DB_PASSWORD=<secure-password>

# Checkpoint DB (та же БД) CHECKPOINT_DB_HOST=postgres CHECKPOINT_DB_PORT=5432 CHECKPOINT_DB_NAME=rag CHECKPOINT_DB_USER=rag CHECKPOINT_DB_PASSWORD=<secure-password>

# Авторизация AUTH_ENABLED=true AUTH_MODE=PLATFORM AUTH_CLIENTS_FILE=/app/clients.json TLS_INSECURE=false

# === Опциональные (внешние сервисы) ===

# Dataset DB (TantorLabs) DATASET_DB_HOST=<dataset-db-host> DATASET_DB_PORT=5432 DATASET_DB_NAME=dataset DATASET_DB_USER=<user> DATASET_DB_PASSWORD=<password>

# Phoenix (TantorLabs) PHOENIX_ENDPOINT=http://<phoenix-host>:6006 PHOENIX_PROJECT_NAME=<client-name>

# Platform API Tools (если нужна работа с алертами и т.д.) PLATFORM_API_TOOLS_ENABLED=false

# Прочее DEFAULT_LANGUAGE=Russian WELCOME_NODE_ENABLED=true HF_HOME=/hf_cache

Настройка LLM:

  • LLM_BASE_URL, LLM_API_KEY, USED_MODEL передаются из Платформы в новый endpoint ассистента.

  • Переменные можно указать в env-файле:

    LLM_BASE_URL=http://<llm-host>:<port>/v1 LLM_API_KEY=<api-key> USED_MODEL=<model-name>

  • Чтобы сохранить значения между рестартами, используется settings.json (volume: /app/settings.json)