Slimme documentatiedatabases bouwen voor je AI-codeassistent

Ruwe documentatie rechtstreeks in een AI-agent stoppen is zelden een goed idee. Veel pagina’s bevatten geen echte inhoud, maar dienen vooral als navigatie of juridische verplichting. Daardoor raakt de agent afgeleid en worden antwoorden minder accuraat.

Niet elke pagina is even waardevol

Technische sites bevatten vaak indexpagina’s, privacyverklaringen en changelogs. Voor mensen zijn die nuttig, maar voor een AI die patronen moet leren zijn ze ballast. Stop je alles ongefilterd in een vectorstore, dan krijg je tragere queries en meer irrelevante verwijzingen.

Twee stappen om te filteren

Een efficiënte aanpak combineert simpele regels met een lichte LLM-classificatie.

Eerste ronde: automatische regels
Kijk eerst naar URL-patronen en paginalengte.

• Juridische pagina’s herken je aan paden als /legal/ of /privacy.
• Navigatiehubs hebben vaak minder dan 200 woorden en bestaan vooral uit links.
• Changelogs en referentielijsten volgen meestal een vast URL-schema.

Dit deel draait lokaal, kost niets en verwijdert 40 tot 60 procent van de ruis.

Tweede ronde: LLM-classificatie
Voor de resterende pagina’s stuur je een klein pakketje naar een lokaal model: URL, titel, eerste 200 woorden en de koppenstructuur. Vraag het model om de pagina te labelen volgens het Diátaxis-raamwerk: conceptueel, tutorial, how-to, voorbeeld of structureel. Alleen de twijfelgevallen komen hierlangs, dus de kosten blijven laag.

Slim embedden zonder tokens te verspillen

Na het schonen kun je pagina’s embedden. Veel documentatie is te lang voor één embedding. Splits daarom op koppen en gemiddelde de vectoren. Zo behoud je context van codeblokken en lijsten. Gebruik een lokaal sentence-transformer-model; dat is snel en voldoet prima voor technische teksten.

Een hybride kennisgraaf

Koppel twee soorten relaties:

• Expliciete links die auteurs zelf hebben geplaatst.
• Semantische verbindingen op basis van cosine similarity (drempel 0,75).

Bewaar beide als gerichte edges in een graaf. Beperk het aantal buren per pagina tot ongeveer twintig, zodat er geen reusachtige knooppunten ontstaan. Navigatie- en juridische pagina’s laat je buiten de semantische laag.

Alles in één SQLite-database

Het eindresultaat is een compacte SQLite-file met:

• Schone markdown per pagina
• Classificatielabels
• Embeddings
• Graph edges met gewichten
• Metadata

De database is draagbaar, offline te gebruiken en direct bevraagbaar met SQL. AI-agenten kunnen filters toepassen (“alle tutorials over authenticatie”) of door de graaf navigeren.

De praktische pijplijn

1. Crawl de site met respect voor robots.txt.
2. Zet HTML om naar markdown.
3. Classificeer met regels en LLM.
4. Maak embeddings via heading-splitsing.
5. Bouw de graaf.
6. Schrijf alles weg naar SQLite.

Wat levert het op?

Je AI werkt met gerichte, gestructureerde kennis in plaats van een hoop ruis. Queries worden sneller, antwoorden relevanter en je houdt volledige controle over je eigen data. Geen API-kosten, geen privacyrisico’s en schaalbaar van kleine tot grote documentatiesites.