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

На этой странице описаны все компоненты 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-совместимый эндпоинт. Пример: http://localhost:11434/v1 для Ollama.

LLM_API_KEY

строка

—

API-ключ для доступа к LLM. Если LLM_API_KEY=ai_assistant_api_key, активируется JWT-режим авторизации.

USED_MODEL

строка

—

Имя используемой модели. Например, gpt-oss:20b, gpt-4o.

LLM_REQUEST_TIMEOUT_SECONDS

int

100

Таймаут одного запроса к LLM в секундах.

LLM_MAX_RETRIES

int

2

Максимальное число повторных попыток при ошибке запроса к LLM.

LLM_USE_RESPONSES_API

bool

false

Выбор OpenAI-эндпоинта. Если значение true, используется /v1/responses — новый API, встроенные тулы, reasoning-модели.

Если значение false, используется /v1/chat/completions — максимальная совместимость со всеми провайдерами.

LLM_SAMPLING_PARAMS_ENABLED

bool

true

Включает передачу sampling-параметров: temperature, frequency_penalty, presence_penalty.

Если значение false, параметры не отправляются. Используется для моделей/бэкендов, которые их отвергают.

LLM_TEMPERATURE

float

0.1

Температура сэмплинга. Чем ниже значение, тем более детерминированными будут ответы модели.

Применяется, если LLM_SAMPLING_PARAMS_ENABLED=true.

LLM_FREQUENCY_PENALTY

float

0.2

Штраф за повторение часто встречающихся токенов.

LLM_PRESENCE_PENALTY

float

0.1

Штраф за появление уже использованных токенов.

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

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

Группа Phoenix (трейсинг)

Переменная

Описание

PHOENIX_ENDPOINT

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

PHOENIX_PROJECT_NAME

Имя проекта в Phoenix
Группа Run traces (трейсы запусков)

Переменная

Тип

По умолчанию

Назначение

RUN_TRACE_ENABLED

bool

true

Включает запись пошаговых трейсов запусков. Трейсы хранятся локально в CHECKPOINT_DB.

RUN_TRACE_MAX_ROWS

int

1000

Лимит количества хранимых трейсов. -1 отключает подрезку по этому критерию.

RUN_TRACE_MAX_AGE_DAYS

int

30

Срок хранения трейсов в днях. -1 отключает подрезку по возрасту.

Локальная БД (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) с учётными данными из переменных окружения.

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

Phoenix (трейсинг)

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

Сетевое взаимодействие: Ассистент → 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».

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

Источник

Назначение

Протокол

Порт

Направление

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

Платформа 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-ассистент

Phoenix

HTTP (OTLP)

6006

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

Опционально

Flyway-миграции

Локальная БД

PostgreSQL (TCP)

5432

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

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

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

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

Конфигурация

В процессе установки инсталлятор инициализирует и использует следующие переменные:

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

# Локальная БД (обычно 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