Hybrid-RAG-Projekt

Ein generalisiertes Retrieval-Augmented-Generation-System (RAG) mit Hybrid-Suchfunktionen, das mit beliebigen Dokumenten funktioniert, die Sie bereitstellen. Kombiniert semantische (dichte Vektor-)Suche und Stichwortsuche (sparse BM25) für optimale Dokumentabfrage, mit einer MCP-Server-API für einfache Integration.

🎯 Hauptfunktionen: Multi-Format-Unterstützung • Lokales LLM • Claude-Desktop-Integration • Strukturierte Datenabfragen • Dokumenttyp-bewusstes Retrieval

🚀 Schnellstart (kein MCP erforderlich!)

Sie benötigen weder Claude Desktop noch MCP, um dieses Projekt zu nutzen! Führen Sie einfach aus:

# 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

Das war's! Stellen Sie Fragen zu den 43.835 Dokument-Chunks im Beispieldatensatz.

📖 Siehe Schnellstart-Anleitung für vollständige Nutzungsanweisungen. 📚 Durchsuchen Sie die gesamte Dokumentation im Ordner docs/ oder beginnen Sie mit docs/README.md.

Related MCP server: Hybrid RAG Project MCP Server

Überblick

Dieses Projekt implementiert ein Hybrid-RAG-System, das Folgendes kombiniert:

• Semantische Suche: Dichte Vektor-Embeddings zum Verständnis von Bedeutung und Kontext

• Stichwortsuche: BM25-Sparse-Retrieval für exakte Stichwortübereinstimmungen

• Hybrid-Fusion: Reciprocal Rank Fusion (RRF) zur Kombination der Ergebnisse beider Methoden

• MCP-Server: Sowohl REST-API als auch Model Context Protocol-Server für Claude-Integration

• Multi-Format-Unterstützung: Automatisches Laden von Dokumenten aus verschiedenen Dateiformaten

Der hybride Ansatz gewährleistet eine bessere Retrieval-Genauigkeit, indem er die Stärken beider Suchmethoden nutzt.

Funktionen

• Vektorbasierte semantische Suche mit Chroma- und Ollama-Embeddings

• BM25-Stichwortsuche für exakte Begriffübereinstimmungen

• Ensemble-Retriever mit Reciprocal Rank Fusion (RRF)

• Integration mit lokalem Ollama-LLM zur Antwortgenerierung

• Unterstützung mehrerer Dokumentformate (TXT, PDF, MD, DOCX, CSV)

• Automatisches Laden von Dokumenten aus dem Datenverzeichnis

• RESTful-API-Server mit /ingest- und /query-Endpunkten

• Model Context Protocol (MCP)-Server für Claude Desktop/API-Integration

• Konfigurationsgesteuerte Architektur (keine hartcodierten Werte)

• Persistenter Vektorspeicher für schnellere nachfolgende Abfragen

Architektur

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

Voraussetzungen

1. Python 3.9+

2. Ollama installiert und lokal ausgeführt

3. Erforderliche Ollama-Modelle:

   • llama3.1:latest (oder ein anderes LLM-Modell)

   • nomic-embed-text (oder ein anderes Embedding-Modell)

Ollama installieren

Besuchen Sie ollama.ai, um Ollama für Ihre Plattform herunterzuladen und zu installieren.

Nach der Installation ziehen Sie die erforderlichen Modelle:

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

Überprüfen Sie, ob Ollama läuft:

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

Installation

1. Klonen Sie das Repository:

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

2. Erstellen Sie eine virtuelle Umgebung:

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

3. Installieren Sie die Abhängigkeiten:

pip install -r requirements.txt

Projektstruktur

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

Beispieldaten (UCSC-Erweiterungsprojekt)

Dieses Repository enthält 13 Beispieldatendateien zu Demonstrations- und Testzwecken. Diese Dateien repräsentieren ein realistisches Geschäftsszenario für TechVision Electronics und sollen die Fähigkeiten des Systems über mehrere Dokumenttypen hinweg demonstrieren.

📊 Enthaltene Beispieldateien

Strukturierte Daten (CSV) - 7 Dateien:

• product_catalog.csv - Produktinventar mit Spezifikationen (5.000 Zeilen)

• inventory_levels.csv - Lagerbestände und Lagerdaten (10.000 Zeilen)

• sales_orders_november.csv - Monatliche Verkaufstransaktionen (8.000 Zeilen)

• warranty_claims_q4.csv - Kundengarantieansprüche (3.000 Zeilen)

• production_schedule_dec2024.csv - Fertigungsplan (4.000 Zeilen)

• supplier_pricing.csv - Lieferantenpreisinformationen (6.000 Zeilen)

• shipping_manifests.csv - Versand- und Logistikdaten (5.000 Zeilen)

Unstrukturierte Daten (Markdown) - 5 Dateien:

• customer_feedback_q4_2024.md - Kundenbewertungen und Feedback (600 Chunks)

• market_analysis_2024.md - Marktforschung und Trends (400 Chunks)

• quality_control_report_nov2024.md - Qualitätskontrollbefunde und Probleme (501 Chunks)

• return_policy_procedures.md - Richtliniendokumentation (300 Chunks)

• support_tickets_summary.md - Technische Support-Zusammenfassung (700 Chunks)

Textdaten - 1 Datei:

• product_specifications.txt - Technische Spezifikationen (334 Chunks)

Gesamtdatensatz:

• 41.000 CSV-Zeilen (in 41.000 Dokumente aufgeteilt, 10 Zeilen pro Chunk)

• 2.835 Text-/Markdown-Chunks (aufgeteilt bei 1000 Zeichen mit 200 Zeichen Überlappung)

• 43.835 insgesamt durchsuchbare Dokument-Chunks

🎯 Zweck

Diese Beispieldateien sind enthalten, um:

1. Die Hybrid-Suchfähigkeiten des Systems zu demonstrieren

2. Sowohl semantisches (Vektor-) als auch lexikalisches (Stichwort-) Retrieval zu testen

3. Die dokumenttyp-bewusste Retrieval-Architektur zu validieren

4. Sofort funktionierende Beispiele ohne zusätzliche Einrichtung bereitzustellen

5. Die Synthese von Abfragen über mehrere Dokumente hinweg zu präsentieren

📖 Testergebnisse

Umfassende Testergebnisse sind in TESTING_RESULTS.md dokumentiert und zeigen:

• ✅ 100% Retrieval-Erfolgsquote über alle Dokumenttypen hinweg

• ✅ 17 Testabfragen mit detaillierten Ergebnissen

• ✅ Leistungsmetriken und vergleichende Analyse

• ✅ Semantischer vs. lexikalischer vs. hybrider Suchvergleich

💡 Verwendung der Beispieldaten

Schnellstart:

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

Für den Produktionseinsatz: Um stattdessen Ihre eigenen Daten zu verwenden:

1. Entfernen oder sichern Sie die Beispieldateien aus data/

2. Fügen Sie Ihre eigenen Dokumente hinzu (TXT, PDF, MD, DOCX, CSV)

3. Führen Sie die Aufnahme erneut aus

4. Kommentieren Sie optional die Datenausschlüsse in .gitignore aus

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

Ändern Sie diese Datei, um:

• Andere Ollama-Modelle zu verwenden

• Den Speicherort des Datenverzeichnisses zu ändern

• Retrieval-Parameter (k-Werte) anzupassen

• Server-Host/Port zu konfigurieren

• Den Speicherort des Vektorspeichers zu ändern

Verwendung

Option 1: Befehlszeilenskript

1. Fügen Sie Ihre Dokumente zum Verzeichnis data/ hinzu:

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

2. Führen Sie das Skript aus:

python scripts/run_demo.py

Das Skript wird:

• Alle unterstützten Dokumente aus dem Verzeichnis data/ laden

• Ollama-Embeddings und LLM initialisieren

• Vektor- und BM25-Retriever erstellen

• Die Hybrid-RAG-Kette aufbauen

• Beispielabfragen ausführen und Ergebnisse anzeigen

Option 2: REST-API-Server

1. Starten Sie den REST-API-Server:

python scripts/mcp_server.py

Der Server startet auf http://localhost:8000

Zum Stoppen des Servers: Drücken Sie Ctrl+C für einen sauberen Shutdown

2. Dokumente aufnehmen (zuerst ausführen):

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

Antwort:

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

3. Dokumente abfragen:

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

Antwort:

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

4. Serverstatus überprüfen:

curl http://localhost:8000/status

API-Endpunkte

Option 3: Claude Desktop/API über MCP

Der MCP-Server (Model Context Protocol) ermöglicht es Claude, direkt Ihr lokales RAG-System abzufragen.

Einrichtung für Claude Desktop

1. Fügen Sie zuerst Dokumente zu Ihrem Datenverzeichnis hinzu:

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

2. Bearbeiten Sie die Datei config/claude_desktop_config.json, um den korrekten absoluten Pfad zu verwenden:

{
  "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. Fügen Sie diese Konfiguration zu Claude Desktop hinzu:

   Auf 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

   Auf Windows:

   %APPDATA%\Claude\claude_desktop_config.json

   Auf Linux:

   ~/.config/Claude/claude_desktop_config.json

4. Starten Sie Claude Desktop neu

5. In Claude Desktop sehen Sie nun die verfügbaren MCP-Tools. Sie können Claude bitten:

   • "Verwenden Sie das Tool ingest_documents, um meine Dokumente zu laden"

   • "Fragen Sie meine Dokumente zu [Ihrer Frage] ab"

   • "Überprüfen Sie den Status des RAG-Systems"

Verfügbare MCP-Tools

Claude hat Zugriff auf diese Tools:

Dokumentaufnahme und -suche:

• ingest_documents: Startet das Laden und Indizieren von Dokumenten asynchron aus dem Verzeichnis data/

• get_ingestion_status: Überwacht den Fortschritt der Dokumentaufnahme (Prozentsatz, aktuelle Datei, Phase)

• query_documents: Fragt die Dokumente mit Hybrid-Suche ab (semantisch + Stichwort)

• get_status: Überprüft den Status des RAG-Systems

Strukturierte Datenabfragen (für CSV-Dateien):

• list_datasets: Listet alle verfügbaren CSV-Datensätze mit Spalten und Zeilenanzahl auf

• count_by_field: Zählt Zeilen, bei denen ein Feld einem Wert entspricht (z. B. "zähle Personen namens Michael")

• filter_dataset: Ruft alle Zeilen ab, die Feldkriterien entsprechen (z. B. "alle Personen von Firma X")

• get_dataset_stats: Ruft Statistiken zu einem Datensatz ab (Zeilen, Spalten, Speichernutzung)

Asynchrone Aufnahme mit Fortschrittsverfolgung

Der Aufnahmeprozess läuft jetzt asynchron mit Echtzeit-Fortschrittsaktualisierungen:

• Nicht blockierend: Die Aufnahme läuft im Hintergrund

• Fortschrittsverfolgung: Sie sehen den Prozentsatz (0-100%)

• Datei-Ebene-Updates: Sie wissen, welche Datei gerade verarbeitet wird

• Phaseninformationen: Laden von Dateien (0-80%) → Indexaufbau (80-100%) → Abgeschlossen

• Statusüberwachung: Überprüfen Sie den Fortschritt jederzeit mit get_ingestion_status

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

Strukturierte Datenabfragen

Für CSV-Dateien verwenden Sie strukturierte Abfragetools für exakte Zählungen und Filterung:

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

Wann welcher Ansatz verwendet werden sollte:

• Strukturierte Abfragen (count_by_field, filter_dataset): Für exakte Zählungen, Filterung und strukturierte Daten

• Semantische Suche (query_documents): Für konzeptionelle Fragen, Inhaltsverständnis, Zusammenfassungen

Unterstützte Dateiformate

Das System lädt und verarbeitet automatisch diese Formate:

• .txt - Reine Textdateien

• .pdf - PDF-Dokumente

• .md - Markdown-Dateien

• .docx - Microsoft Word-Dokumente

• .csv - CSV-Dateien

Legen Sie einfach unterstützte Dateien in das Verzeichnis data/!

So funktioniert es

Dokumentladen

Die Klasse DocumentLoaderUtility:

1. Durchsucht das Verzeichnis data/ rekursiv

2. Identifiziert unterstützte Dateiformate

3. Verwendet geeignete Loader für jedes Format

4. Fügt Metadaten (Quelldatei, Dateityp) zu jedem Dokument hinzu

5. Gibt eine Liste von Document-Objekten zurück, die für die Indizierung bereit sind

Hybrid-Retrieval

Der EnsembleRetriever verwendet Reciprocal Rank Fusion (RRF), um:

1. Top-k-Ergebnisse aus der Vektorsuche (semantisch) abzurufen

2. Top-k-Ergebnisse aus der BM25-Suche (Stichwort) abzurufen

3. Reziproke Rangfolge-Scores jedem Ergebnis zuzuweisen

4. Scores zu einer einheitlichen Rangfolge zu kombinieren

5. Die insgesamt relevantesten Dokumente zurückzugeben

Dieser Ansatz behandelt:

• Semantische Abfragen ("Wie beantrage ich Freizeit?")

• Stichwortabfragen ("PTO-Formular HR-42")

• Komplexe Abfragen, die von beiden Methoden profitieren

Anpassung

Verwendung verschiedener Modelle

Bearbeiten Sie config/config.yaml, um Modelle zu ändern:

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

Anpassen der Retrieval-Parameter

Ändern Sie die k-Werte in config/config.yaml:

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

Hinzufügen weiterer Dateiformat-Unterstützung

Bearbeiten Sie src/hybrid_rag/document_loader.py, um weitere Loader hinzuzufügen:

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

Anpassen des Prompts

Bearbeiten Sie die Prompt-Vorlage in scripts/run_demo.py oder scripts/mcp_server.py:

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

<context>
{context}
</context>

Question: {input}
""")

Entwicklungsworkflow

1. Dokumente hinzufügen zum Verzeichnis data/

2. Konfiguration ändern in config/config.yaml nach Bedarf

3. Mit der Befehlszeile testen: python scripts/run_demo.py

4. MCP-Server bereitstellen: python scripts/mcp_server.py

5. Über die API in Ihre Anwendungen integrieren

Fehlerbehebung

"Fehler beim Verbinden mit Ollama"

• Stellen Sie sicher, dass Ollama installiert ist und läuft

• Überprüfen Sie, ob der Ollama-Dienst unter der konfigurierten URL erreichbar ist

• Verifizieren Sie, dass die Modelle heruntergeladen sind: ollama list

"Keine Dokumente im Datenverzeichnis gefunden"

• Fügen Sie Dateien zum Verzeichnis data/ hinzu

• Stellen Sie sicher, dass die Dateien unterstützte Erweiterungen haben (.txt, .pdf, .md, .docx, .csv)

• Überprüfen Sie, ob der Pfad zum Datenverzeichnis in config/config.yaml korrekt ist

"ModuleNotFoundError"

• Stellen Sie sicher, dass die virtuelle Umgebung aktiviert ist: source .venv/bin/activate

• Installieren Sie die Abhängigkeiten neu: pip install -r requirements.txt

Schlechte Retrieval-Ergebnisse

• Fügen Sie relevantere Dokumente zum Verzeichnis data/ hinzu

• Passen Sie die k-Werte in config/config.yaml an

• Probieren Sie verschiedene Embedding-Modelle aus

• Stellen Sie sicher, dass die Abfragebegriffe mit dem Dokumentinhalt übereinstimmen

API-Fehler

• Stellen Sie sicher, dass Sie /ingest vor /query aufrufen

• Überprüfen Sie die Server-Logs auf detaillierte Fehlermeldungen

• Stellen Sie sicher, dass Ollama läuft und erreichbar ist

• Überprüfen Sie, dass die Dokumente erfolgreich geladen wurden

Beispiel: Vollständiger Ablauf

# 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

Abhängigkeiten

Kernbibliotheken:

• langchain: Framework für LLM-Anwendungen

• langchain-community: Community-Integrationen

• langchain-ollama: Ollama-Integration

• chromadb: Vektordatenbank für Embeddings

• rank-bm25: BM25-Implementierung für die Stichwortsuche

• fastapi: Web-Framework für die API

• uvicorn: ASGI-Server

• pyyaml: YAML-Konfigurationsparsing

Dokumentenlader:

• pypdf: PDF-Verarbeitung

• python-docx: Word-Dokumentverarbeitung

• unstructured: Markdown und andere Formate

Leistungstipps

1. Persistenz des Vektorstores: Das Vektorstore wird nach der Indexierung auf der Festplatte (chroma_db/) gespeichert, wodurch nachfolgende Abfragen schneller werden.

2. Stapelverarbeitung: Verwenden Sie beim Hinzufügen vieler Dokumente den /ingest-Endpunkt einmal, anstatt ihn mehrfach aufzurufen.

3. Abrufparameter: Niedrigere k-Werte (z. B. 2–3) sind schneller und für kleine Dokumentsätze oft ausreichend.

4. Modellauswahl: Kleinere Embedding-Modelle sind schneller, können aber an Genauigkeit einbüßen.

Lizenz

Dieses Projekt wird ohne Gewähr für Bildungs- und Demonstrationszwecke bereitgestellt.

Mitwirken

Sie können gerne Issues einreichen, das Repository forken und Pull Requests für Verbesserungen erstellen.

Ressourcen

• LangChain-Dokumentation

• Ollama-Dokumentation

• ChromaDB-Dokumentation

• FastAPI-Dokumentation

• BM25-Algorithmus

• Reciprocal Rank Fusion

Änderungshistorie

Version 2.0.0

• System zur Verarbeitung beliebiger Dokumente verallgemeinert

• data/-Verzeichnis für die Dokumentenindexierung hinzugefügt

• DocumentLoaderUtility für die Unterstützung mehrerer Formate erstellt

• Projektstruktur gemäß Python-Best Practices neu organisiert (src-Layout)

• Gesamte Konfiguration in das config/-Verzeichnis verschoben

• Gesamte Dokumentation in das docs/-Verzeichnis verschoben

• Ordentliche Python-Paketstruktur mit setup.py erstellt

• Skripte in das scripts/-Verzeichnis organisiert

• Alle Importpfade und die Dokumentation aktualisiert

Version 1.0.0

• Erste Implementierung mit Beispieldokumenten für die Personalabteilung

• Grundlegende hybride Suche mit Vektor- und BM25-Retrievern