Что такое RAG в данном проекте? Мы не просто отправляем вопрос в ChatGPT. Мы реализуем архитектуру Retrieval-Augmented Generation. Это необходимо для того, чтобы LLM не галлюцинировала законы, а отвечала строго по тексту загруженных документов.

Принцип работы:

Поиск: Запрос пользователя превращается в вектор. В базе данных находятся фрагменты законов, семантически близкие к запросу
Дополнение: Найденные фрагменты подклеиваются к промпту пользователя в качестве контекста
Генерация: LLM генерирует ответ, используя только предоставленный контекст, и проставляет ссылки

2. Функциональность

Пользователь (юрист или сотрудник компании) взаимодействует с системой через Telegram-бот. Примеры интерфейса:

Отправка запроса: Пользователь пишет сообщение, например: "Найди все договоры поставки с компанией ООО "Ромашка" или "Какая ответственность за неуплату налогов ИП?". Бот отвечает на естественном языке, с точными фактами и обязательными ссылками на источники (например, "Согласно статье 122 Налогового кодекса РФ")
Выбор коллекции: Пользователь может выбрать доступную его компании коллекцию документов (список доступных коллекций отображается) и далее задавать вопросы в рамках нее
Создание коллекций: Любой пользователь может создать собственную коллекцию через админпанель и выбрать логины пользователей, которые имеют право ей пользоваться
Добавление данных: Админы коллекций через панель могут добавлять документы в свою коллекцию
Подписка: После 10 бесплатных запросов бот предлагает оплатить подписку через встроенный платежный сервис
Источники: Каждый факт в ответе сопровождается ссылкой, например, "Документ: Налоговый кодекс РФ, статья 122"
Просмотр коллекций: Пользователь может просмотреть список с именами и описаниями доступных коллекций

3. Стек технологий и обоснование

Компонент	Технология	Обоснование выбора
Backend API	FastAPI	Асинхронность для работы с LLM стримами, легкая интеграция DI, валидация аднных
Telegram Bot	Aiogram	Асинхронный, нативная поддержка машин состояний, мощный механизм мидлвара для логирования и авторизации.
Vector DB	Qdrant	Высокопроизводительная БД на Rust. Поддерживает гибридный поиск и фильтрацию по метаданным из коробки.
Cache & Bus	Redis	1. Кэширование RAG: Хранение пар вопрос-ответ для экономии денег на LLM 2. FSM Storage: Хранение состояний диалога бота 3. Rate Limiting: Подсчет количества запросов пользователя
Main DB	PostgreSQL	Хранение профилей пользователей, логов чатов, конфигураций коллекций и данных для биллинга
LLM	DeepSeek	Использование API внешних провайдеров

4. API Интерфейс

Бэкенд предоставляет REST API, документированное по стандарту OpenAPI. Полная swagger спецификация представлена в файлах вместе с данным документом (AI_api.yaml)

5. Какие задачи необходимо выполнить

Разработка backend (FastAPI): Создать API для обработки запросов, интеграции с БД, эмбеддингом и LLM. Включает DDD, Dependency Injection (dishka), асинхронность. Также сервис авторизации.
Telegram-бот (aiogram): Интеграция с API, авторизация, обработка сообщений, команд для коллекций и платежей.
Векторная БД (Qdrant): Настройка для хранения embeddings, коллекций (в сущностях DocumentCollection, Embeddings).
Индексатор и Поисковик: Реализация предобработки, векторизации и семантического поиска.
Реранкер и Генератор: Модули для реранкинга топ-k и генерации ответов с источниками.
Админ панель: Простой интерфейс для добавления/удаления данных.
Тестирование: Создание тестового датасета с hit@5 > 50%.
Кэширование: Для ускорения похожих запросов.
Платежный сервис: Простая подписка после 10 запросов.
Деплой: Docker-контейнеры для FastAPI и бота.

6. Сколько времени потратится на каждую задачу

Оценки времени (в рабочих днях):

Задача	Время (дни)
Backend (FastAPI)	5
Telegram-бот	4
Векторная БД	2
Индексатор и Поисковик	3
Реранкер и Генератор	4
Админ панель	2
Тестирование	2
Датасет проверки качества	2
Кэширование	2
Платежный сервис	2
Деплой и интеграция	3
Эмбеддинг	2
Итого	33

Общий срок — 4 недели (с учетом параллельной работы команды из 4 человек).

7. Кто что делает в команде

Распределение ролей в команде из 4 человек:

Developer 1 (Lead/Backend): Backend (FastAPI, DDD, DI), Векторная БД, Индексатор/Поисковик.
Developer 2 (AI/ML): Эмбеддинг, Реранкер, Генератор, Тестирование (датасет, метрики).
Developer 3 (Frontend/Bot): Telegram-бот, Админ панель, Платежный сервис.
Developer 4 (DevOps/Tester): Кэширование, Деплой (Docker), тестирование функционала.

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

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

graph TD
    User((Пользователь))
    Admin((Админ))

    subgraph "Интерфейсы"
        TGBot[Telegram Bot
        Aiogram]
        API_Endpoint[API Gateway
        FastAPI]
    end

    subgraph "Бэкенд RAG"
        Logic[Бизнес-логика
        Services & RAG Pipeline]
    end

    subgraph "Базы данных"
        PG[(PostgreSQL
        Users, Logs)]
        VDB[(Vector DB
        Embeddings)]
        Redis[(Redis
        Cache)]
    end

    subgraph "Внешние API"
        LLM[LLM API
        DeepSeek]
        Pay[Payment API
        Yookassa]
    end

    User -->|Команды/Вопросы| TGBot
    TGBot -->|REST| API_Endpoint
    Admin -->|Загрузка документов| API_Endpoint
    
    API_Endpoint --> Logic

    Logic -->|Кэширование| Redis
    Logic -->|Метаданные| PG
    Logic -->|Поиск похожих| VDB
    
    Logic -->|Генерация ответа| LLM
    Logic -->|Транзакции| Pay

Пайплайн RAG

sequenceDiagram
    autonumber
    
    actor User as Юрист
    participant System as Бот + RAG Сервис
    participant VectorDB as Векторная БД
    participant AI as LLM

    Note over User, System: Шаг 1: Запрос
    User->>System: "Статья 5.5, что это?"

    Note over System, VectorDB: Шаг 2: Поиск фактов
    System->>VectorDB: Ищет похожие статьи законов
    VectorDB-->>System: Возвращает Топ-5 документов

    Note over System, AI: Шаг 3: Генерация
    System->>AI: Отправляет промпт
    AI-->>System: Формирует ответ, опираясь на законы

    Note over User, System: Шаг 4: Ответ
    System-->>User: Текст консультации + Ссылки на статьи

Схема индексации

graph TD

    Actor[Администратор / Юрист] -->|Загрузка документа| API[FastAPI]
    API --> Input

    subgraph "1. Предобработка"
        Input[Файл PDF/DOCX] --> Extract(Извлечение текста)
        Extract --> Clean{Очистка}
        Clean -- Удаление шума --> Norm[Нормализация текста]
    end

    subgraph "2. Чанкирование"
        Norm --> Splitter[Разбиение на фрагменты]
        --> Chunks[Список чанков]
    end

    subgraph "3. Векторизация"
        Chunks --> Model[Эмбеддинг модель
        FRIDA]
        Model --> Vectors[Векторные представления]
    end

    subgraph "4. Сохранение"
        Vectors --> VDB[(Векторная БД
        Qdrant)]
        Chunks -->|Заголовок, дата, автор| MetaDB[(Postgres
        Метаданные)]
    end

Схема БД

erDiagram
    USERS {
        uuid user_id PK
        string telegram_id
        datetime created_at
        string role "user / admin"
    }

    COLLECTIONS {
        uuid collection_id PK
        string name
        text description
        uuid owner_id FK
        boolean is_public
        datetime created_at
    }

    DOCUMENTS {
        uuid document_id PK
        uuid collection_id FK
        string title
        text content
        json metadata
        vector vector_embedding "Вектор всего документа"
        datetime created_at
    }

    EMBEDDINGS {
        uuid embedding_id PK
        uuid document_id FK
        vector embedding
        string model_version
        datetime created_at
    }

    CONVERSATIONS {
        uuid conversation_id PK
        uuid user_id FK
        uuid collection_id FK
        datetime created_at
        datetime updated_at
    }

    MESSAGES {
        uuid message_id PK
        uuid conversation_id FK
        text content
        string role "user / ai"
        json sources "Ссылки на использованные документы"
        datetime created_at
    }

    USERS ||--o{ COLLECTIONS : "owner_id"

    USERS ||--o{ CONVERSATIONS : "user_id"

    COLLECTIONS ||--o{ DOCUMENTS : "collection_id"

    COLLECTIONS ||--o{ CONVERSATIONS : "collection_id"

    DOCUMENTS ||--o{ EMBEDDINGS : "document_id"

    CONVERSATIONS ||--o{ MESSAGES : "conversation_id"

README.md Unescape Escape

Техническая документация проекта: Юридический AI-ассистент (RAG Система)

1. Концепция и методология RAG