📄 Universal Document Vector Search Service

Микросервис для семантического поиска по документам с поддержкой категорий, версионирования и MCP-интеграцией

✨ Ключевые возможности

• 🔍 Семантический поиск — поиск по смыслу текста, а не по ключевым словам

• 📊 Гибридный поиск — RRF (Reciprocal Rank Fusion) для лучшего качества

• 📁 Много форматов — PDF, DOCX, TXT, HTML, Markdown, XLSX

• 🗂️ Категоризация — автоматическая иерархическая система категорий

• 🔄 Версионирование — отслеживание изменений документов

• 🤖 MCP Integration — готовая интеграция с AI-ассистентами

• 🐳 Docker Ready — быстрое развёртывание за 2 минуты

• 🎨 GPU Acceleration — ускорение через NVIDIA CUDA

📝 О проекте

Этот сервис позволяет загружать документы различных форматов, автоматически извлекать из них текст, разбивать на чанки, создавать векторные представления и выполнять семантический поиск. Результаты можно группировать по категориям и фильтраровать по метаданным.

Проект идеален для:

• B2B интеграций — поиск по технической документации, инструкциям, базам знаний

• AI-ассистентов — MCP-протокол для подключения к LLM-ботам

• Аналитики — категоризация и поиск по большим массивам документов

📸 Скриншоты

Swagger UI документация (добавьте скриншот после запуска: http://localhost:8000/docs)

Related MCP server: context-repo-mcp

📋 Содержание

• Возможности

• Архитектура

• Требования

• Быстрый старт

• Установка и настройка

• REST API

• MCP Интеграция

• Конфигурация

• Развёртывание

• Структура проекта

• Разработка

• Тестирование

• FAQ

✨ Возможности

• Семантический поиск по документам с использованием векторных эмбеддингов

• Гибридный поиск сweighted RRF (Reciprocal Rank Fusion)

• Группировка результатов по категориям и коллекциям

• Поддержка множества форматов: PDF, DOCX, DOC, TXT, HTML, Markdown, XLSX

• OCR для сканированных документов (Tesseract)

• Конвертация документов в Markdown через Docling

• Иерархическая система категорий с несколькими уровнями вложенности

• Версионирование документов с возможностью доступа к старым версиям

• MCP (Model Context Protocol) интеграция для AI-ассистентов

• Docker-развёртывание с поддержкой GPU

• Аутентификация для API и MCP endpoints

🏗️ Архитектура

┌─────────────────┐      ┌──────────────────┐      ┌──────────────┐
│   AI Client     │◄────►│  RAG Service     │◄────►│   Qdrant     │
│  (MCP/API)      │      │  (FastAPI)       │      │ (Vector DB)  │
└─────────────────┘      └──────────────────┘      └──────────────┘
                                  │
                                  ▼
                          ┌──────────────────┐
                          │  Document Store  │
                          │   (uploads/)     │
                          └──────────────────┘

Основные компоненты:

• FastAPI — веб-фреймворк для REST API и MCP прокси

• Qdrant — векторная база данных для хранения и поиска эмбеддингов

• Sentence Transformers — генерация векторных представлений текста

• Docling — конвертация документов в структурированный Markdown

• Tesseract OCR — распознавание текста на изображениях

📦 Требования

Для локальной разработки:

• Python 3.11+

• Qdrant (локально или Docker)

• ~2GB свободного места для моделей эмбеддингов

Для production (Docker):

• Docker Engine 20.10+

• Docker Compose v2

• GPU (опционально, для ускорения работы с эмбеддингами)

⚡ Быстрый старт (2 минуты)

Запуск одним командой

# 1. Клонируйте репозиторий
git clone https://github.com/PlVld/rag-service.git
cd rag-service

# 2. Настройте переменные окружения
cp .env.example .env
# Отредактируйте .env: укажите свой RAG_SERVICE_API_KEY

# 3. Запустите
docker-compose up -d

# 4. Готово! Откройте:
curl http://localhost:8000/health
# http://localhost:8000/docs (Swagger UI)

Подробная инструкция →

🚀 Быстрый старт

1. Клонирование репозитория

git clone <repository-url>
cd rag

2. Настройка переменных окружения

cp .env.example .env

Отредактируйте .env файл, указав необходимые значения:

RAG_SERVICE_API_KEY=your-secret-api-key-here
QDRANT_URL=http://localhost:6333
EMBEDDING_MODEL=BAAI/bge-m3
USE_GPU=false

3. Запуск с Docker Compose

docker-compose up -d

Это запустит:

• Qdrant на порту 6333

• RAG Service на порту 8000

4. Проверка работоспособности

# Проверка health check
curl http://localhost:8000/health

# Открытие Swagger UI
# http://localhost:8000/docs

📖 Установка и настройка

Локальная установка (без Docker)

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

# Создание виртуального окружения
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Установка зависимостей
pip install -r requirements.txt

2. Запуск Qdrant

docker run -d --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v ./qdrant_data:/qdrant/storage \
  qdrant/qdrant:latest

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

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Использование CPU-only образа

docker-compose -f docker-compose.yml -f Dockerfile.cpu up -d

🌐 REST API

Основные эндпоинты

Документы

Категории

Файлы

Администрирование

Интерактивная документация

После запуска откройте:

• Swagger UI: http://localhost:8000/docs

• ReDoc: http://localhost:8000/redoc

🔌 MCP Интеграция

Сервис поддерживает Model Context Protocol (MCP) для интеграции с AI-ассистентами.

Доступные инструменты

1. search_documents_tool — семантический поиск по документам

2. search_categories_tool — поиск категорий по запросу

3. get_category_hierarchy_tool — получение иерархии категорий

Подключение

URL: http://localhost:8000/mcp
Method: POST
Content-Type: application/json
Authorization: Bearer <RAG_SERVICE_API_KEY>

Пример вызова (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_documents_tool",
    "arguments": {
      "query_text": "настройка векторного поиска",
      "collection_name": "documents",
      "limit": 5
    }
  }
}

Подробная документация по MCP: docs/mcp_tools.md

⚙️ Конфигурация

Все настройки управляются через переменные окружения (файл .env).

Ключевые параметры

Полный список переменных: .env.example

🐳 Развёртывание

Production deployment

1. Настройте .env для production:

   USE_GPU=true
   LOG_LEVEL=WARNING
   MCP_AUTH_ENABLED=true

2. Соберите образ:

   docker build -t rag-service:latest -f Dockerfile .

3. Запустите:

   docker-compose up -d

Horizontal Scaling

Для масштабирования можно запустить несколько инстансов сервиса за load balancer'ом, так как состояние хранится в Qdrant.

Backup

Регулярно бэкапьте:

• Директорию qdrant_data/ — данные векторной БД

• Директорию uploads/ — исходные документы

📁 Структура проекта

rag/
├── app/                          # Основной код приложения
│   ├── api/                      # REST API endpoints
│   │   ├── documents.py          # Эндпоинты для документов
│   │   ├── categories.py         # Эндпоинты для категорий
│   │   ├── files.py              # Эндпоинты для файлов
│   │   ├── admin.py              # Админ-эндпоинты
│   │   ├── health.py             # Health check
│   │   └── ...
│   ├── core/                     # Ядро приложения
│   │   ├── config.py             # Конфигурация
│   │   └── embeddings.py         # Работа с эмбеддингами
│   ├── models/                   # Pydantic модели
│   ├── repository/               # Работа с Qdrant
│   ├── text_cleaning/            # Очистка и预处理 текста
│   │   ├── doc_cleaner.py        # Общий cleaner
│   │   ├── pdf_cleaner.py        # PDF специфичный
│   │   ├── markdown_cleaner.py   # Markdown специфичный
│   │   └── ...
│   ├── main.py                   # Точка входа (FastAPI app)
│   └── mcp_server.py             # MCP сервер
├── tests/                        # Тесты
├── docs/                         # Документация
│   ├── api/                      # Документация по API
│   ├── architecture.md           # Архитектура
│   ├── DEPLOYMENT.md             # Развёртывание
│   └── mcp_tools.md              # MCP инструменты
├── uploads/                      # Загруженные документы
├── qdrant_data/                  # Данные Qdrant
├── model_cache/                  # Кэш моделей
├── docker-compose.yml            # Docker Compose конфиг
├── Dockerfile                    # Docker образ (GPU)
├── Dockerfile.cpu                # Docker образ (CPU)
├── requirements.txt              # Зависимости Python
└── .env.example                  # Пример конфигурации

🧪 Тестирование

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

pytest

Запуск с покрытием

pytest --cov=app --cov-report=html

Запуск конкретных тестов

# Тесты API документов
pytest tests/test_rest_api_documents.py -v

# Тесты категорий
pytest tests/test_rest_api_categories.py -v

# Тесты MCP сервера
pytest tests/test_mcp_server.py -v

❓ FAQ

Как загрузить документы?

Используйте POST /api/documents/upload или через Swagger UI на http://localhost:8000/docs.

Как искать документы?

POST /api/documents/search с телом запроса:

{
  "query_text": "ваш запрос",
  "limit": 10
}

Как использовать GPU?

1. Установите NVIDIA Docker runtime

2. В docker-compose.yml раскомментируйте секцию deploy с GPU

3. Установите USE_GPU=true в .env

Как сменить модель эмбеддингов?

Укажите другую модель в .env:

EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

Как настроить авторизацию?

Установите RAG_SERVICE_API_KEY в .env и передавайте заголовок:

Authorization: Bearer <your-api-key>

🛠️ Tech Stack

🎬 Quick Demo

# Загрузить документ
curl -X POST http://localhost:8000/v1/documents/upload \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"documents": [{"text": "Текст для поиска", "category_path": "Документация"}]}'

# Искать
curl -X POST http://localhost:8000/v1/documents/search \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query_text": "как искать документы", "limit": 5}'

📁 Related Projects

• Qdrant — Vector Database

• Sentence Transformers

• Docling — Document Conversion

📄 Лицензия

MIT License

🤝 Вклад в проект

Мы приветствуем contributions! Пожалуйста:

1. Fork репозитория

2. Создайте ветку (git checkout -b feature/amazing-feature)

3. Commit изменения (git commit -m 'Add amazing feature')

4. Push в ветку (git push origin feature/amazing-feature)

5. Откройте Pull Request

Подробности в CONTRIBUTING.md

👥 Авторы

Разработано

• PlVld

📬 Контакты

• GitHub Issues: Открыть issue

• Discussions: GitHub Discussions