Markdown voor RAG: documenten slim opdelen in chunks

RAG staat voor Retrieval-Augmented Generation. Het idee: in plaats van alles wat je weet in de prompt te stoppen, zoekt je systeem eerst de relevante stukken tekst op in een kennisbank en geeft alleen die aan het taalmodel. Dat werkt met een vector store of een andere zoekindex. De documenten in die kennisbank zijn opgedeeld in kleine stukken: chunks.

Het opdelen klinkt als een technisch detail, maar het is een van de belangrijkste factoren voor de kwaliteit van je antwoorden. Een chunk die midden in een zin begint, of een tabel die in tweeën is geknipt, levert een zoekresultaat op dat het model op het verkeerde been zet.

Waarom Markdown de beste basis is

Om slim te kunnen opdelen, moet je weten waar een onderwerp begint en eindigt. In een PDF weet je dat niet: er is alleen tekst op posities. In Word is de structuur er wel, maar verstopt in opmaakcodes. Markdown maakt de structuur zichtbaar en eenvoudig te verwerken:

• #, ## en ### markeren secties en subsecties;
• lege regels scheiden alinea's;
• lijsten en tabellen hebben een herkenbare vorm;
• codeblokken staan tussen vaste tekens.

Daarmee kun je opdelen op betekenis in plaats van op lengte. Veel RAG-frameworks hebben er daarom aparte Markdown-splitters voor, die op koppen knippen. De eerste stap is dus altijd: zet je documenten om naar schone Markdown. Met PDF naar Markdown omzetten en Excel naar Markdown omzetten heb je die basis snel. Voor grote aantallen kun je de Python-bibliotheek gebruiken, zoals beschreven in Markdown omzetten in de browser of met Python.

Vier manieren om op te delen

In de praktijk werkt de hiërarchische aanpak het vaakst het best: eerst op koppen, en secties die te lang zijn daarna verder op alinea's.

Een voorbeeld

Neem een stuk uit een handboek van een zorginstelling in Gelderland:

# Handboek Thuiszorg 2026

## Medicatie
### Medicatie aanreiken
Controleer naam, geboortedatum en de toedienlijst...

### Medicatiefouten melden
Meld elke fout binnen 24 uur via het MIC-formulier...

## Hygiëne
### Handhygiëne
Was je handen voor en na elk cliëntcontact...

Bij opdelen op koppen krijg je drie chunks: 'Medicatie aanreiken', 'Medicatiefouten melden' en 'Handhygiëne'. Zoekt een medewerker 'hoe meld ik een fout met medicijnen?', dan vindt het systeem precies de juiste sectie. Bij knippen op vaste lengte had de helft van die sectie misschien bij 'Medicatie aanreiken' gezeten.

Geef elke chunk zijn context mee

Een losse chunk mist vaak context. 'Meld elke fout binnen 24 uur' zegt weinig als je niet weet dat het over medicatie in de thuiszorg gaat. Twee technieken helpen:

1. Kopregel-pad toevoegen. Zet boven elke chunk het pad van koppen: Handboek Thuiszorg 2026 > Medicatie > Medicatiefouten melden. Dat verbetert zowel het zoeken als het antwoord.
2. Metadata opslaan. Bewaar per chunk de documentnaam, de versie of datum en eventueel een categorie. Dan kun je filteren, bijvoorbeeld alleen documenten van 2026, en kan het model de bron noemen.

Hoe groot moet een chunk zijn?

Een universeel juist getal bestaat niet. Het hangt af van je documenten, het embeddingmodel en het soort vragen. Een paar vuistregels:

• Te klein en een chunk mist context. Een losse zin over een termijn zonder te zeggen waar die termijn over gaat, helpt niemand.
• Te groot en een chunk gaat over meerdere onderwerpen. De embedding wordt dan een gemiddelde, en zoeken wordt minder precies. Bovendien gaat er meer ruimte in de prompt verloren aan tekst die niet relevant is.
• Veel teams starten ergens tussen een paar honderd en ongeveer duizend tokens, en stellen bij op basis van tests.

Tel tokens met dezelfde tokenizer als je model, of in ieder geval een vergelijkbare. Onze converters tonen bij elk resultaat een schatting van het aantal tokens, zodat je een gevoel krijgt voor de omvang van je secties.

Overlap: wel of niet?

Bij knippen op vaste lengte wordt vaak overlap gebruikt: elke chunk begint met de laatste zinnen van de vorige. Zo gaat informatie op de grens niet verloren. Bij opdelen op koppen is dat minder nodig, omdat een sectie al een afgerond geheel is. Gebruik je de hiërarchische aanpak, dan kun je overlap alleen toepassen bij secties die je verder opdeelt.

Tabellen en lijsten heel houden

Tabellen zijn het lastigst. Een prijstabel van een webwinkel die halverwege wordt doorgeknipt, levert een tweede chunk op met getallen zonder kolomnamen. Regels:

• Knip nooit midden in een tabel als dat te voorkomen is.
• Is een tabel te groot, deel hem dan op per groep rijen en herhaal de kopregel in elk deel.
• Overweeg om tabelrijen ook als zin op te slaan: 'Volkorenbrood kost € 3,10 en is op voorraad'. Sommige zoekmodellen vinden dat makkelijker.
• Houd een opsomming bij de zin die hem inleidt.

Wil je tabellen eerst opschonen of opnieuw opbouwen, dan helpt de Markdown-tabel generator.

Schoonmaken voor je opdeelt

Opdelen kan geen rommel repareren. Haal vooraf weg wat geen inhoud is:

• herhaalde kop- en voetteksten en paginanummers;
• inhoudsopgaven en registers;
• juridische standaardteksten die in elk document terugkomen;
• lege koppen en losse afbeeldingsverwijzingen.

Doe je dat niet, dan duiken die stukken op als zoekresultaat en verdringen ze de echte antwoorden.

Checklist

Testen, testen, testen

De enige manier om te weten of je chunking werkt, is meten. Stel een lijst op van twintig tot vijftig vragen met het bijbehorende juiste document en de juiste sectie. Kijk of je systeem die sectie bij de eerste paar resultaten vindt. Verander dan één ding tegelijk, bijvoorbeeld de chunkgrootte of het toevoegen van koppen, en meet opnieuw.

Metadata: meer dan alleen tekst

Een chunk is meer dan een stukje tekst. In de meeste vectordatabases sla je naast de tekst ook metadata op: velden waarop je kunt filteren of die je meestuurt aan het taalmodel. Met Markdown als basis haal je die metadata vaak gewoon uit de structuur.

Een voorbeeld: een zorginstelling in Zeeland zet haar protocollen in een RAG-systeem. Elk protocol krijgt in de frontmatter een versie en een ingangsdatum. Bij het ophalen filtert het systeem eerst op de nieuwste versie en zoekt pas daarna op inhoud. Zo kan een verouderd protocol nooit de bron van een antwoord zijn, hoe goed de tekst ook bij de vraag past.

Het omzetten zelf doe je met Word naar Markdown of PDF naar Markdown; de koppen die daarbij uit het origineel komen, vormen meteen je kop-pad. Controleer na het omzetten of de kopniveaus kloppen. Een hoofdstuk dat als ### binnenkomt in plaats van ##, belandt anders onder het verkeerde kop-pad.

Samengevat

Goede RAG begint bij goede chunks, en goede chunks beginnen bij Markdown. Zet je documenten om, maak ze schoon, deel ze op langs de koppen, geef elke chunk zijn context en metadata mee en houd tabellen heel. Kies de chunkgrootte niet op gevoel maar op basis van tests met je eigen vragen.