fofanov.dmitry/easy_rag
1
0
Fork 0
Code Activity

Реализована операции Milvus для управления документами и встраиванием, включая функции вставки, запроса и удаления. Внедрите архитектуру RAG с LLM и сервисами встраивания. Добавьте обработку текста для фрагментации и конкатенации. Создайте автономный скрипт для настройки и управления Milvus. Разработайте комплексные тесты API для обработки документов и взаимодействия с LLM, включая имитации для сервисов. Расширьте возможности конфигурации пользователя с помощью дополнительных настроек YAML.

Browse Source
This commit is contained in:
Dmitriy Fofanov
2025-09-19 11:38:31 +03:00
parent 8e7aab5181
commit 636096fd34
38 changed files with 3420 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

454
README.md
View File

@@ -1,2 +1,454 @@
# easy_rag
# 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)
- [ ] Продвинутая аналитика использования
- [ ] Система разрешений и ролей