248 lines
13 KiB
Markdown
248 lines
13 KiB
Markdown
# Техническая документация проекта: Юридический 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<br>2. **FSM Storage:** Хранение состояний диалога бота<br>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"
|
||
``` |