fofanov.dmitry/easy_rag
1
0
Fork 0
Code Activity
Files
master
easy_rag/README.md

16 KiB
Raw Permalink Blame History

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. Получить все документы

GET /api/v1/docs

Описание: Получить список всех сохраненных документов.

Ответ:

{
    "version": "v1",
    "docs": [
        {
            "id": "document_id",
            "filename": "document.txt",
            "summary": "Краткое описание документа",
            "metadata": {
                "category": "Техническая документация",
                "author": "Автор"
            }
        }
    ]
}

2. Загрузить документы

POST /api/v1/upload

Описание: Загрузить один или несколько документов для обработки и индексации.

Тело запроса:

{
    "docs": [
        {
            "content": "Содержимое документа...",
            "link": "https://example.com/document",
            "filename": "document.txt",
            "category": "Категория",
            "metadata": {
                "author": "Автор",
                "date": "2024-01-01"
            }
        }
    ]
}

Ответ:

{
    "version": "v1",
    "task_id": "unique_task_id",
    "expected_time": "10m",
    "status": "Обработка начата"
}

3. Получить документ по ID

GET /api/v1/doc/{id}

Описание: Получить детальную информацию о документе по его идентификатору.

Ответ:

{
    "version": "v1",
    "doc": {
        "id": "document_id",
        "content": "Полное содержимое документа",
        "filename": "document.txt",
        "summary": "Краткое описание",
        "metadata": {
            "category": "Категория",
            "author": "Автор"
        }
    }
}

4. Задать вопрос

POST /api/v1/ask

Описание: Задать вопрос на основе проиндексированных документов.

Тело запроса:

{
    "question": "Что такое ISO 27001?"
}

Ответ:

{
    "version": "v1",
    "docs": ["document_id_1", "document_id_2"],
    "answer": "ISO 27001 - это международный стандарт информационной безопасности..."
}

5. Удалить документ

DELETE /api/v1/doc/{id}

Описание: Удалить документ по его идентификатору.

Ответ:

{
    "version": "v1",
    "docs": null
}

Структуры данных

Document (Документ)

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 (Эмбеддинг)

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. Клонирование репозитория

git clone https://github.com/elchemista/easy_rag.git
cd easy_rag

2. Установка зависимостей

go mod tidy

3. Настройка окружения

Создайте файл .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

# Используя Docker
docker run -d --name milvus-standalone \
    -p 19530:19530 -p 9091:9091 \
    milvusdb/milvus:latest

5. Запуск приложения

go run cmd/rag/main.go

API будет доступно по адресу http://localhost:4002

Запуск с Docker

Сборка образа

docker build -f deploy/Dockerfile -t easy-rag .

Запуск контейнера

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. Загрузка документа

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. Поиск ответа

curl -X POST http://localhost:4002/api/v1/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "О чем этот документ?"
  }'

3. Получение всех документов

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

Запуск тестов

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