FAQ RAG Chatbot — PeopleForce HR SaaS

Intelligentes FAQ-Support-Chatbot-System basierend auf Retrieval-Augmented Generation (RAG). Es verarbeitet ein FAQ-Dokument eines HR-SaaS-Unternehmens, indiziert es in einer Vektordatenbank und beantwortet Benutzerfragen, indem es die relevantesten Textabschnitte aus dem Dokument abruft, um mit einem LLM präzise Antworten zu generieren. Dies eliminiert die Notwendigkeit manueller Suchen und entlastet das Kundensupport-Team.

RAG-Architektur

┌──────────────────────────────────────────────────────────────────┐
│                    PIPELINE DE INDEXACIÓN                        │
│                                                                  │
│  faq_document.txt ──► Chunking ──► Embeddings ──► ChromaDB      │
│                     (300 chars,   (text-embedding   (persistente │
│                      50 overlap)   -3-small)         local)      │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│                    PIPELINE DE CONSULTA                          │
│                                                                  │
│  Pregunta ──► Embedding ──► k-NN Search ──► Contexto ──► LLM    │
│  del usuario   de query     (coseno,        (top-k       (gpt-4o │
│                              ChromaDB)       chunks)      -mini)  │
│                                                     │            │
│                                                     ▼            │
│                                              JSON Response       │
│                                        { user_question,          │
│                                          system_answer,          │
│                                          chunks_related }        │
└──────────────────────────────────────────────────────────────────┘

Related MCP server: RAG-MCP

Installation

1. Repository klonen

git clone <repo-url>
cd kunz-mcp-project

2. Virtuelle Umgebung erstellen und Abhängigkeiten installieren

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

pip install -r requirements.txt

3. API-Key konfigurieren

cp .env.example .env
# Edita .env y agrega tu clave de OpenAI:
# OPENAI_API_KEY=sk-...

Verwendung

Indexierungs-Pipeline ausführen

python src/build_index.py

Dies lädt data/faq_document.txt, unterteilt es in Chunks, generiert Embeddings und speichert diese in ChromaDB (data/chroma_db/).

Eine Abfrage ausführen

python src/query.py "¿Cuántos días de vacaciones me corresponden?"

Beispiel-JSON-Ausgabe:

{
  "user_question": "¿Cuántos días de vacaciones me corresponden?",
  "system_answer": "Todos los colaboradores de tiempo completo tienen derecho a 15 días hábiles de vacaciones al año a partir de su primer aniversario. Con más de 3 años de antigüedad, se reciben 20 días hábiles, y con más de 7 años, 25 días hábiles.",
  "chunks_related": [
    {
      "text": "¿Cuántos días de vacaciones me corresponden?...",
      "metadata": {
        "chunk_index": 1,
        "total_chunks": 30,
        "source": "faq_document.txt"
      }
    }
  ]
}

Evaluierungs-Agent ausführen (Bonus)

python src/evaluator.py

Bewertet die Antworten in outputs/sample_queries.json und gibt eine Punktzahl von 0-10 mit Begründung zurück.

MCP-Server (Model Context Protocol)

Das Projekt enthält src/mcp_server.py, das die RAG-Pipeline als MCP-Server bereitstellt, sodass KI-Agenten (Claude Desktop, Cursor, VS Code mit Copilot usw.) die Tools direkt aufrufen können.

Verfügbare Tools

Voraussetzung

Stellen Sie sicher, dass der Index erstellt wurde, bevor Sie den Server starten:

python src/build_index.py

Option A — Direkt ausführen (stdio-Modus)

python src/mcp_server.py

Dies startet den Server im stdio-Modus, der mit jedem MCP-Client kompatibel ist.

Option B — Mit MCP CLI ausführen

mcp run src/mcp_server.py

Option C — In Claude Desktop integrieren

Bearbeiten Sie die Konfigurationsdatei von Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hr-faq-rag": {
      "command": "python",
      "args": ["/ruta/absoluta/a/kunz-mcp-project/src/mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Starten Sie Claude Desktop neu. Der Server erscheint als verfügbares Tool im Chat.

Option D — In Cursor oder VS Code integrieren

Fügen Sie dies in der MCP-Konfiguration des Editors hinzu (.cursor/mcp.json oder settings.json):

{
  "mcpServers": {
    "hr-faq-rag": {
      "command": "python",
      "args": ["src/mcp_server.py"]
    }
  }
}

Hinweis: Der Server liest OPENAI_API_KEY aus der .env-Datei des Projekts; falls der Editor die Umgebung nicht übernimmt, geben Sie ihn explizit im Block "env" an, wie in Option C gezeigt.

Projektstruktur

kunz-mcp-project/
├── README.md               # Documentación del proyecto
├── requirements.txt        # Dependencias con versiones
├── .env.example            # Plantilla de variables de entorno
├── config.yaml             # Configuración del modelo, embeddings y RAG
├── data/
│   └── faq_document.txt    # Documento FAQ fuente (≥1000 palabras)
├── src/
│   ├── __init__.py
│   ├── build_index.py      # Pipeline de indexación (load → chunk → embed → store)
│   ├── query.py            # Pipeline de consulta (search → generate → JSON)
│   ├── evaluator.py        # Agente evaluador de calidad (bonus)
│   ├── mcp_server.py       # Servidor MCP (expone los tools vía FastMCP)
│   └── shared/
│       ├── __init__.py
│       ├── config_loader.py  # Carga config.yaml + .env
│       └── logger.py         # Logger con Rich (colores y formato)
└── outputs/
    └── sample_queries.json   # ≥3 ejemplos de consulta-respuesta

Technische Entscheidungen

Chunking-Strategie

Es wird RecursiveCharacterTextSplitter mit chunk_size=300 und chunk_overlap=50 verwendet.

• Warum rekursiv? Die hierarchischen Trennzeichen (\n\n → \n → . → ) bewahren die natürlichen semantischen Grenzen des Textes (Abschnitte, Absätze, Sätze) und erzeugen kohärentere Chunks als ein Schnitt bei fester Größe.

• Warum 300 Zeichen? Erzeugt Chunks von ca. 75-125 Tokens, was innerhalb des erforderlichen Bereichs von 50-500 Tokens liegt. Kleinere Chunks verbessern die Genauigkeit der Vektorsuche durch Reduzierung des semantischen Rauschens.

• Warum 50 Überlappung? Die Überlappung stellt die Kontextkontinuität zwischen benachbarten Chunks sicher und verhindert, dass relevante Informationen an einer Grenze abgeschnitten werden.

Vektorsuchmethode

Es wird k-NN (k-Nearest Neighbors) mit Kosinus-Ähnlichkeit auf dem HNSW-Index von ChromaDB verwendet.

• Warum k-NN? Es ist die direkteste und vorhersehbarste Methode für die Suche nach ähnlichen Vektoren. ChromaDB optimiert intern mit HNSW (Hierarchical Navigable Small World) für sublineare Suchvorgänge.

• Warum Kosinus? Die Kosinus-Ähnlichkeit misst die semantische Richtung der Vektoren, nicht deren Betrag. Dies ist ideal für normalisierte Text-Embeddings wie die von OpenAI (text-embedding-3-small), bei denen Vektoren mit ähnlicher Bedeutung in die gleiche Richtung zeigen.

• Top-k = 3 liefert 2-5 Chunks pro Abfrage, was ausreicht, um Kontext zu bieten, ohne Rauschen einzuführen.

Vorteile von RAG

• Aktualisierung ohne Re-Training: Es reicht aus, das Quelldokument zu aktualisieren und neu zu indizieren, ohne dass ein kostspieliges Fine-Tuning des LLM erforderlich ist.

• Transparenz: Jede Antwort enthält die verwendeten Chunks (chunks_related), was die Überprüfung der Informationsquelle ermöglicht.

• Attribution: Die Metadaten jedes Chunks (source, chunk_index) ermöglichen eine vollständige Rückverfolgbarkeit der Antwort.

Konfiguration

Die Datei config.yaml zentralisiert alle Parameter: