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