QA-RAG-Platform

QA-RAG-Platform — мультитенантная open-source платформа агентного Retrieval-Augmented Generation. Отвечает на вопросы пользователей по корпоративной базе знаний, выполняет анализ данных по загруженным файлам, обрабатывает изображения и аудио. Ядро — LangGraph-агент с интент-роутингом, гибридным поиском (Qdrant dense + BM25 + reranker), SGR-генерацией с цитированиями, долговременной памятью (Mem0) и петлёй валидации/репарации ответов.

---

Задача, для кого, какая боль

Задача. Корпоративный Q&A по разнородным внутренним данным (PDF, DOCX, XLSX, PPTX, скан-документы, аудио, изображения) с проверяемыми цитатами и контролем галлюцинаций.

Для кого.

• Внутренние пользователи (поддержка, аналитика, юристы, продакты) — задают вопросы и получают ответы со ссылками на исходники.
• ML/Platform-команды — разворачивают платформу под свои данные без переписывания ядра.
• Администраторы — управляют тенантами, моделями (LiteLLM-роутинг, GigaChat / YandexGPT / OpenAI-совместимые / локальный vLLM), правами и аудитом.

Боль.

• ChatGPT-подобные сервисы не видят внутренних документов и нельзя проверить, откуда взялся факт.
• «Самосбор» RAG (LangChain + Qdrant + LLM) ломается на проде: галлюцинации без цитат, нет ретраев, нет управления токеновым бюджетом, нет долговременной памяти, нет тенантной изоляции, нет наблюдаемости.
• Готовые SaaS не подходят для закрытых контуров с требованием on-prem развёртывания.

---

Что именно сделает PoC на демо

1. Загрузка и индексация документов. Юзер заливает PDF/DOCX/XLSX через UI → файл уходит в S3 (MinIO) → RabbitMQ ставит ingest-job → воркер парсит (PyMuPDF / docling / OCR через Qwen2-VL для скан-PDF) → чанкует → эмбедит (BAAI/bge-m3) → индексирует в Qdrant + BM25 в namespace тенанта.
2. Агентный Q&A с цитатами. Юзер задаёт вопрос → LangGraph определяет интент (rag / image / data-analysis / clarify) → агентный RAG-подграф: hybrid retrieve → CrossEncoder rerank → grading релевантности → при необходимости query rewrite/decomposition → SGR-генерация со ссылками на конкретные чанки → валидация цитат → если что-то не сошлось — репарация (до N попыток).
3. Долговременная память. Mem0 на Qdrant — извлекает факты из диалога, при следующем обращении подмешивает релевантный контекст пользователя.
4. Multi-route оркестрация. Тот же агент умеет: генерация картинок (FLUX), анализ изображений (Qwen2-VL), анализ Excel/CSV-файлов через ReAct + изолированный sandbox (Firecracker), делегирование внешним агентам по A2A.
5. Наблюдаемость и качество. Каждый запрос трассируется в Langfuse: интент, retrieve-метрики, токены, цена, валидация цитат, latency по нодам. Eviction по TTL для чат-скопированных коллекций.
6. Multi-tenant изоляция. Qdrant-коллекции именуются {tenant_id}_{kb_id} и {tenant_id}_{chat_id} — кросс-тенантного доступа быть не должно ни в одном пути.

Демо запускается через make docker-up (pilot-стек без GPU, внешний LLM-провайдер) либо make docker-up-gpu (полный стек с локальным vLLM).

---

Что НЕ делает PoC (явные out-of-scope)

• Fine-tuning LLM/эмбеддера на пилотных данных. Используем готовые модели (bge-m3, bge-reranker-v2-m3, внешний LLM или vLLM). SFT-пайплайн зарезервирован, но в PoC не задействован.
• Real-time стриминг ASR. Whisper работает в batch-режиме через RabbitMQ.
• Self-service onboarding и биллинг конечных пользователей. Регистрация — JWT, биллинг — out-of-scope.
• Кросс-тенантный поиск и федеративный RAG. Каждый тенант изолирован.
• Тонкая RBAC-модель прав на отдельные документы. Право доступа задаётся уровнем «база знаний», не «документ».
• Автономное обучение агента / online learning. Все политики routing/grading/repair — детерминированные или промптовые, без RL/обновления весов.
• Поддержка нестандартных модальностей (видео, 3D, robotics). Только текст, табличные данные, изображения, аудио.
• Multi-region high availability. PoC — одна инсталляция, без active-active гео-репликации.

---

Быстрый старт

git clone <repo> qa-rag-platform
cd qa-rag-platform
cp platform-api/.env.example platform-api/.env  # отредактировать LLM_API_KEY и QDRANT_URL
make docker-up           # pilot: infra + rag-api, без GPU, внешний LLM
make migrate             # применить alembic-миграции
make ui-build            # собрать SPA, FastAPI отдаст её на /ui
open http://localhost:8000/ui

Полный стек с локальным vLLM (GPU): make docker-up-gpu. Подробнее — docs/architecture-system.md.

---

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

Milestone 1 — согласование проекта (docs/milestone-1/)

• product-proposal.md — обоснование, цели, метрики, сценарии, ограничения, архитектурный набросок, data flow.
• governance.md — Risk register, политика логов и ПДн, защиты от injection, подтверждение действий.

Milestone 2 — системный дизайн (docs/milestone-2/)

• system-design.md — ключевые архитектурные решения, модули, workflow, state/memory/context, retrieval, tool/API, failure modes, fallbacks, guardrails, SLO/cost.
• diagrams/ — C4 (Context / Container / Component), workflow с ветками ошибок, data flow.
• specs/ — спецификации модулей: retriever, tools/APIs, memory/context, agent/orchestrator, serving/config, observability/evals.

Глубокая техническая документация (уже существующая, дополняет milestones): docs/architecture-system.md, docs/architecture.md, docs/retrieval-internals.md, docs/observability.md, docs/security.md, docs/adr/.

---

Команды (через make)

make lint          # ruff check platform-api/
make format        # ruff format platform-api/
make typecheck     # pyright platform-api/app/
make test          # pytest platform-api/tests/ -v
make migrate       # alembic upgrade head
make migrate-create msg="description"
make eviction      # TTL eviction (python -m app.rag.eviction)

make docker-up        # pilot: infra + rag-api (external LLM)
make docker-up-full   # full stack без GPU
make docker-up-gpu    # full stack с vLLM + ASR
make docker-down

make ui-dev    # Vite dev на :3000 (proxy → :8000)
make ui-build  # сборка в ui/dist, отдаётся FastAPI на /ui

---

Структура репозитория

qa-rag-platform/
├── platform-api/         # FastAPI + LangGraph агент + RAG pipeline
│   ├── app/
│   │   ├── api/v1/        # роутеры (chat, ingest, transcribe, admin, ...)
│   │   ├── agent/         # LangGraph: graphs/, nodes/, domain/state.py
│   │   ├── rag/           # pipeline, retrieval/, generation/sgr.py, eviction
│   │   ├── store/         # qdrant_store.py (hybrid: vector + BM25)
│   │   ├── orchestrator/  # intent_service, handlers, code_interpreter
│   │   ├── services/      # llm/, infra/, memory/, vision, image-gen, a2a
│   │   └── config.py      # pydantic Settings
│   ├── domain/            # SQLAlchemy ORM модели
│   ├── migrations/        # Alembic
│   └── workers/ingest_worker.py
├── encoder/              # bge-m3 эмбеддер (Triton)
├── asr/                  # Whisper transcription
├── vllm-service/         # vLLM инференс (text + Qwen2-VL)
├── image-gen/            # FLUX text-to-image
├── opensandbox/          # Firecracker sandbox для code interpreter
├── litellm/              # LiteLLM proxy для роутинга LLM-провайдеров
├── ui/                   # React + TypeScript + Vite SPA
├── deploy/, helm/        # k8s манифесты, Helm-чарт, мониторинг
├── docs/                 # архитектурная документация (см. Milestone 1)
└── docker-compose.*.yml  # pilot, full, monitoring, litellm

---

Лицензия

MIT. См. LICENSE.