---
name: rag-pipeline-architect
last_verified: 2026-04-02
description: "Design and architect RAG (Retrieval-Augmented Generation) pipelines. Covers vector DB selection, chunking strategies, hybrid retrieval (vector + knowledge graph), semantic caching, ingestion pipeline design, embedding model selection, and production deployment patterns. Triggers on: RAG, retrieval augmented generation, vector database, embeddings, chunking, FAISS, Qdrant, Milvus, pgvector, Weaviate, Pinecone, knowledge graph, Neo4j, semantic search, document Q&A, ingestion pipeline, reranking, hybrid search, or any question about building a RAG system."
---

# RAG Pipeline Architect

Dieses Skill-Dokument destilliert Architektur-Patterns aus zwei analysierten RAG-Repos (scalable-rag-pipeline, intelligent-rag-service) und dify's 30+ Vector-DB-Adapter-Erfahrung.

---

## Input-Parameter

| Parameter | Werte | Default | Beschreibung |
|-----------|-------|---------|-------------|
| **Use Case** | `document-qa` / `chatbot` / `search` / `code-qa` / `multi-modal` | (Pflicht) | Was soll das RAG-System leisten? |
| **Scale** | `prototype` / `production` / `enterprise` | `production` | Erwartete Dokumentenmenge und Query-Last |
| **Document Types** | PDF, Markdown, HTML, Code, etc. | (Pflicht) | Welche Dokumente werden indexiert? |
| **Existing Stack** | PostgreSQL, AWS, K8s, etc. | Aus Kontext | Vorhandene Infrastruktur |
| **LLM Provider** | OpenAI, Anthropic, self-hosted, etc. | Aus Kontext | Bevorzugter LLM-Anbieter |
| **Budget** | `minimal` / `moderate` / `enterprise` | `moderate` | Kostenrahmen |

---

## Vector DB Selection Matrix

Basierend auf dify's 30+ Adapter-Implementierungen und scalable-rag-pipeline's Qdrant-Einsatz.

| Vector DB | Best For | Self-Hosted | Filtering | Scale | Cost |
|-----------|----------|-------------|-----------|-------|------|
| **Qdrant** | Production hybrid search, metadata filtering | Ja (Docker) | Exzellent (Payload-Filter) | Hoch | Open Source |
| **pgvector** | Teams mit bestehendem PostgreSQL | Ja (Extension) | SQL WHERE | Mittel | Kostenlos |
| **FAISS** | Prototyping, In-Memory-Demos | Ja (Library) | Keine native | Niedrig (RAM-limitiert) | Kostenlos |
| **Milvus** | Massive Scale (Milliarden Vektoren) | Ja (K8s) | Gut | Sehr hoch | Open Source |
| **Weaviate** | Multi-modal (Text + Bild) | Ja (Docker) | GraphQL-Filter | Hoch | Open Source |
| **Pinecone** | Managed Service, kein Ops-Aufwand | Nein (Cloud) | Metadata-Filter | Hoch | Teuer ab Scale |
| **ChromaDB** | Einfachste lokale Entwicklung | Ja (pip install) | Basic | Niedrig | Kostenlos |
| **Neo4j** | Knowledge Graph + Vektor (Hybrid) | Ja (Docker) | Cypher Queries | Mittel | Community Edition kostenlos |

**Empfehlung nach Scale:**
- `prototype`: FAISS oder ChromaDB (kein Setup)
- `production`: Qdrant oder pgvector (je nach bestehendem Stack)
- `enterprise`: Qdrant + Neo4j Hybrid (wie in scalable-rag-pipeline)

**Quelle:** scalable-rag-pipeline nutzt Qdrant fuer Dense Vectors + Neo4j fuer Knowledge Graph. intelligent-rag-service nutzt FAISS (in-memory, geht bei Restart verloren -- Anti-Pattern fuer Production).

---

## Chunking Strategy Guide

### Nach Dokumenttyp

| Dokumenttyp | Strategie | Chunk-Groesse | Overlap |
|-------------|-----------|---------------|---------|
| **PDF (Fliesstext)** | Recursive Character Split | 512-1024 Tokens | 10-20% |
| **PDF (Tabellen)** | Table-aware Parsing (Unstructured/LlamaParse) | Tabelle als Einheit | 0% |
| **Markdown** | Header-basiertes Splitting | Pro Section | 0% (Headers als Metadata) |
| **Code** | AST-basiert oder Function-Level | Pro Funktion/Klasse | 0% |
| **HTML** | Tag-basiert + Boilerplate-Entfernung | 512-1024 Tokens | 10% |
| **Chat/Logs** | Message-basiert | Pro Nachricht/Turn | 1-2 Messages Kontext |

### Nach Use Case

| Use Case | Empfohlene Chunk-Groesse | Begruendung |
|----------|--------------------------|-------------|
| Q&A (praezise Antworten) | 256-512 Tokens | Kleine Chunks = praezisere Retrieval-Ergebnisse |
| Zusammenfassung | 1024-2048 Tokens | Groessere Chunks = mehr Kontext pro Retrieval |
| Chatbot (konversationell) | 512-1024 Tokens | Balance aus Praezision und Kontext |
| Code-Suche | Funktion/Klasse als Einheit | Semantisch zusammenhaengende Einheiten |

### Overlap-Strategie

- **10-20% Overlap** fuer Fliesstext (verhindert Informationsverlust an Chunk-Grenzen)
- **0% Overlap** fuer strukturierte Dokumente (Tabellen, Code, Markdown-Sections)
- **Metadata anreichern**: Immer Dokumentname, Seitenzahl, Section-Header als Metadata mitgeben

**Anti-Pattern (aus intelligent-rag-service):** Kein Overlap konfiguriert, keine Metadata -- Kontext geht an Chunk-Grenzen verloren.

---

## Embedding Model Selection

| Modell | Dimensionen | Sprache | Hosting | Qualitaet | Kosten |
|--------|-------------|---------|---------|-----------|--------|
| **BGE-M3** | 1024 | Multilingual | Self-hosted (GPU) | Sehr gut | Hardware-Kosten |
| **all-MiniLM-L6-v2** | 384 | Englisch | Self-hosted (CPU) | Gut (fuer Groesse) | Minimal |
| **text-embedding-3-large** (OpenAI) | 3072 | Multilingual | API | Exzellent | $0.13/1M Tokens |
| **text-embedding-3-small** (OpenAI) | 1536 | Multilingual | API | Sehr gut | $0.02/1M Tokens |
| **embed-v3** (Cohere) | 1024 | Multilingual | API | Sehr gut | $0.10/1M Tokens |
| **nomic-embed-text** | 768 | Englisch | Self-hosted (CPU) | Gut | Kostenlos |

**Empfehlung:**
- Budget-sensitiv + Multilingual: `text-embedding-3-small` (OpenAI)
- Self-hosted + Multilingual: `BGE-M3` (wie in scalable-rag-pipeline)
- Prototyping: `all-MiniLM-L6-v2` (wie in intelligent-rag-service, laeuft auf CPU)
- Maximale Qualitaet: `text-embedding-3-large` (OpenAI)

**Quelle:** scalable-rag-pipeline nutzt BGE-M3 via Ray Serve auf GPU-Nodes. intelligent-rag-service nutzt all-MiniLM-L6-v2 lokal.

---

## Retrieval Architecture Patterns

### Pattern 1: Simple RAG (Prototyp)

```
User Query -> Embed Query -> Vector Search (Top-K) -> Inject Context -> LLM -> Response
```

- **Wann:** Prototyping, einfache Q&A, <10K Dokumente
- **Beispiel:** intelligent-rag-service (FAISS + SageMaker)
- **Limitierung:** Keine Query-Optimierung, kein Reranking, ein Retrieval-Pfad

### Pattern 2: Hybrid Retrieval (Production)

```
User Query -> [parallel]
  ├── Embed -> Qdrant Dense Vector Search (Top-K)
  └── Extract Entities -> Neo4j Cypher Query (Graph Traversal)
-> Merge + Deduplicate -> Rerank -> Inject Context -> LLM -> Response
```

- **Wann:** Production, >10K Dokumente, relationale Daten
- **Beispiel:** scalable-rag-pipeline (Qdrant + Neo4j via asyncio.gather)
- **Vorteil:** Vector fuer semantische Aehnlichkeit + Graph fuer strukturierte Beziehungen
- **Wichtig:** Parallele Ausfuehrung via `asyncio.gather` fuer Latenz-Reduktion

### Pattern 3: Agentic RAG (Enterprise)

```
User Query -> Planner Agent (Intent Detection, Query Refinement)
  -> Decision: retrieve / direct_answer / tool_use
  -> Retriever Agent (Hybrid Search)
  -> Responder Agent (Context Synthesis + Answer)
```

- **Wann:** Komplexe Anfragen, Multi-Step-Reasoning, Tool-Integration
- **Beispiel:** scalable-rag-pipeline (LangGraph Planner->Retriever->Responder)
- **Achtung:** scalable-rag hat die Conditional Edges NICHT implementiert -- der Graph laeuft immer linear. Fuer echte agentic Logik muessen Conditional Edges her.

### Pattern 4: RAG mit Semantic Cache

```
User Query -> Embed Query -> Cache Lookup (Similarity Search in Cache-Collection)
  ├── Cache Hit (Similarity > Threshold) -> Return Cached Response
  └── Cache Miss -> Full RAG Pipeline -> Cache Response -> Return
```

- **Wann:** Wiederkehrende/aehnliche Fragen, Kosten-Reduktion
- **Beispiel:** scalable-rag-pipeline (separate Qdrant-Collection fuer Cache)
- **Implementierung:** Eigene Qdrant-Collection, Embedding der Query, Similarity-Threshold (z.B. 0.95), TTL-Management
- **Kosten-Ersparnis:** 40-70% weniger LLM-Calls bei FAQ-artigen Workloads

### Pattern 5: HyDE (Hypothetical Document Embeddings)

```
User Query -> LLM generates hypothetical answer -> Embed hypothetical answer -> Vector Search -> Real context -> LLM -> Final Response
```

- **Wann:** Queries die semantisch weit von den Dokumenten entfernt sind
- **Beispiel:** scalable-rag-pipeline hat HyDE-Modul (enhancers/hyde.py), aber NICHT aktiviert
- **Trade-off:** +1 LLM-Call Latenz, aber bessere Retrieval-Qualitaet

### Pattern 6: Query Rewriting

```
User Query -> LLM rewrites query for better retrieval -> Embed rewritten query -> Vector Search -> Context -> LLM -> Response
```

- **Wann:** Konversationelle Queries ("Was meinst du damit?"), vage Anfragen
- **Beispiel:** scalable-rag-pipeline hat Query Rewriter (enhancers/query_rewriter.py), aber NICHT aktiviert

---

## Ingestion Pipeline Design

Basierend auf scalable-rag-pipeline's Ray Data Pipeline:

```
S3/MinIO (Dokumente)
  -> Parse (PDF/HTML/Markdown Extraktion)
  -> Chunk (Recursive Split mit Overlap)
  -> [parallel]
      ├── Embed (BGE-M3 via Ray Serve, batched GPU compute)
      └── Graph Extract (Entity/Relation Extraction fuer Neo4j)
  -> [parallel]
      ├── Index in Qdrant (Vektoren)
      └── Index in Neo4j (Knowledge Graph)
```

**Skalierungs-Pattern:**
- Lazy S3 Reads (nicht alles auf einmal in Memory laden)
- Batched GPU Compute (Embeddings in Batches, nicht einzeln)
- Ray Data fuer horizontale Skalierung (N Worker-Nodes)
- Paralleles Indexing (Vector + Graph gleichzeitig)

**Anti-Patterns:**
- Alles in-memory halten (intelligent-rag-service: FAISS verliert alles bei Restart)
- Sequentielles Processing (ein Dokument nach dem anderen)
- Kein Batching bei Embeddings (N API-Calls statt 1 Batch-Call)

---

## Semantic Caching Pattern

Detaillierte Implementierung basierend auf scalable-rag-pipeline:

1. **Separate Collection:** Eigene Qdrant-Collection `semantic_cache` (nicht die Dokument-Collection)
2. **Cache Write:** Nach jeder erfolgreichen RAG-Antwort: Query-Embedding + Response + Timestamp speichern
3. **Cache Read:** Vor jedem RAG-Call: Query embedden, Similarity Search gegen Cache-Collection
4. **Threshold:** Cosine Similarity > 0.95 = Cache Hit (konfigurierbar)
5. **TTL:** Eintraege aelter als X Stunden/Tage invalidieren
6. **Invalidierung:** Bei Dokument-Updates Cache fuer betroffene Dokumente loeschen

**Kosten-Schaetzung:**
- Embedding-Kosten fuer Cache-Lookup: ~$0.00002 pro Query (text-embedding-3-small)
- Eingesparte LLM-Kosten pro Cache-Hit: ~$0.01-0.10 (je nach Modell und Context-Laenge)
- Break-even bei >10% Cache-Hit-Rate

---

## Production Checklist

- [ ] **Connection Pooling**: httpx.AsyncClient wiederverwenden (Anti-Pattern aus scalable-rag: neuer Client pro Request)
- [ ] **Error Handling**: Fallback wenn Embedding-Service nicht erreichbar
- [ ] **Monitoring**: Retrieval-Latenz, Cache-Hit-Rate, Relevanz-Scores tracken
- [ ] **Index Maintenance**: Reindexierung-Strategie bei Dokument-Updates
- [ ] **Rate Limiting**: Ingestion-Endpoints schuetzen
- [ ] **Structured Logging**: structlog/Pino, NICHT print() (Anti-Pattern aus beiden Repos)
- [ ] **Evaluation**: Ragas oder LLM-Judge fuer Retrieval-Qualitaet (scalable-rag hat Eval-Setup)
- [ ] **Secrets**: JWT-Secrets und API-Keys aus Umgebungsvariablen (NICHT hardcoded wie in intelligent-rag)
- [ ] **DB Schema**: Alembic-Migrations fuer Chat-History etc. (scalable-rag hat KEINE Migrations)
- [ ] **Health Checks**: Alle Dependencies (Vector DB, LLM, Graph DB) pruefen
- [ ] **Graceful Degradation**: Was passiert wenn Neo4j down ist? Nur Vector Search nutzen.

---

## Anti-Patterns (aus den analysierten Repos)

| Anti-Pattern | Gefunden in | Konsequenz | Besser |
|-------------|-------------|------------|--------|
| In-memory-only Vector Store (FAISS) | intelligent-rag | Daten weg nach Restart | Qdrant/pgvector mit Persistenz |
| Hardcodiertes JWT Secret | intelligent-rag | Sicherheitsluecke | Env-Variable |
| python-jose (unmaintained) | scalable-rag | Keine Security-Patches | PyJWT oder joserfc |
| Neuer httpx Client pro Request | scalable-rag | Connection Overhead, Leaks | Shared AsyncClient |
| print() statt Logging | beide | Kein strukturiertes Log | structlog |
| Kein Chunking-Overlap | intelligent-rag | Info-Verlust an Grenzen | 10-20% Overlap |
| Keine Evaluation | intelligent-rag | Keine Qualitaetsmessung | Ragas + LLM Judge |
| LangGraph 0.0.21 | scalable-rag | Komplett veraltete API | Aktualisieren auf 0.3.x+ |
| datetime.utcnow() | beide | Deprecated seit Python 3.12 | datetime.now(UTC) |
| Doppelte Model-Definition | scalable-rag | Inkonsistenz-Risiko | Single Source of Truth |

---

## Architecture Decision Output Format

Wenn du eine RAG-Architektur empfiehlst, nutze dieses Format:

```
## RAG Architecture Recommendation

**Use Case:** [Was das System leisten soll]
**Scale:** [Erwartete Dokumente / Queries]

### Empfohlener Stack
- Vector DB: [Auswahl + Begruendung]
- Embedding Model: [Auswahl + Begruendung]
- LLM: [Auswahl + Begruendung]
- Retrieval Pattern: [Simple / Hybrid / Agentic]
- Caching: [Ja/Nein + Begruendung]

### Architektur-Diagramm
[ASCII oder Mermaid]

### Geschaetzte Kosten
- Embedding: [$/Monat]
- LLM: [$/Monat]
- Infrastruktur: [$/Monat]

### Risiken & Mitigationen
[Top 3]

### Erste Schritte
1. [Konkreter erster Schritt]
2. [Zweiter Schritt]
3. [Dritter Schritt]
```