# Техническая документация проекта: Юридический AI-ассистент (RAG Система)
## 1. Концепция и методология RAG
**Что такое RAG в данном проекте?**
Мы не просто отправляем вопрос в ChatGPT. Мы реализуем архитектуру **Retrieval-Augmented Generation**. Это необходимо для того, чтобы LLM не галлюцинировала законы, а отвечала строго по тексту загруженных документов.
**Принцип работы:**
1. **Поиск:** Запрос пользователя превращается в вектор. В базе данных находятся фрагменты законов, семантически близкие к запросу
2. **Дополнение:** Найденные фрагменты подклеиваются к промпту пользователя в качестве контекста
3. **Генерация:** 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 и интерфейсы для контрактов, что обеспечивает изоляцию компонентов и легкость изменений.
## Диаграмма компонентов системы
``` mermaid
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
``` mermaid
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: Текст консультации + Ссылки на статьи
```
## Схема индексации
``` mermaid
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
```
## Схема БД
``` mermaid
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"
```