Assistant Flow

Мультимодальная AI-платформа для работы с корпоративными знаниями, AI-ассистентами и эксплуатацией AI-сервисов.

RAG и операционная консоль встроены в уже существующий мультимодальный контур обработки запросов, а не заменяют его.

Бизнес-сценарий и идея

Во многих компаниях знания существуют, но ими сложно пользоваться.

Регламенты лежат в PDF-файлах и папках.
Инструкции быстро устаревают.
Поддержка отвечает на одни и те же вопросы.
Новые сотрудники долго разбираются во внутренних процессах.
AI-боты часто работают как «черный ящик», когда невозможно понять, почему был получен тот или иной ответ.

Assistant Flow создается как единая AI-платформа, которая объединяет:

AI-ассистента в Telegram;
текстовые, голосовые, графические сценарии и OCR с фотографий;
память диалога;
поиск по корпоративной базе знаний (RAG);
диагностику AI-контуров;
контроль качества ответов;
эксплуатационную телеметрию.

Платформа ориентирована не только на генерацию ответов, но и на полноценную эксплуатацию AI-систем:

с диагностикой;
трассировкой обработки запросов;
наблюдаемостью поиска по базе знаний;
анализом качества ответов;
управлением индексами документов;
поддержкой нескольких AI-провайдеров.

Основные возможности платформы

Мультимодальные сценарии

Assistant Flow изначально рассчитан на несколько типов запросов в одном Telegram-боте:

текстовые ответы и диалог;
RAG-запросы по корпоративной базе знаний;
генерация изображений по описанию;
голос: распознавание речи (STT) и озвучивание (TTS), если включено в окружении;
OCR / Vision — извлечение текста с фото через OpenAI Vision.

Примеры формулировок в Telegram:

«объясни простыми словами, что такое фотосинтез» — текстовый режим;
«дай полную сводку по компании NovaTex» — RAG по проиндексированным документам;
«распознай текст на изображении» — OCR (режим /mode ocr или подпись к фото);
«нарисуй слона в посудной лавке» — генерация изображения в текстовом режиме.

Текстовые AI-сценарии

Assistant Flow поддерживает текстовые AI-ответы через Telegram и административную консоль.

Платформа:

определяет тип запроса;
запускает нужный сценарий обработки;
сохраняет историю взаимодействия;
отображает этапы обработки;
фиксирует задержки и техническую телеметрию.

📷 Скриншоты:

Пример текстового ответа Telegram-ассистента в режиме обычного диалога.

Консоль текстового pipeline: параметры LLM-запроса, telemetry и таймлайн обработки text-response.

Работа с базой знаний (RAG)

Платформа поддерживает полноценный контур поиска по базе знаний:

загрузку документов;
индексацию;
разбиение документов на смысловые фрагменты;
поиск релевантной информации;
настройку параметров поиска;
анализ найденных чанков;
диагностику поиска;
выбор backend векторного поиска (Chroma / FAISS / Weaviate).

Через административную консоль можно наблюдать RAG-сессии, анализировать чанки, настраивать поиск и переключать backend векторного хранилища.

📷 Скриншоты:

RAG-ответ Telegram-ассистента на основе корпоративной базы знаний Assistant Flow.

Операционная консоль RAG-сессий с диагностикой retrieval, latency, cache-state и найденных чанков.

Расширенная диагностика retrieval: найденные чанки, relevance-score, latency retrieval и состояние retrieval cache.

Управление документами knowledge base: индексация, preprocessing, версии документов и жизненный цикл ingestion pipeline.

Панель управления retrieval backend: переключение vector storage, runtime tuning, chunking и cache-настройки RAG.

Кэширование запросов к базе знаний

Повторяемые RAG-запросы можно ускорять кэшем результатов поиска. В консоли видны состояния OFF / MISS / HIT и задержки поиска. Включение и TTL — в Retrieval Settings или через .env (подробности — docs/architecture/cache_layer_design.md).

📷 Скриншот:

Сравнение retrieval cache MISS и HIT: снижение latency retrieval при повторном запросе.

Память диалога

Платформа запоминает контекст разговора с пользователем: можно продолжить диалог без повторения вводных. История хранится в PostgreSQL (при настроенной БД); размер контекста, передаваемого модели, ограничивается, чтобы ответы оставались устойчивыми и предсказуемыми.

Оператор в административной консоли (Memory, /memory) видит сессии, реплики и диагностику того, как память повлияла на ответ.

📷 Скриншот:

Диагностика runtime memory: контекст диалога, trimming history и политика ограничения conversational memory.

Голосовые сценарии

Платформа поддерживает:

распознавание речи (STT);
синтез речи (TTS);
голосовые ответы;
диагностику аудио-сценариев;
телеметрию голосовых AI-контуров.

📷 Скриншоты:

Пример голосового взаимодействия с Telegram-ассистентом: распознавание речи и генерация аудио-ответа.

Операционная консоль voice pipeline: STT/TTS telemetry, аудио-сессия и таймлайн обработки голосового запроса.

Генерация изображений

Assistant Flow поддерживает генерацию изображений по текстовому описанию.

Платформа:

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

📷 Скриншоты:

Пример генерации изображения Telegram-ассистентом по текстовому запросу пользователя.

Консоль генерации изображений: refined prompt, telemetry image pipeline и сохранённый generated asset.

Распознавание текста (OCR)

Распознавание выполняется через OpenAI Vision (без локальных OCR-библиотек). Нужны OPENAI_API_KEY и vision-capable модель из .env.

Как запустить:

режим /mode ocr — отправьте фото (подпись необязательна);
в режимах text или rag — фото с подписью, где явно просят прочитать текст, например: «распознай текст», «OCR», «извлеки текст», «прочитай изображение».

Ответ приходит одним сообщением с распознанным текстом. В режиме OCR подпись может уточнить задание для vision-модели (например «объясни простыми словами, что написано») — это один вызов Vision, без отдельного текстового ассистента после OCR.

Ограничения: качество зависит от снимка; хуже распознаются размытые кадры, рукопись, мелкий шрифт и сложные таблицы. RAG по содержимому изображения без OCR отдельно не запускается.

📷 Скриншоты:

Пример OCR-обработки изображения в Telegram: распознавание текста средствами OpenAI Vision.

OCR/Vision pipeline: распознавание изображения, telemetry обработки и извлечённый текст документа.

Подробнее — USER_GUIDE.md.

Операционная консоль

Административная консоль предназначена для эксплуатации и наблюдаемости AI-платформы.

Консоль позволяет:

контролировать состояние платформы;
анализировать AI-сессии;
наблюдать этапы обработки запросов;
анализировать этапы поиска по базе знаний;
управлять индексацией документов;
наблюдать память диалога;
анализировать качество RAG;
отслеживать техническую телеметрию AI-контуров.

Основной UI: frontend/admin-ui (React). Пункты бокового меню (как в коде):

Раздел	Путь
Обзор	`/`
Сводка	`/summary`
Текст	`/text`
RAG	`/rag`
Изображения	`/images`
Аудио	`/audio`
Документы	`/documents`
Retrieval Settings	`/retrieval`
Логи	`/logs`
Memory	`/memory`
Анализ RAG	`/evaluation`

📷 Скриншоты:

Обзор состояния платформы Assistant Flow: health-check сервисов, активные AI-провайдеры, retrieval backend и операционные метрики.

Сводная операционная статистика платформы: маршруты обработки, этапы pipeline, телеметрия провайдеров и агрегированные метрики.

Журнал execution-сессий и трассировка pipeline обработки запросов Assistant Flow.

Анализ качества RAG

В платформу встроен отдельный контур оценки качества RAG и AI-ответов.

Поддерживаются:

RAGAS;
ручная оценка ответов;
анализ точности поиска;
анализ найденных чанков;
оценка faithfulness;
оценка relevance.

Это позволяет не только запускать RAG, но и контролировать качество работы поиска по базе знаний.

📷 Скриншоты:

Консоль оценки качества RAG: RAGAS-метрики, ручная валидация ответов и анализ retrieved chunks.

Сравнение отдельных RAG-сессий внутри evaluation run с отображением метрик quality evaluation.

Типовой сценарий работы

Оператор загружает документы в административную консоль.
Платформа индексирует базу знаний.
Пользователь задаёт вопрос в Telegram.
Система выполняет поиск по базе знаний и формирует ответ.
Оператор просматривает диагностику запроса в консоли (RAG, логи, задержки).

Архитектура платформы

Assistant Flow состоит из нескольких связанных контуров. Ниже — схема верхнего уровня (без деталей реализации).

flowchart TD
    TG[Telegram] --> BOT[Telegram-бот]
    UI[Admin UI] --> API[Admin API]

    BOT --> ORCH[Оркестратор запросов]
    API --> ORCH

    ORCH --> TEXT[Текстовый контур]
    ORCH --> RAG[RAG]
    ORCH --> OCR[OCR]
    ORCH --> VOICE[Voice STT/TTS]
    ORCH --> IMG[Генерация изображений]
    ORCH --> MEM[Memory]

    TEXT --> PROV[AI providers<br/>OpenAI · GigaChat · Proxy API]
    RAG --> PROV
    OCR --> PROV
    VOICE --> PROV
    IMG --> PROV

    RAG --> CACHE[Retrieval Cache]
    CACHE --> RET[Retrieval backends<br/>Chroma · FAISS · Weaviate]
    RAG --> PG[(PostgreSQL<br/>metadata · sessions · logs)]

    MEM --> PG
    API --> PG

    STOR[Asset / Storage<br/>assets · documents · outputs]
    IMG --> STOR
    OCR --> STOR
    API --> STOR

    ORCH --> OBS[Логи и телеметрия]
    API --> OBS

Пользовательский контур

Поддерживает:

Telegram-интерфейс;
текстовые сценарии;
голосовые сценарии;
генерацию изображений;
RAG-запросы.

Контур обработки запросов

Маршрутизация по типу запроса, контуры обработки AI, память диалога, логирование и диагностика этапов.

Контур базы знаний

Загрузка документов, индексация, метаданные чанков, настройка поиска и опциональный кэш повторных запросов.

Контур наблюдаемости

Поддерживаются:

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

Технологический стек

Backend

Python
FastAPI
PostgreSQL
ChromaDB
Weaviate
FAISS

Frontend

React
Vite

AI-провайдеры

OpenAI
GigaChat
Proxy API

Инфраструктура

Docker
Docker Compose (docker-compose.portfolio.yml)

Структура проекта

assistant-flow/
├── admin_api/              # FastAPI Admin API
├── core/                   # оркестрация запросов
├── providers/              # клиенты AI-провайдеров, embeddings
├── services/               # RAG, поиск, кэш, evaluation, индексация
├── interfaces/             # Telegram-бот (run_telegram_bot.py)
├── repositories/           # PostgreSQL
├── database/               # schema.sql, миграции
├── frontend/
│   └── admin-ui/           # React операционная консоль (Vite)
├── docs/                   # архитектура, OPERATIONS, screenshots/
├── evaluation/             # датасеты и контур оценки качества
├── scripts/                # smoke, индексация, утилиты
├── storage/                # FAISS, SQLite cache, assets (volume в compose)
├── utils/                  # AppConfig, общие утилиты
├── docker-compose.portfolio.yml
├── .env.example
├── RUNBOOK.md
├── USER_GUIDE.md
├── PROJECT_STATE.md
└── README.md

Развертывание

Каноническая команда для локального демо и GitHub (проект compose portfolio-test):

cp .env.example .env
COMPOSE_BAKE=false docker compose -p portfolio-test -f docker-compose.portfolio.yml up -d --build --remove-orphans

Поднимаются сервисы: postgres, chroma, weaviate, assistant-flow (Telegram), admin-api, admin-ui.

Порты на хосте (по умолчанию):

Сервис	Порт
Admin UI	8080
Admin API	8600
PostgreSQL	5433 → 5432 в сети compose
Chroma HTTP	8001 → 8000
Weaviate HTTP	8089 → 8080

Volumes: ./data/documents, ./storage, ./outputs → контейнеры assistant-flow и admin-api.

Проверка после запуска:

curl -sS http://localhost:8600/api/health
# браузер: http://localhost:8080 (UI), API: http://localhost:8600

Подробные эксплуатационные процедуры, SSH-туннель и типовые сбои — в RUNBOOK.md.

Конфигурация (.env)

cp .env.example .env — только плейсхолдеры в git; секреты не коммитить.

Группа	Ключевые переменные
Telegram	`TELEGRAM_BOT_TOKEN` (реальный токен, не заглушка)
Текст / RAG	`GIGACHAT_`, `OPENAI_API_KEY`, `OPENAI_MODEL`, `OPENAI_EMBEDDING_MODEL`, `PROXY_`
PostgreSQL	`DATABASE_URL` → `postgresql://assistant:assistant@postgres:5432/assistant_flow` (portfolio)
Поиск / кэш	`RAG_BACKEND`, `CHROMA_`, `FAISS_INDEX_DIR`, `WEAVIATE_`, `RAG_DOCUMENTS_DIR`, `ENABLE_RETRIEVAL_CACHE`
Аудио	`AUDIO_ENABLED`, `STT_PROVIDER`, `TTS_PROVIDER` (по умолчанию `disabled`)
Admin UI	`ADMIN_API_CORS_ORIGINS` → `http://localhost:8080`

Полный перечень — .env.example, docs/OPERATIONS.md.

Текущий статус проекта

Стабильные подсистемы

текстовый AI-контур;
RAG-контур;
индексация документов;
диагностика поиска по базе знаний;
кэширование запросов к базе знаний;
техническое логирование;
механизм памяти диалога;
операционная наблюдаемость.

Активно развиваются

React Admin UI;
оценка качества RAG (RAGAS, ENABLE_RAGAS_EVALUATION);
фильтрация поиска по источникам;
кэш готовых ответов (в основном пути не включён).

Roadmap

RUNBOOK.md — восстановление, reindex, диагностика кэша и хранилищ.
Фильтрация поиска по источникам.
Резервная маршрутизация провайдеров (OpenAI / GigaChat / Proxy API).
Улучшение разбиения документов на чанки.
RAGAS и ручная оценка качества в консоли.

Документация проекта

Документ	Назначение
README.md	Общее описание платформы (входная точка GitHub)
RUNBOOK.md	Эксплуатация и диагностика (документ в разработке)
USER_GUIDE.md	Руководство пользователя (документ в разработке)
docs/ARCHITECTURE.md	Архитектура системы
docs/OPERATIONS.md	Compose, env, процедуры развёртывания
PROJECT_STATE.md	Инженерное состояние и backlog
docs/architecture/	Детальные проектные документы (кэш, оценка, UI contract)

Важное замечание

Assistant Flow является инженерным AI-проектом и исследовательской платформой для:

RAG;
мультимодальных AI-сценариев;
эксплуатации AI-систем;
наблюдаемости AI-контуров;
диагностики поиска по базе знаний;
проектирования мультимодальных AI-систем.

Проект активно развивается и используется как практический полигон для разработки и сопровождения AI-сервисов.

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
admin_api		admin_api
admin_ui		admin_ui
core		core
database		database
docs		docs
evaluation/datasets		evaluation/datasets
frontend/admin-ui		frontend/admin-ui
interfaces		interfaces
providers		providers
repositories		repositories
scripts		scripts
services		services
storage/cache		storage/cache
utils		utils
.dockerignore		.dockerignore
.env.example		.env.example
.env.server.example		.env.server.example
.gitignore		.gitignore
Dockerfile		Dockerfile
PROJECT_STATE.md		PROJECT_STATE.md
README.md		README.md
RUNBOOK.md		RUNBOOK.md
USER_GUIDE.md		USER_GUIDE.md
dashboard.py		dashboard.py
docker-compose.assistant.yml		docker-compose.assistant.yml
docker-compose.portfolio.yml		docker-compose.portfolio.yml
main.py		main.py
requirements-ragas.txt		requirements-ragas.txt
requirements.txt		requirements.txt
run_admin_api.py		run_admin_api.py
run_telegram_bot.py		run_telegram_bot.py
Текстовый документ.txt		Текстовый документ.txt

Folders and files

Latest commit

History

Repository files navigation

Assistant Flow

Бизнес-сценарий и идея

Основные возможности платформы

Мультимодальные сценарии

Текстовые AI-сценарии

Работа с базой знаний (RAG)

Кэширование запросов к базе знаний

Память диалога

Голосовые сценарии

Генерация изображений

Распознавание текста (OCR)

Операционная консоль

Анализ качества RAG

Типовой сценарий работы

Архитектура платформы

Пользовательский контур

Контур обработки запросов

Контур базы знаний

Контур наблюдаемости

Технологический стек

Backend

Frontend

AI-провайдеры

Инфраструктура

Структура проекта

Развертывание

Конфигурация (.env)

Текущий статус проекта

Стабильные подсистемы

Активно развиваются

Roadmap

Документация проекта

Важное замечание

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages