Гибридный RAG-проект

Обобщённая система генерации с дополнением извлечения (RAG) с возможностями гибридного поиска, которая работает с любыми предоставленными вами документами. Сочетает семантический (плотные векторные) поиск и поиск по ключевым словам (разреженный BM25) для оптимального извлечения документов, а также предоставляет API-сервер MCP для лёгкой интеграции.

🎯 Ключевые возможности: поддержка множества форматов • локальная LLM • интеграция с Claude Desktop • запросы к структурированным данным • извлечение с учётом типа документа

🚀 Быстрый старт (без MCP!)

Вам не нужен Claude Desktop или MCP для использования этого проекта! Просто запустите:

# 1. Make sure Ollama is running
ollama serve

# 2. Activate virtual environment
source .venv/bin/activate

# 3. Start conversational demo (recommended)
python scripts/demos/conversational.py

# Or use the shortcut
./scripts/bin/ask.sh

Всё! Задавайте вопросы о 43 835 фрагментах документов в демонстрационном наборе данных.

📖 См. Руководство по быстрому старту для полных инструкций по использованию. 📚 Просмотрите всю документацию в папке docs/ или начните с docs/README.md.

Related MCP server: Hybrid RAG Project MCP Server

Обзор

Этот проект реализует гибридную RAG-систему, которая объединяет:

• Семантический поиск: плотные векторные эмбеддинги для понимания смысла и контекста

• Поиск по ключевым словам: разреженное извлечение BM25 для точного совпадения ключевых слов

• Гибридное слияние: Reciprocal Rank Fusion (RRF) для объединения результатов обоих методов

• MCP-сервер: и REST API, и сервер Model Context Protocol для интеграции с Claude

• Поддержка множества форматов: автоматическая загрузка документов из различных файловых форматов

Гибридный подход обеспечивает более высокую точность извлечения, используя сильные стороны обоих методов поиска.

Возможности

• Векторный семантический поиск с использованием эмбеддингов Chroma и Ollama

• Поиск по ключевым словам BM25 для точного совпадения терминов

• Ансамблевый ретривер с Reciprocal Rank Fusion (RRF)

• Интеграция с локальной LLM Ollama для генерации ответов

• Поддержка нескольких форматов документов (TXT, PDF, MD, DOCX, CSV)

• Автоматическая загрузка документов из каталога данных

• RESTful API-сервер с конечными точками /ingest и /query

• Сервер Model Context Protocol (MCP) для интеграции с Claude Desktop/API

• Архитектура, управляемая конфигурацией (без жёстко заданных значений)

• Постоянное векторное хранилище для ускорения последующих запросов

Архитектура

User Documents → data/ directory
                      ↓
            Document Loader
                      ↓
Query → Hybrid Retriever → [Vector Retriever + BM25 Retriever]
                         → RRF Fusion
                         → Retrieved Context
                         → LLM (Ollama)
                         → Final Answer

Предварительные требования

1. Python 3.9+

2. Ollama установлен и запущен локально

3. Требуемые модели Ollama:

   • llama3.1:latest (или другая LLM-модель)

   • nomic-embed-text (или другая модель эмбеддингов)

Установка Ollama

Посетите ollama.ai, чтобы загрузить и установить Ollama для вашей платформы.

После установки загрузите требуемые модели:

ollama pull llama3.1:latest
ollama pull nomic-embed-text

Проверьте, что Ollama запущен:

curl http://localhost:11434/api/tags

Установка

1. Клонируйте репозиторий:

git clone <your-repo-url>
cd hybrid-rag-project

2. Создайте виртуальное окружение:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Установите зависимости:

pip install -r requirements.txt

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

hybrid-rag-project/
├── src/
│   └── hybrid_rag/            # Core application package
│       ├── __init__.py        # Package initialization
│       ├── document_loader.py # Document loading utility
│       ├── structured_query.py# CSV query engine
│       └── utils.py           # Logging and utility functions
├── scripts/
│   ├── run_demo.py            # Main demonstration script
│   ├── mcp_server.py          # REST API server
│   └── mcp_server_claude.py   # MCP server for Claude integration
├── config/
│   ├── config.yaml            # Configuration file
│   └── claude_desktop_config.json # Sample Claude Desktop MCP config
├── docs/
│   ├── INSTALLATION.md        # Detailed installation guide
│   ├── STRUCTURED_QUERIES.md  # CSV query documentation
│   ├── ASYNC_INGESTION.md     # Async ingestion guide
│   └── SHUTDOWN.md            # Shutdown handling guide
├── data/                      # Sample data files (13 files included)
│   ├── *.csv                  # 7 CSV files (structured data)
│   ├── *.md                   # 5 Markdown files (unstructured)
│   └── *.txt                  # 1 Text file (technical specs)
├── chroma_db/                 # Vector store (auto-created)
├── tests/                     # Unit tests
│   └── extract_fields_tests.py
├── setup.py                   # Package setup file
├── requirements.txt           # Python dependencies
├── TESTING_RESULTS.md         # Comprehensive test results
├── CONTRIBUTING.md            # Contribution guidelines
├── CHANGELOG.md               # Version history
├── LICENSE                    # MIT License
└── README.md                  # This file

Пример данных (проект UCSC Extension)

Этот репозиторий включает 13 примеров файлов данных для демонстрации и тестирования. Эти файлы представляют реалистичный бизнес-сценарий для TechVision Electronics и предназначены для демонстрации возможностей системы на различных типах документов.

📊 Включённые примеры файлов

Структурированные данные (CSV) — 7 файлов:

• product_catalog.csv — каталог продуктов с характеристиками (5 000 строк)

• inventory_levels.csv — уровни запасов и данные складов (10 000 строк)

• sales_orders_november.csv — ежемесячные продажи (8 000 строк)

• warranty_claims_q4.csv — гарантийные претензии клиентов (3 000 строк)

• production_schedule_dec2024.csv — производственный график (4 000 строк)

• supplier_pricing.csv — информация о ценах поставщиков (6 000 строк)

• shipping_manifests.csv — данные о доставке и логистике (5 000 строк)

Неструктурированные данные (Markdown) — 5 файлов:

• customer_feedback_q4_2024.md — отзывы и обратная связь клиентов (600 фрагментов)

• market_analysis_2024.md — маркетинговые исследования и тенденции (400 фрагментов)

• quality_control_report_nov2024.md — результаты контроля качества и проблемы (501 фрагмент)

• return_policy_procedures.md — документация по политике возврата (300 фрагментов)

• support_tickets_summary.md — сводка обращений в техподдержку (700 фрагментов)

Текстовые данные — 1 файл:

• product_specifications.txt — технические характеристики (334 фрагмента)

Общий набор данных:

• 41 000 строк CSV (разбиты на 41 000 документов по 10 строк на фрагмент)

• 2 835 текстовых/Markdown-фрагментов (разбиты по 1000 символов с перекрытием 200 символов)

• 43 835 всего доступных для поиска фрагментов документов

🎯 Назначение

Эти примеры файлов включены для того, чтобы:

1. Продемонстрировать возможности гибридного поиска системы

2. Протестировать как семантическое (векторное), так и лексическое (ключевое) извлечение

3. Проверить архитектуру извлечения с учётом типа документа

4. Предоставить готовые рабочие примеры без дополнительной настройки

5. Показать синтез запросов по нескольким документам

📖 Результаты тестирования

Полные результаты тестирования задокументированы в TESTING_RESULTS.md, показывающие:

• ✅ 100% успешность извлечения для всех типов документов

• ✅ 17 тестовых запросов с подробными результатами

• ✅ Показатели производительности и сравнительный анализ

• ✅ Сравнение семантического, лексического и гибридного поиска

💡 Использование примеров данных

Быстрый старт:

# 1. Run setup
./setup.sh

# 2. The sample data is already in data/ - ready to use!

# 3. Run the demo
python scripts/run_demo.py

# 4. Or use Claude Desktop
# Configure MCP server and query: "What are the prices in the product catalog?"

Для производственного использования: Чтобы использовать собственные данные:

1. Удалите или сделайте резервную копию примеров файлов из data/

2. Добавьте свои документы (TXT, PDF, MD, DOCX, CSV)

3. Повторно запустите индексацию

4. При необходимости раскомментируйте исключения данных в .gitignore

## Configuration

All settings are managed in `config/config.yaml`:

```yaml
# Ollama Configuration
ollama:
  base_url: "http://localhost:11434"
  embedding_model: "nomic-embed-text"
  llm_model: "llama3.1:latest"

# Data Configuration
data:
  directory: "./data"
  supported_formats:
    - "txt"
    - "pdf"
    - "md"
    - "docx"
    - "csv"

# Retrieval Configuration
retrieval:
  vector_search_k: 2
  keyword_search_k: 2

# MCP Server Configuration
mcp_server:
  host: "0.0.0.0"
  port: 8000

# Vector Store Configuration
vector_store:
  persist_directory: "./chroma_db"

Измените этот файл, чтобы:

• Использовать другие модели Ollama

• Изменить расположение каталога данных

• Настроить параметры извлечения (значения k)

• Настроить хост/порт сервера

• Изменить расположение постоянного векторного хранилища

Использование

Вариант 1: Скрипт командной строки

1. Добавьте свои документы в каталог data/:

cp /path/to/your/documents/*.pdf data/
cp /path/to/your/documents/*.txt data/

2. Запустите скрипт:

python scripts/run_demo.py

Скрипт будет:

• Загружать все поддерживаемые документы из каталога data/

• Инициализировать эмбеддинги и LLM Ollama

• Создавать векторный и BM25 ретриверы

• Строить гибридную RAG-цепочку

• Выполнять примеры запросов и отображать результаты

Вариант 2: REST API-сервер

1. Запустите REST API-сервер:

python scripts/mcp_server.py

Сервер запустится на http://localhost:8000

Чтобы остановить сервер: нажмите Ctrl+C для корректного завершения

2. Загрузите документы (сделайте это первым):

curl -X POST http://localhost:8000/ingest

Ответ:

{
  "status": "success",
  "message": "Documents ingested successfully",
  "documents_loaded": 15
}

3. Запросите документы:

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the main topic of these documents?"}'

Ответ:

{
  "answer": "Based on the documents...",
  "context": [
    {
      "content": "Document text...",
      "source": "example.pdf",
      "type": ".pdf"
    }
  ]
}

4. Проверьте статус сервера:

curl http://localhost:8000/status

Конечные точки API

Вариант 3: Claude Desktop/API через MCP

Сервер MCP (Model Context Protocol) позволяет Claude напрямую запрашивать вашу локальную RAG-систему.

Настройка для Claude Desktop

1. Сначала добавьте документы в каталог данных:

cp /path/to/your/documents/*.pdf data/

2. Отредактируйте файл config/claude_desktop_config.json, чтобы использовать правильный абсолютный путь:

{
  "mcpServers": {
    "hybrid-rag": {
      "command": "python",
      "args": [
        "/absolute/path/to/hybrid-rag-project/scripts/mcp_server_claude.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/hybrid-rag-project"
      }
    }
  }
}

3. Добавьте эту конфигурацию в Claude Desktop:

   На macOS:

   # Copy the configuration
   mkdir -p ~/Library/Application\ Support/Claude
   # Edit the file and add your MCP server configuration
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

   На Windows:

   %APPDATA%\Claude\claude_desktop_config.json

   На Linux:

   ~/.config/Claude/claude_desktop_config.json

4. Перезапустите Claude Desktop

5. В Claude Desktop теперь будут доступны инструменты MCP. Вы можете попросить Claude:

   • "Используй инструмент ingest_documents для загрузки моих документов"

   • "Запроси мои документы о [ваш вопрос]"

   • "Проверь статус RAG-системы"

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

Claude будет иметь доступ к этим инструментам:

Загрузка документов и поиск:

• ingest_documents: начать асинхронную загрузку и индексацию документов из каталога data/

• get_ingestion_status: отслеживать прогресс загрузки документов (процент, текущий файл, этап)

• query_documents: запрашивать документы с помощью гибридного поиска (семантический + ключевой)

• get_status: проверять статус RAG-системы

Запросы к структурированным данным (для CSV-файлов):

• list_datasets: список всех доступных CSV-наборов данных с колонками и количеством строк

• count_by_field: подсчёт строк, где поле соответствует значению (например, "подсчитай людей по имени Michael")

• filter_dataset: получение всех строк, соответствующих критериям поля (например, "все люди из компании X")

• get_dataset_stats: получение статистики о наборе данных (строки, колонки, использование памяти)

Асинхронная загрузка с отслеживанием прогресса

Процесс загрузки теперь выполняется асинхронно с обновлениями прогресса в реальном времени:

• Неблокирующий: загрузка выполняется в фоновом режиме

• Отслеживание прогресса: виден процент завершения (0–100%)

• Обновления на уровне файлов: известно, какой файл обрабатывается в данный момент

• Информация об этапах: загрузка файлов (0–80%) → построение индекса (80–100%) → завершено

• Мониторинг статуса: проверка прогресса в любое время с помощью get_ingestion_status

Пример использования с Claude

You: "Please start ingesting my documents"
Claude: [Uses ingest_documents tool]
        "Ingestion started. Use get_ingestion_status to monitor progress."

You: "Check the ingestion status"
Claude: [Uses get_ingestion_status tool]
        "Ingestion Status: In Progress
         Progress: 45%
         Stage: loading_files
         Files Processed: 9/20
         Current File: document.pdf
         Documents Loaded: 15"

You: "Check status again"
Claude: [Uses get_ingestion_status tool]
        "Ingestion Status: Completed ✅
         Progress: 100%
         Total Files Processed: 20
         Total Documents Loaded: 35

         You can now use query_documents to search the documents."

You: "What are the main topics in my documents?"
Claude: [Uses query_documents tool with your question]
        "Based on the documents, the main topics are..."

Запросы к структурированным данным

Для CSV-файлов используйте инструменты структурированных запросов для точных подсчётов и фильтрации:

You: "List available datasets"
Claude: [Uses list_datasets tool]
        "Available Datasets:
         📊 contacts
            Rows: 24,697
            Columns (7): First Name, Last Name, URL, Email Address, Company, Position, Connected On"

You: "Count how many people are named Michael in the contacts dataset"
Claude: [Uses count_by_field tool with dataset="contacts", field="First Name", value="Michael"]
        "Count Result:
         Dataset: contacts
         Field: First Name
         Value: Michael
         Count: 226 out of 24,697 total rows (0.92%)"

You: "Show me all the Michaels"
Claude: [Uses filter_dataset tool]
        "Filter Results:
         Found: 226 rows
         Showing: 100 rows (truncated to 100)

         [1] First Name: Michael | Last Name: Randel | Company: Randel Consulting Associates ..."

Когда использовать каждый подход:

• Структурированные запросы (count_by_field, filter_dataset): для точных подсчётов, фильтрации и структурированных данных

• Семантический поиск (query_documents): для концептуальных вопросов, понимания содержания, обобщения

Поддерживаемые форматы файлов

Система автоматически загружает и обрабатывает следующие форматы:

• .txt — обычные текстовые файлы

• .pdf — PDF-документы

• .md — файлы Markdown

• .docx — документы Microsoft Word

• .csv — CSV-файлы

Просто поместите любые поддерживаемые файлы в каталог data/!

Как это работает

Загрузка документов

Класс DocumentLoaderUtility:

1. Рекурсивно сканирует каталог data/

2. Определяет поддерживаемые форматы файлов

3. Использует соответствующие загрузчики для каждого формата

4. Добавляет метаданные (исходный файл, тип файла) к каждому документу

5. Возвращает список объектов Document, готовых к индексации

Гибридное извлечение

EnsembleRetriever использует Reciprocal Rank Fusion (RRF) для:

1. Извлечения top-k результатов из векторного поиска (семантического)

2. Извлечения top-k результатов из поиска BM25 (ключевого)

3. Присвоения оценок обратного ранга каждому результату

4. Объединения оценок для получения единого ранжирования

5. Возврата наиболее релевантных документов в целом

Этот подход обрабатывает:

• Семантические запросы ("Как мне запросить отгул?")

• Ключевые запросы ("Форма PTO HR-42")

• Сложные запросы, выигрывающие от обоих методов

Настройка

Использование других моделей

Отредактируйте config/config.yaml, чтобы изменить модели:

ollama:
  embedding_model: "your-embedding-model"
  llm_model: "your-llm-model"

Настройка параметров извлечения

Измените значения k в config/config.yaml:

retrieval:
  vector_search_k: 5   # Return top 5 from semantic search
  keyword_search_k: 5  # Return top 5 from keyword search

Добавление поддержки дополнительных форматов файлов

Отредактируйте src/hybrid_rag/document_loader.py, чтобы добавить больше загрузчиков:

self.supported_loaders = {
    '.txt': TextLoader,
    '.pdf': PyPDFLoader,
    '.json': JSONLoader,  # Add this
    # ... more formats
}

Настройка промпта

Отредактируйте шаблон промпта в scripts/run_demo.py или scripts/mcp_server.py:

prompt = ChatPromptTemplate.from_template("""
Your custom prompt here...

<context>
{context}
</context>

Question: {input}
""")

Рабочий процесс разработки

1. Добавьте документы в каталог data/

2. Измените конфигурацию в config/config.yaml по мере необходимости

3. Протестируйте с помощью командной строки: python scripts/run_demo.py

4. Разверните MCP-сервер: python scripts/mcp_server.py

5. Интегрируйте через API в свои приложения

Устранение неполадок

"Ошибка подключения к Ollama"

• Убедитесь, что Ollama установлен и запущен

• Проверьте, что служба Ollama доступна по настроенному URL

• Проверьте, что модели загружены: ollama list

"В каталоге данных не найдено документов"

• Добавьте файлы в каталог data/

• Убедитесь, что файлы имеют поддерживаемые расширения (.txt, .pdf, .md, .docx, .csv)

• Проверьте, что путь к каталогу данных в config/config.yaml указан правильно

"ModuleNotFoundError"

• Убедитесь, что виртуальное окружение активировано: source .venv/bin/activate

• Переустановите зависимости: pip install -r requirements.txt

Плохие результаты извлечения

• Добавьте больше релевантных документов в каталог data/

• Настройте значения k в config/config.yaml

• Попробуйте другие модели эмбеддингов

• Убедитесь, что терминология запроса соответствует содержанию документов

Ошибки API

Пример: полный рабочий процесс

# 1. Activate environment
source .venv/bin/activate

# 2. Add your documents
cp ~/my-docs/*.pdf data/

# 3. Start MCP server
python scripts/mcp_server.py &

# 4. Ingest documents
curl -X POST http://localhost:8000/ingest

# 5. Query your documents
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Summarize the key points"}'

# 6. Check status
curl http://localhost:8000/status

Зависимости

Основные библиотеки:

• langchain: Фреймворк для LLM-приложений

• langchain-community: Сообщественные интеграции

• langchain-ollama: Интеграция с Ollama

• chromadb: Векторная база данных для эмбеддингов

• rank-bm25: Реализация BM25 для поиска по ключевым словам

• fastapi: Веб-фреймворк для API

• uvicorn: ASGI-сервер

• pyyaml: Разбор YAML-конфигурации

Загрузчики документов:

• pypdf: Обработка PDF

• python-docx: Обработка Word-документов

• unstructured: Markdown и другие форматы

Советы по производительности

1. Постоянное хранилище векторов: векторное хранилище сохраняется на диск (chroma_db/) после загрузки, что ускоряет последующие запросы.

2. Пакетная обработка: при добавлении множества документов используйте конечную точку /ingest один раз, а не несколько.

3. Параметры поиска: меньшие значения k (например, 2–3) работают быстрее и часто достаточны для небольших наборов документов.

4. Выбор модели: меньшие модели эмбеддингов работают быстрее, но могут немного терять в точности.

Лицензия

Этот проект предоставляется как есть, в образовательных и демонстрационных целях.

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

Не стесняйтесь отправлять вопросы (issues), форкать репозиторий и создавать pull request'ы для любых улучшений.

Ресурсы

• Документация LangChain

• Документация Ollama

• Документация ChromaDB

• Документация FastAPI

• Алгоритм BM25

• Reciprocal Rank Fusion

Журнал изменений

Версия 2.0.0

• Обобщена система для работы с любыми документами

• Добавлена директория data/ для загрузки документов

• Создан DocumentLoaderUtility для поддержки множества форматов

• Переструктурирован проект в соответствии с лучшими практиками Python (структура src)

• Вся конфигурация перемещена в директорию config/

• Вся документация перемещена в директорию docs/

• Создана правильная структура Python-пакета с setup.py

• Скрипты организованы в директории scripts/

• Обновлены все пути импорта и документация

Версия 1.0.0

• Первоначальная реализация с примером HR-документов

• Базовый гибридный поиск с векторными и BM25-рет-риверами