455 lines
16 KiB
Markdown
455 lines
16 KiB
Markdown
# Easy RAG - Система Retrieval-Augmented Generation
|
||
|
||
## Обзор
|
||
|
||
Easy RAG - это мощная система для управления документами и генерации ответов на основе метода Retrieval-Augmented Generation (RAG). Проект реализует полнофункциональное API для загрузки, хранения, поиска и анализа документов с использованием векторных баз данных и современных языковых моделей.
|
||
|
||
### Ключевые возможности
|
||
|
||
- 🔍 **Семантический поиск** по документам с использованием векторных эмбеддингов
|
||
- 📄 **Управление документами** - загрузка, хранение, получение и удаление
|
||
- 🤖 **Интеграция с LLM** - поддержка OpenAI, Ollama и OpenRoute
|
||
- 💾 **Векторная база данных** - использование Milvus для хранения эмбеддингов
|
||
- 🔧 **Модульная архитектура** - легко расширяемая и настраиваемая система
|
||
- 🚀 **RESTful API** - простое и понятное API для интеграции
|
||
- 🐳 **Docker-готовность** - контейнеризация для простого развертывания
|
||
|
||
---
|
||
|
||
## Архитектура системы
|
||
|
||
### Компоненты
|
||
|
||
1. **API слой** (`api/`) - HTTP API на базе Echo Framework
|
||
2. **Основная логика** (`internal/pkg/rag/`) - ядро RAG системы
|
||
3. **Провайдеры LLM** (`internal/llm/`) - интеграция с языковыми моделями
|
||
4. **Провайдеры эмбеддингов** (`internal/embeddings/`) - генерация векторных представлений
|
||
5. **База данных** (`internal/database/`) - работа с векторной БД Milvus
|
||
6. **Обработка текста** (`internal/pkg/textprocessor/`) - разбиение на чанки
|
||
7. **Конфигурация** (`config/`) - управление настройками
|
||
|
||
### Поддерживаемые провайдеры
|
||
|
||
#### LLM (Языковые модели):
|
||
- **OpenAI** - GPT-3.5, GPT-4 и другие модели
|
||
- **Ollama** - локальные открытые модели
|
||
- **OpenRoute** - доступ к различным моделям через единый API
|
||
|
||
#### Эмбеддинги:
|
||
- **OpenAI Embeddings** - text-embedding-ada-002 и новые модели
|
||
- **Ollama Embeddings** - локальные модели эмбеддингов (например, bge-m3)
|
||
|
||
#### Векторная база данных:
|
||
- **Milvus** - высокопроизводительная векторная база данных
|
||
|
||
---
|
||
|
||
## API Документация
|
||
|
||
### Базовый URL
|
||
```
|
||
http://localhost:4002/api/v1
|
||
```
|
||
|
||
### Эндпоинты
|
||
|
||
#### 1. Получить все документы
|
||
```http
|
||
GET /api/v1/docs
|
||
```
|
||
**Описание**: Получить список всех сохраненных документов.
|
||
|
||
**Ответ**:
|
||
```json
|
||
{
|
||
"version": "v1",
|
||
"docs": [
|
||
{
|
||
"id": "document_id",
|
||
"filename": "document.txt",
|
||
"summary": "Краткое описание документа",
|
||
"metadata": {
|
||
"category": "Техническая документация",
|
||
"author": "Автор"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 2. Загрузить документы
|
||
```http
|
||
POST /api/v1/upload
|
||
```
|
||
**Описание**: Загрузить один или несколько документов для обработки и индексации.
|
||
|
||
**Тело запроса**:
|
||
```json
|
||
{
|
||
"docs": [
|
||
{
|
||
"content": "Содержимое документа...",
|
||
"link": "https://example.com/document",
|
||
"filename": "document.txt",
|
||
"category": "Категория",
|
||
"metadata": {
|
||
"author": "Автор",
|
||
"date": "2024-01-01"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**Ответ**:
|
||
```json
|
||
{
|
||
"version": "v1",
|
||
"task_id": "unique_task_id",
|
||
"expected_time": "10m",
|
||
"status": "Обработка начата"
|
||
}
|
||
```
|
||
|
||
#### 3. Получить документ по ID
|
||
```http
|
||
GET /api/v1/doc/{id}
|
||
```
|
||
**Описание**: Получить детальную информацию о документе по его идентификатору.
|
||
|
||
**Ответ**:
|
||
```json
|
||
{
|
||
"version": "v1",
|
||
"doc": {
|
||
"id": "document_id",
|
||
"content": "Полное содержимое документа",
|
||
"filename": "document.txt",
|
||
"summary": "Краткое описание",
|
||
"metadata": {
|
||
"category": "Категория",
|
||
"author": "Автор"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4. Задать вопрос
|
||
```http
|
||
POST /api/v1/ask
|
||
```
|
||
**Описание**: Задать вопрос на основе проиндексированных документов.
|
||
|
||
**Тело запроса**:
|
||
```json
|
||
{
|
||
"question": "Что такое ISO 27001?"
|
||
}
|
||
```
|
||
|
||
**Ответ**:
|
||
```json
|
||
{
|
||
"version": "v1",
|
||
"docs": ["document_id_1", "document_id_2"],
|
||
"answer": "ISO 27001 - это международный стандарт информационной безопасности..."
|
||
}
|
||
```
|
||
|
||
#### 5. Удалить документ
|
||
```http
|
||
DELETE /api/v1/doc/{id}
|
||
```
|
||
**Описание**: Удалить документ по его идентификатору.
|
||
|
||
**Ответ**:
|
||
```json
|
||
{
|
||
"version": "v1",
|
||
"docs": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Структуры данных
|
||
|
||
### Document (Документ)
|
||
```go
|
||
type Document struct {
|
||
ID string `json:"id"` // Уникальный идентификатор
|
||
Content string `json:"content"` // Содержимое документа
|
||
Link string `json:"link"` // Ссылка на источник
|
||
Filename string `json:"filename"` // Имя файла
|
||
Category string `json:"category"` // Категория
|
||
EmbeddingModel string `json:"embedding_model"` // Модель эмбеддингов
|
||
Summary string `json:"summary"` // Краткое описание
|
||
Metadata map[string]string `json:"metadata"` // Метаданные
|
||
Vector []float32 `json:"vector"` // Векторное представление
|
||
}
|
||
```
|
||
|
||
### Embedding (Эмбеддинг)
|
||
```go
|
||
type Embedding struct {
|
||
ID string `json:"id"` // Уникальный идентификатор
|
||
DocumentID string `json:"document_id"` // ID связанного документа
|
||
Vector []float32 `json:"vector"` // Векторное представление
|
||
TextChunk string `json:"text_chunk"` // Фрагмент текста
|
||
Dimension int64 `json:"dimension"` // Размерность вектора
|
||
Order int64 `json:"order"` // Порядок фрагмента
|
||
Score float32 `json:"score"` // Оценка релевантности
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Установка и настройка
|
||
|
||
### Требования
|
||
- Go 1.24.3+
|
||
- Milvus векторная база данных
|
||
- Ollama (для локальных моделей) или API ключи для OpenAI/OpenRoute
|
||
|
||
### 1. Клонирование репозитория
|
||
```bash
|
||
git clone https://github.com/elchemista/easy_rag.git
|
||
cd easy_rag
|
||
```
|
||
|
||
### 2. Установка зависимостей
|
||
```bash
|
||
go mod tidy
|
||
```
|
||
|
||
### 3. Настройка окружения
|
||
Создайте файл `.env` или установите переменные окружения:
|
||
|
||
```env
|
||
# LLM настройки
|
||
OPENAI_API_KEY=your_openai_api_key
|
||
OPENAI_ENDPOINT=https://api.openai.com/v1
|
||
OPENAI_MODEL=gpt-3.5-turbo
|
||
|
||
OPENROUTE_API_KEY=your_openroute_api_key
|
||
OPENROUTE_ENDPOINT=https://openrouter.ai/api/v1
|
||
OPENROUTE_MODEL=anthropic/claude-3-haiku
|
||
|
||
OLLAMA_ENDPOINT=http://localhost:11434/api/chat
|
||
OLLAMA_MODEL=qwen3:latest
|
||
|
||
# Эмбеддинги
|
||
OPENAI_EMBEDDING_API_KEY=your_openai_api_key
|
||
OPENAI_EMBEDDING_ENDPOINT=https://api.openai.com/v1
|
||
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002
|
||
|
||
OLLAMA_EMBEDDING_ENDPOINT=http://localhost:11434
|
||
OLLAMA_EMBEDDING_MODEL=bge-m3
|
||
|
||
# База данных
|
||
MILVUS_HOST=localhost:19530
|
||
```
|
||
|
||
### 4. Запуск Milvus
|
||
```bash
|
||
# Используя Docker
|
||
docker run -d --name milvus-standalone \
|
||
-p 19530:19530 -p 9091:9091 \
|
||
milvusdb/milvus:latest
|
||
```
|
||
|
||
### 5. Запуск приложения
|
||
```bash
|
||
go run cmd/rag/main.go
|
||
```
|
||
|
||
API будет доступно по адресу `http://localhost:4002`
|
||
|
||
---
|
||
|
||
## Запуск с Docker
|
||
|
||
### Сборка образа
|
||
```bash
|
||
docker build -f deploy/Dockerfile -t easy-rag .
|
||
```
|
||
|
||
### Запуск контейнера
|
||
```bash
|
||
docker run -d -p 4002:4002 \
|
||
-e MILVUS_HOST=your_milvus_host:19530 \
|
||
-e OLLAMA_ENDPOINT=http://your_ollama_host:11434/api/chat \
|
||
-e OLLAMA_MODEL=qwen3:latest \
|
||
easy-rag
|
||
```
|
||
|
||
---
|
||
|
||
## Примеры использования
|
||
|
||
### 1. Загрузка документа
|
||
```bash
|
||
curl -X POST http://localhost:4002/api/v1/upload \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"docs": [{
|
||
"content": "Это тестовый документ для демонстрации RAG системы.",
|
||
"filename": "test.txt",
|
||
"category": "Тест",
|
||
"metadata": {
|
||
"author": "Пользователь",
|
||
"type": "demo"
|
||
}
|
||
}]
|
||
}'
|
||
```
|
||
|
||
### 2. Поиск ответа
|
||
```bash
|
||
curl -X POST http://localhost:4002/api/v1/ask \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"question": "О чем этот документ?"
|
||
}'
|
||
```
|
||
|
||
### 3. Получение всех документов
|
||
```bash
|
||
curl http://localhost:4002/api/v1/docs
|
||
```
|
||
|
||
---
|
||
|
||
## Архитектурные особенности
|
||
|
||
### Модульность
|
||
Система спроектирована с использованием интерфейсов, что позволяет легко:
|
||
- Переключаться между различными LLM провайдерами
|
||
- Использовать разные модели эмбеддингов
|
||
- Менять векторную базу данных
|
||
- Добавлять новые методы обработки текста
|
||
|
||
### Обработка текста
|
||
- Автоматическое разбиение документов на чанки
|
||
- Генерация эмбеддингов для каждого фрагмента
|
||
- Сохранение порядка фрагментов для корректной реконструкции
|
||
|
||
### Поиск и ранжирование
|
||
- Семантический поиск по векторным представлениям
|
||
- Ранжирование результатов по релевантности
|
||
- Контекстная генерация ответов на основе найденных документов
|
||
|
||
---
|
||
|
||
## Разработка и тестирование
|
||
|
||
### Структура проекта
|
||
```
|
||
easy_rag/
|
||
├── api/ # HTTP API обработчики
|
||
├── cmd/rag/ # Точка входа приложения
|
||
├── config/ # Конфигурация
|
||
├── deploy/ # Docker файлы
|
||
├── internal/ # Внутренняя логика
|
||
│ ├── database/ # Интерфейсы БД
|
||
│ ├── embeddings/ # Провайдеры эмбеддингов
|
||
│ ├── llm/ # Провайдеры LLM
|
||
│ ├── models/ # Модели данных
|
||
│ └── pkg/ # Пакеты общего назначения
|
||
├── scripts/ # Вспомогательные скрипты
|
||
└── tests/ # Тесты и коллекции Postman
|
||
```
|
||
|
||
### Запуск тестов
|
||
```bash
|
||
go test ./...
|
||
```
|
||
|
||
### Использование Postman
|
||
В папке `tests/` находится коллекция Postman для тестирования API:
|
||
```
|
||
tests/RAG.postman_collection.json
|
||
```
|
||
|
||
---
|
||
|
||
## Производительность и масштабирование
|
||
|
||
### Рекомендации по производительности
|
||
- Используйте SSD для хранения векторной базы данных
|
||
- Настройте индексы Milvus для оптимальной производительности
|
||
- Рассмотрите использование GPU для генерации эмбеддингов
|
||
- Кэшируйте часто запрашиваемые результаты
|
||
|
||
### Масштабирование
|
||
- Горизонтальное масштабирование Milvus кластера
|
||
- Балансировка нагрузки между несколькими экземплярами API
|
||
- Асинхронная обработка загрузки документов
|
||
- Использование очередей для обработки больших объемов данных
|
||
|
||
---
|
||
|
||
## Устранение неполадок
|
||
|
||
### Частые проблемы
|
||
|
||
1. **Не удается подключиться к Milvus**
|
||
- Проверьте, что Milvus запущен и доступен
|
||
- Убедитесь в правильности MILVUS_HOST
|
||
|
||
2. **Ошибки LLM провайдера**
|
||
- Проверьте API ключи
|
||
- Убедитесь в доступности эндпоинтов
|
||
- Проверьте правильность названий моделей
|
||
|
||
3. **Медленная обработка документов**
|
||
- Уменьшите размер чанков
|
||
- Используйте более быстрые модели эмбеддингов
|
||
- Оптимизируйте настройки Milvus
|
||
|
||
---
|
||
|
||
## Вклад в проект
|
||
|
||
Мы приветствуем вклад в развитие проекта! Пожалуйста:
|
||
|
||
1. Форкните репозиторий
|
||
2. Создайте ветку для новой функции
|
||
3. Внесите изменения
|
||
4. Добавьте тесты
|
||
5. Отправьте Pull Request
|
||
|
||
---
|
||
|
||
## Лицензия
|
||
|
||
Проект распространяется под лицензией MIT. См. файл `LICENSE` для подробностей.
|
||
|
||
---
|
||
|
||
## Поддержка
|
||
|
||
Если у вас есть вопросы или проблемы:
|
||
- Создайте Issue в GitHub репозитории
|
||
- Обратитесь к документации API
|
||
- Проверьте примеры в папке `tests/`
|
||
|
||
---
|
||
|
||
## Roadmap
|
||
|
||
### Ближайшие планы
|
||
- [ ] Поддержка дополнительных форматов документов (PDF, DOCX)
|
||
- [ ] Веб-интерфейс для управления документами
|
||
- [ ] Улучшенная система метаданных
|
||
- [ ] Поддержка multimodal моделей
|
||
- [ ] Кэширование результатов
|
||
- [ ] Мониторинг и метрики
|
||
|
||
### Долгосрочные цели
|
||
- [ ] Поддержка множественных языков
|
||
- [ ] Федеративный поиск по нескольким источникам
|
||
- [ ] Интеграция с внешними системами (SharePoint, Confluence)
|
||
- [ ] Продвинутая аналитика использования
|
||
- [ ] Система разрешений и ролей
|