Proyecto Hybrid RAG

Un sistema generalizado de Retrieval-Augmented Generation (RAG) con capacidades de búsqueda híbrida que funciona con cualquier documento que proporciones. Combina la búsqueda semántica (vectores densos) y la búsqueda por palabras clave (BM25 disperso) para una recuperación óptima de documentos, con una API de servidor MCP para una integración sencilla.

🎯 Características clave: Compatibilidad con múltiples formatos • LLM local • Integración con Claude Desktop • Consultas de datos estructurados • Recuperación según el tipo de documento

🚀 Inicio rápido (¡No se requiere MCP!)

¡No necesitas Claude Desktop ni MCP para usar este proyecto! Simplemente ejecuta:

# 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

¡Eso es todo! Haz preguntas sobre los 43,835 fragmentos de documentos del conjunto de datos de ejemplo.

📖 Consulta la Guía de inicio rápido para obtener instrucciones de uso completas. 📚 Explora toda la documentación en la carpeta docs/ o empieza con docs/README.md.

Related MCP server: Hybrid RAG Project MCP Server

Descripción general

Este proyecto implementa un sistema RAG híbrido que combina:

• Búsqueda semántica: Incrustaciones (embeddings) de vectores densos para comprender el significado y el contexto

• Búsqueda por palabras clave: Recuperación dispersa con BM25 para la coincidencia exacta de términos

• Fusión híbrida: Reciprocal Rank Fusion (RRF) para combinar los resultados de ambos métodos

• Servidor MCP: Tanto API REST como servidor Model Context Protocol para la integración con Claude

• Compatibilidad con múltiples formatos: Carga automática de documentos en varios formatos de archivo

El enfoque híbrido garantiza una mayor precisión en la recuperación al aprovechar los puntos fuertes de ambos métodos de búsqueda.

Características

• Búsqueda semántica basada en vectores mediante Chroma e incrustaciones de Ollama

• Búsqueda de palabras clave con BM25 para coincidencia exacta de términos

• Recuperador conjunto con fusión de rango recíproco (RRF)

• Integración con el LLM local de Ollama para generar respuestas

• Compatibilidad con múltiples formatos de documento (TXT, PDF, MD, DOCX, CSV)

• Carga automática de documentos desde el directorio de datos

• Servidor API RESTful con endpoints de /ingest y /query

• Servidor Model Context Protocol (MCP) para la integración con Claude Desktop/API

• Arquitectura basada en configuración (sin valores fijos en el código)

• Almacén vectorial persistente para consultas posteriores más rápidas

Arquitectura

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

Requisitos previos

1. Python 3.9+

2. Ollama instalado y ejecutándose localmente

3. Modelos de Ollama necesarios:

   • llama3.1:latest (u otro modelo LLM)

   • nomic-embed-text (u otro modelo de incrustación)

Instalación de Ollama

Visita ollama.ai para descargar e instalar Ollama en tu plataforma.

Después de la instalación, descarga los modelos necesarios:

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

Verifica que Ollama esté ejecutándose:

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

Instalación

1. Clona el repositorio:

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

2. Crea un entorno virtual:

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

3. Instala las dependencias:

pip install -r requirements.txt

Estructura del proyecto

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

Datos de ejemplo (Proyecto UCSC Extension)

Este repositorio incluye 13 archivos de datos de ejemplo para fines de demostración y prueba. Estos archivos representan un escenario empresarial realista para TechVision Electronicsy están diseñados para mostrar las capacidades del sistema en múltiples tipos de documento.

📊 Archivos de ejemplo incluidos

Datos estructurados (CSV) - 7 archivos:

• product_catalog.csv - Inventario de productos con especificaciones (5,000 filas)

• inventory_levels.csv - Niveles de stock y datos de almacén (10,000 filas)

• sales_orders_november.csv - Transacciones de ventas mensuales (8,000 filas)

• warranty_claims_q4.csv - Reclamaciones de garantía de clientes (3,000 filas)

• production_schedule_dec2024.csv - Calendario de fabricación (4,000 filas)

• supplier_pricing.csv - Información de precios de proveedores (6,000 filas)

• shipping_manifests.csv - Datos de envío y logística (5,000 filas)

Datos no estructurados (Markdown) - 5 archivos:

• customer_feedback_q4_2024.md - Reseñas y comentarios de clientes (600 fragmentos)

• market_analysis_2024.md - Investigación de mercado y tendencias (400 fragmentos)

• quality_control_report_nov2024.md - Hallazgos y problemas de control de calidad (501 fragmentos)

• return_policy_procedures.md - Documentación de políticas (300 fragmentos)

• support_tickets_summary.md - Resumen de soporte técnico (700 fragmentos)

Datos de texto - 1 archivo:

• product_specifications.txt - Especificaciones técnicas (334 fragmentos)

Conjunto de datos total:

• 41,000 filas CSV (divididas en 41,000 documentos a razón de 10 filas por fragmento)

• 2,835 fragmentos de texto/markdown (fragmentados a 1000 caracteres con un solapamiento de 200 de caracteres)

• 43,835 fragmentos de documento en total

🎯 Propósito

Estos archivos de ejemplo están incluidos para:

1. Demostrar las capacidades de búsqueda híbrida del sistema

2. Probar la recuperación tanto semántica (vectorial) como léxica (por palabras clave)

3. Validar la arquitectura de recuperación según el tipo de documento

4. Proporcionar ejemplos funcionales inmediatos sin configuración adicional

5. Ejeficiar los resultados de la síntesis de consultas entre documentos

📖 Resultados de las pruebas

Los resultados completos de las pruebas están documentados en TESTING_RESULTS.md, donde se muestra:

• ✅ Tasa de éxito de recuperación del 100% en todos los tipos de documento

• ✅ 17 consultas de prueba con resultados detallados

• ✅ Métricas de rendimiento y análisis comparativo

• ✅ Comparación de búsqueda semántica vs léxica vs híbrida

💡 Uso de los datos de ejemplo

Inicio rápido:

# 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?"

Para uso en producción: Si deseas usar tus propios datos:

1. Elimina esos archivos de ejemplo de data/

2. Añade tus propios documentos (TXT, PDF, MD, DOCX, CSV)

3. Vuelve a ejecutar la ingesta

4. Opcionalmente, puedes descomentar las exclusiones en .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"

Modifica este archivo para:

• Usar diferentes modelos de Ollama

• Cambiar la ubicación del directorio de datos

• Ajustar los parámetros de recuperación (valores de k)

• Configurar el host/puerto del servidor

• Cambiar la ubicación persistente del almacén vectorial

Uso

Opción 1: Script de línea de comandos

1. Añade tus documentos al directorio data/:

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

2. Ejecuta el script:

python scripts/run_demo.py

El script realizará:

• Cargar todos los documentos admitidos del directorio data/

• Inicializar las incrustaciones de Ollama y el LLM

• Crear los recuperadores vectorial y BM25

• Construir la cadena RAG híbrida

• Ejecutar consultas de ejemplo y mostrar los resultados

Opción 2: Servidor de API REST

1. Inicia el servidor de API REST:

python scripts/mcp_server.py

El servidor se iniciará en http://localhost:8000

Para detener el servidor: Pulsa Ctrl+C para un apagado correcto

2. Ingesta los documentos (haz esto primero):

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

Respuesta:

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

3. Consulta los documentos:

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

Respuesta:

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

4. Comprueba el estado del servidor:

curl http://localhost:8000/status

Endpoints de la API

Opción 3: Claude Desktop/API mediante MCP

El servidor MCP (Model Context Protocol) permite que Claude consulte directamente tu sistema RAG local.

Configuración para Claude Desktop

1. Primero, añade documentos a tu directorio de datos:

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

2. Edita el archivo config/claude_desktop_config.json para usar la ruta absoluta correcta:

{
  "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. Añade esta configuración a Claude Desktop:

   En 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

   En Windows:

   %APPDATA%\Claude\claude_desktop_config.json

   En Linux:

   ~/.config/Claude/claude_desktop_config.json

4. Reinicia Claude Desktop

5. En Claude Desktop, ahora verás las herramientas MCP disponibles. Puedes pedirle lo siguiente a Claude:

   • "Usa las herramienta ingest_documents para cargar mis documentos"

   • "Consulta mis documentos sobre [tu pregunta]"

   • "Verifica el estado del sistema RAG"

Herramientas MCP disponibles

Claude tendrá acceso a estas herramientas:

Ingesta de documentos y búsqueda:

• ingest_documents: Inicia la carga e indexación de documentos en modo asyncrono desde el directorio data/

• get_ingestion_status: Monitorea el progreso de la ingesta de documentos (porcentaje, archivo actual, etapa)

• query_documents: Consulta los documentos mediante la búsqueda híbrida (semántica + palabras clave)

• get_status: Verifica el estado del sistema RAG

Consultas de datos estructurados (para archivos CSV):

• list_datasets: Lista todos los conjuntos de datos CSV disponibles con columnas y tamaño de filas

• count_by_field: Cuenta las filas donde un campo coincide con un valor (por ejemplo, "cuenta las personas llamadas Michael")

• filter_dataset: Obtiene todas las filas que coinciden con criterios de campo (por ejemplo, "todas las personas de la empresa X")

• get_dataset_stats: Obtiene estadísticas sobre un conjunto de datos (filas, columnas, uso de memoria)

Ingesta asíncrona con seguimiento del progreso

El proceso de ingesta ahora se ejecuta en modo asíncrono y con actualizaciones en tiempo real:

• Sin bloqueo: La ingesta se ejecuta en segundo plano

• Seguimiento del progreso: Ver el porcentaje completado (0 al 100%)

• Actualizaciones a nivel de archivo: saber qué archivo se está procesando en cada momento

• Información sobre etapas: Carga de archivos (0-80 %) → Progreso de carga (0-100 %) → Construcción del índice (80-100 %) → Completado

• Monitoreo de estado: Verifica el progreso en cualquier momento con get_ingestion_status

Ejemplo de uso con 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..."

Consultas de datos estructurados

Para archivos CSV, usa las herramientas de consulta estructurada para obtener recuentos y filtros exactos:

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 ..."

Cuándo usar cada enfoque:

• Consultas estructuradas (count_by_field, filter_dataset): para recuentos exactos, filtros y datos estructurados

• Búsqueda semántica (query_documents): para preguntas conceptuales, comprensión de contenido, resúmenes

Formatos de archivo compatibles

El sistema carga y procesa automáticamente estos formatos:

• .txt - Archivos de texto plano

• .pdf - Documentos PDF

• .md - Archivos Markdown

• .docx - Documentos de Microsoft Word

• .csv - Archivos CSV

¡Simplemente coloca cualquier archivo compatible en el directorio data/!

Cómo funciona

Carga de documentos

La clase DocumentLoaderUtility:

1. Escanea el directorio data/ de forma recursiva

2. Identifica los formatos de archivo admitidos

3. Usa los cargadores apropiados para cada formato

4. Añade metadatos (archivo de origen, tipo de archivo) a cada documento

5. Devuelve una lista de objetos Document listos para la indexación

Recuperación híbrida

El EnsembleRetriever usa Reciprocal Rank Fusion (RRF) para:

1. Recuperar los mejores resultados con k de la búsqueda vectorial (semántica)

2. Recuperar los k resultados principales de la búsqueda BM25 (palabras clave)

3. Asignar puntuaciones de rango recíproco a cada resultado

4. Combinar las puntuaciones para producir una clasificación unificada

5. Devolver los documentos más relevantes en total

Este enfoque admite:

• Consultas semánticas ("¿Cómo solicito tiempo libre?")

• Consultas por palabras clave ("Formulario PTO HR-42")

• Consultas complejas que se benefician de ambos métodos

Personalización

Uso de diferentes modelos

Edita config/config.yaml para cambiar los modelos:

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

Ajuste de los parámetros de recuperación

Modifica los valores de k en config/config.yaml:

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

Cómo añadir más formatos de archivo compatibles

Edita src/hybrid_rag/document_loader.py para añadir más cargadores:

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

Cómo personalizar el prompt

Edita la plantilla del prompt en scripts/run_demo.py o scripts/mcp_server.py:

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

<context>
{context}
</context>

Question: {input}
""")

Flujo de trabajo de desarrollo

1. Añade documentos al directorio data/

2. Modifica la configuración en config/config.yaml si es necesario

3. Prueba con la línea de comandos: python scripts/run_demo.py

4. Despliega el servidor MCP: python scripts/mcp_server.py

5. Integra mediante la API en tus aplicaciones

Solución de problemas

"Error al conectar con Ollama"

• Asegúrate de que Ollama está instalado y ejecutándose

• Comunidad de que el servicio de Ollama sea accesible en la URL configurada

• Verifica que los modelos estén descargados: ollama list

"No se encontraron documentos en el directorio de datos"

• Añade archivos al directorio data/

• Asegúrate de que los archivos tengan extensiones compatibles (.txt, .pdf, .md, .docx, .csv)

• Comprueba que la ruta del directorio de datos en config/config.yaml sea correcta

"ModuleNotFoundError"

• Asegúrate de que el entorno virtual esté activado: source .venv/bin/activate

• Reinstala las dependencias: pip install -r requirements.txt

Resultados de recuperación deficientes

• Añade más documentos relevantes al directorio data/

• Ajusta los valores de k en config/config.yaml

• Prueba con un modelos de incrustación diferentes

• Asegúrate de que la terminología de las consultas coincida con el contenido de los documentos

Errores de la API

• Asegúrate de llamar a /ingest antes de /query

• Revisa los registros del servidor para ver mensajes de error detallados

• Verifica que Ollama esté en ejecución y sea accesible

• Comprueba que los documentos se hayan cargado correctamente

Ejemplo: Flujo de trabajo completo

# 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

Dependencias

Bibliotecas principales:

• langchain: Framework para aplicaciones LLM

• langchain-community: Integraciones de la comunidad

• langchain-ollama: Integración con Ollama

• chromadb: Base de datos vectorial para incrustaciones

• rank-bm25: Implementación de BM25 para búsqueda por palabras clave

• fastapi: Framework web para la API

• uvicorn: Servidor ASGI

• pyyaml: Análisis de configuración YAML

Cargadores de documentos:

• pypdf: Procesamiento de PDF

• python-docx: Procesamiento de documentos de Word

• unstructured: Markdown y otros formatos

Consejos de rendimiento

1. Persistencia del almacén vectorial: El almacén vectorial se persiste en disco (chroma_db/) después de la ingesta, lo que hace que las consultas posteriores sean más rápidas.

2. Procesamiento por lotes: Al añadir muchos documentos, usa el endpoint /ingest una sola vez en lugar de varias.

3. Parámetros de recuperación: Los valores de k más bajos (p. ej., 2-3) son más rápidos y a menudo suficientes para conjuntos de documentos pequeños.

4. Selección del modelo: Los modelos de incrustación más pequeños son más rápidos, pero pueden sacrificar algo de precisión.

Licencia

Este proyecto se proporciona tal cual con fines educativos y de demostración.

Contribuciones

No dudes en enviar incidencias, hacer un fork del repositorio y crear solicitudes de extracción para cualquier mejora.

Recursos

• Documentación de LangChain

• Documentación de Ollama

• Documentación de ChromaDB

• Documentación de FastAPI

• Algoritmo BM25

• Fusión de rango recíproco

Historial de cambios

Versión 2.0.0

• Sistema generalizado para funcionar con cualquier documento

• Se añadió el directorio data/ para la ingesta de documentos

• Se creó DocumentLoaderUtility para soporte de múltiples formatos

• Se reestructuró el proyecto para seguir las mejores prácticas de Python (estructura src)

• Se movió toda la configuración al directorio config/

• Se movió toda la documentación al directorio docs/

• Se creó la estructura de paquete Python adecuada con setup.py

• Se organizaron los scripts en el directorio scripts/

• Se actualizaron todas las rutas de importación y la documentación

Versión 1.0.0

• Implementación inicial con documentos de recursos humanos de ejemplo

• Búsqueda híbrida básica con recuperadores vectoriales y BM25