RAG mit Markdown-Chunks: Best Practices für Vector Stores

Retrieval-Augmented Generation (RAG) ist das Standard-Pattern, um Sprachmodelle mit eigenem Wissen zu versorgen. Das Setup klingt simpel: Dokumente in Chunks zerlegen, in einen Vector Store laden, bei Anfragen die relevantesten Chunks finden, als Kontext ans LLM schicken. In der Praxis entscheidet aber die Qualität der Chunks darüber, ob dein RAG-System brauchbare Antworten liefert oder Halluzinationen produziert. Markdown ist dabei das ideale Eingabeformat, aber nur wenn du es richtig aufbereitest.

Warum Markdown für RAG besser ist als Plain Text

Plain Text kennt keine Struktur. Wenn du ein PDF einfach als Fließtext extrahierst und in 500-Zeichen-Chunks schneidest, zerteilst du Sätze mitten in Argumenten, mischst Themen, verlierst Hierarchie. Markdown gibt dir explizite Strukturmarker, die du beim Chunking nutzen kannst.

Konkret hat Markdown drei Vorteile für RAG:

Erstens, Heading-basiertes Chunking. Du kannst Dokumente entlang ihrer H2- oder H3-Sektionen splitten. Jeder Chunk ist dann semantisch zusammenhängend, weil er einen Themenabschnitt komplett abdeckt.

Zweitens, Erhalt von Listen und Tabellen. In Plain Text wird eine Tabelle zu einer chaotischen Zeichenfolge. In Markdown bleibt sie strukturiert, das Embedding-Modell erkennt sie als Tabelle, der Retrieval-Score wird besser.

Drittens, Metadaten-Tagging. Du kannst Markdown-Frontmatter (YAML am Dateianfang) oder strukturierte Header nutzen, um pro Chunk Metadaten zu extrahieren: Quelle, Datum, Autor, Themenbereich. Diese Metadaten landen im Vector Store und ermöglichen gefilterte Suchen.

RAG-Performance hängt zu ungefähr 70 Prozent von der Datenaufbereitung ab, nur 30 Prozent vom verwendeten Embedding-Modell. Wer mehr Qualität will, sollte zuerst in saubere Chunks investieren, nicht in größere Modelle.

Die richtige Chunk-Größe

Es gibt keine universell richtige Chunk-Größe. Sie hängt von deinen Dokumenten, deinem Anwendungsfall und dem Embedding-Modell ab. Aber es gibt belastbare Faustregeln.

Sehr kleine Chunks (100 bis 300 Tokens). Gut für Faktendatenbanken, kurze FAQs, Definitions-Suchen. Schlecht für komplexe Argumentationen, weil Zusammenhang verloren geht.

Mittlere Chunks (500 bis 1.000 Tokens). Der Sweet Spot für die meisten Anwendungsfälle. Genug Kontext für sinnvolle Argumente, klein genug für präzise Retrieval-Treffer.

Große Chunks (1.500 bis 3.000 Tokens). Sinnvoll für narrative Inhalte wie ganze Kapitel oder Berichte. Risiko: das Embedding wird "verwässert", weil ein Chunk mehrere Themen enthält. Retrieval-Präzision sinkt.

Sehr große Chunks (5.000+ Tokens). Meist suboptimal, weil ein Chunk dann mehrere unzusammenhängende Themen vermischt. Ausnahme: wenn du nur Top-1-Retrieval willst und das LLM mit großem Kontextfenster arbeitet.

Dokumenttyp	Empfohlene Chunk-Größe
FAQ-Datenbank	200 bis 500 Tokens
Produktdokumentation	500 bis 1.000 Tokens
Wissenschaftliche Paper	800 bis 1.500 Tokens
Verträge, juristische Texte	1.000 bis 2.000 Tokens
Narrative Berichte	1.500 bis 2.500 Tokens

Wenn du nicht weißt, womit du anfangen sollst, starte mit 800 Tokens und 100 Token Overlap. Teste mit zehn typischen Suchanfragen, justiere von dort.

Chunk-Overlap richtig einsetzen

Overlap bedeutet, dass aufeinanderfolgende Chunks sich teilweise überschneiden. Wenn ein Argument am Chunk-Ende beginnt und im nächsten Chunk weitergeht, bleibt der Zusammenhang erhalten.

Empfehlung in der Praxis: 10 bis 20 Prozent der Chunk-Größe als Overlap. Bei 800-Token-Chunks also 80 bis 160 Tokens Overlap.

Warum nicht mehr? Höherer Overlap bläht den Vector Store auf und produziert mehr redundante Treffer im Retrieval. Bei 50 Prozent Overlap kann ein Suchergebnis dreimal denselben Inhalt liefern.

Warum nicht weniger? Ohne Overlap reißen Sätze und Argumente an Chunk-Grenzen ab. Der entsprechende Chunk wird im Retrieval schlecht bewertet, weil ihm der Kontext fehlt.

Heading-basiertes Chunking

Die intelligenteste Chunk-Strategie für Markdown ist heading-basiert. Statt fix bei 800 Tokens zu schneiden, schneidest du an Markdown-Headings.

Vorgehensweise:

Parse die Markdown-Datei und identifiziere alle H1, H2, H3.
Jeder Chunk beginnt bei einem Heading und endet beim nächsten Heading derselben oder höheren Ebene.
Wenn ein Chunk zu groß wird (über 2.000 Tokens), splitte ihn an H3-Headings oder an Absatzgrenzen weiter.
Wenn ein Chunk zu klein wird (unter 200 Tokens), fasse ihn mit dem nächsten zusammen.

Dieser Ansatz produziert semantisch saubere Chunks, weil jeder einen vollständigen Themenabschnitt umfasst.

import re

def chunk_by_headings(markdown_text, min_tokens=200, max_tokens=1500):
    sections = re.split(r'^(#{1,3} .+)#x27;, markdown_text, flags=re.MULTILINE)
    chunks = []
    current_chunk = ""
    
    for i in range(0, len(sections), 2):
        heading = sections[i+1] if i+1 < len(sections) else ""
        content = sections[i] if i > 0 else ""
        
        section = heading + "\n" + content
        token_count = len(section.split()) * 1.3
        
        if token_count < min_tokens and current_chunk:
            current_chunk += "\n\n" + section
        elif token_count > max_tokens:
            chunks.extend(split_by_paragraphs(section, max_tokens))
        else:
            if current_chunk:
                chunks.append(current_chunk)
            current_chunk = section
    
    if current_chunk:
        chunks.append(current_chunk)
    
    return chunks

Das ist eine vereinfachte Version, in Production-Code würdest du einen echten Tokenizer wie tiktoken nutzen statt der Word-Count-Approximation.

Metadaten an Chunks anhängen

Jeder Chunk im Vector Store sollte Metadaten haben. Diese ermöglichen gefilterte Suchen ("nur Chunks aus dem Handbuch 2024, nur Sektionen zum Thema API") und verbessern die Retrieval-Präzision deutlich.

Sinnvolle Metadaten pro Chunk:

source: Dateiname oder Pfad des Quelldokuments
section: H2-Überschrift des Chunks
parent_section: H1, falls H2 in größerer Struktur liegt
date: Datum des Dokuments oder letztes Update
category: Themenkategorie (manuell oder automatisch klassifiziert)
chunk_position: Reihenfolge innerhalb des Dokuments (1, 2, 3, ...)

Wenn du Markdown mit Frontmatter nutzt, kannst du diese Metadaten direkt aus dem Dokument lesen:

---
source: produkthandbuch-v3.md
category: API-Dokumentation
last_updated: 2026-04-15
author: Adriano Caruso
---

# API-Authentifizierung

Inhalte hier...

Die Frontmatter wird beim Chunking ignoriert (nicht als Inhalt eingebettet), aber als Metadaten pro Chunk gespeichert.

Investiere fünf Minuten pro Quelldokument in saubere Metadaten. Diese Investition zahlt sich beim Retrieval um den Faktor zehn aus, weil du gezielt filtern kannst.

Embedding-Strategie

Das Embedding-Modell verwandelt deinen Chunk in einen hochdimensionalen Vektor. Die Wahl des Modells beeinflusst die Retrieval-Qualität, aber weniger als oft angenommen.

Bewährte Modelle 2026:

OpenAI text-embedding-3-large (3072 Dimensionen). Sehr gut, vor allem für englische und gemischtsprachige Inhalte. Hoher Speicherbedarf wegen großer Dimension.

OpenAI text-embedding-3-small (1536 Dimensionen). Ausgewogen, deutlich günstiger als large, für die meisten Anwendungsfälle ausreichend. Mein Standard-Empfehlung für Einsteiger.

Cohere embed-multilingual-v3 (1024 Dimensionen). Stark bei mehrsprachigen Inhalten, vor allem für deutsche Quelldokumente.

Voyage AI voyage-3 (1024 Dimensionen). Sehr gut, auch für lange Kontexte, oft besser als OpenAI bei technischen Inhalten.

Sentence-Transformers (all-MiniLM-L6-v2, 384 Dimensionen). Open Source, kostenlos, lokal lauffähig. Qualitativ schwächer als die kommerziellen, aber für DSGVO-kritische Setups oft die einzige Option.

Wenn du mit mehrsprachigen Quelldokumenten arbeitest, prüfe vor der Wahl, wie das Embedding-Modell mit deinen Sprachen umgeht. Manche Modelle sind stark im Englischen aber schwach im Deutschen.

Praktischer Workflow zum Nachmachen

Ein typischer RAG-Setup-Workflow für ein neues Projekt:

Quelldokumente sammeln. PDFs, Word-Dateien, Excel-Sheets, alles was relevant ist.
Zu Markdown konvertieren. Mit MarkItDown im Browser oder per Python-Library für Batches.
Frontmatter ergänzen. Pro Dokument fünf bis zehn Zeilen YAML-Metadaten am Anfang.
Heading-basiert chunken. Mit Chunk-Größe 600 bis 1.000 Tokens und 10 Prozent Overlap.
Embeddings generieren. Mit text-embedding-3-small oder vergleichbarem Modell.
In Vector Store laden. Beliebter: Pinecone, Weaviate, Qdrant, ChromaDB.
Mit zehn typischen Suchanfragen testen. Prüfen, ob Retrieval die richtigen Chunks findet.
Iterativ anpassen. Wenn Suchergebnisse schlecht sind, an Chunk-Größe, Overlap oder Metadaten justieren.

Die meisten RAG-Probleme entstehen in Schritt vier und sieben. Wenn du dort Disziplin walten lässt, ist 80 Prozent der Arbeit getan.

Häufige Fehler

Fehler eins, zu große Chunks aus Bequemlichkeit. "Ich nehme das ganze Kapitel als einen Chunk" klingt einfach, killt aber die Retrieval-Präzision. Bleib bei 500 bis 1.500 Tokens.

Fehler zwei, keine Metadaten. Ohne Metadaten kannst du nicht filtern. Bei 10.000 Chunks ohne Filter wird Retrieval ungenauer als bei 1.000 Chunks mit guten Filtern.

Fehler drei, Originalformate statt Markdown. Wenn du PDFs direkt parst, verlierst du Struktur. Konvertiere zu Markdown, dann erst chunken.

Fehler vier, ein einziges Embedding-Modell für alles. Wenn du sowohl technische Dokumentation als auch Marketing-Texte hast, performt ein einziges Modell vielleicht nicht optimal für beide. Erwäge separate Embeddings pro Dokumenttyp.

Fehler fünf, nie reembedden. Embedding-Modelle entwickeln sich weiter. Wenn dein Vector Store zwei Jahre alt ist, mit dem nächsten Modell-Update solltest du komplett reembedden. Das kostet Geld, lohnt sich aber.

Fehler sechs, kein Hybrid Search. Reine Vektor-Suche verliert bei exakten Begriffen (Produktnamen, Codes, IDs). Hybrid Search kombiniert Vektor-Suche mit klassischer BM25-Suche und ist in 90 Prozent der Fälle besser als reine Vektor-Suche.

Fazit

RAG-Qualität entsteht durch die Datenaufbereitung, nicht durch das Embedding-Modell allein. Sauberes Markdown als Eingabeformat, heading-basiertes Chunking, gute Metadaten und eine bewusste Chunk-Größe sind die vier Hebel mit dem größten Effekt. Wenn du diese vier Punkte konsequent umsetzt, schlägt dein RAG-System auch mit kostenlosen Embedding-Modellen ein schlecht aufgebautes System mit Premium-Embeddings.

Weiterführend

MarkItDown direkt nutzen für die Konvertierung deiner Quelldokumente
PDF zu Markdown konvertieren für PDF-spezifische Konvertierung
Was ist Markdown?, wenn du den Grundlagen-Guide noch nicht gelesen hast
Claude Projects mit Dokumenten füttern, als RAG-Alternative für kleinere Setups