Pragmatische RAG: Google's Open Knowledge Format (OKF) testen

Als u AI-agenten in een echte codebase hebt geïntegreerd, bent u waarschijnlijk tegen de beperkingen van naïef zoeken naar vectoren aangelopen.

U vraagt een agent om een API-eindpunt te refactoren en deze haalt het functielichaam op via vectorzoekopdracht. Maar het mist het databaseschema, de authenticatie-middleware en het implementatiehandboek, omdat ze niet genoeg semantische overlap deelden.

De agent faalt omdat deze in een contextvacuüm werkt.

Om dit probleem van "contextassemblage" op te lossen, heeft Google Cloud de Open Knowledge Format (OKF) specificatie gepubliceerd. Het is een leveranciersneutrale standaard om een map met tekstbestanden om te zetten in een semantische kennisgraaf die AI-agenten recursief kunnen navigeren.

Hier is mijn praktische ervaring met de implementatie ervan.

Echte implementatie: OKF in dit portfolio

In plaats van alleen het concept uit te leggen, heb ik OKF geïmplementeerd in de gehele documentatie van dit portfolio. U kunt de daadwerkelijke kennisbank verkennen in de map /knowledge/ in deze repository.

OKF formaliseert wat veel platformteams al deden: het structureren van interne documentatie als een schone directoryboom van gewone Markdown-bestanden met YAML-frontmatter.

In plaats van eigen grafische databases of complexe vectorindelingspipelines te introduceren, vertrouwt OKF op twee webstandaarden:

1. YAML Frontmatter voor metagegevens op bestandsniveau (om aan te geven wat een bestand is).
2. Standaard Markdown-links om relaties tussen bestanden aan te geven (om de agent naar de volgende node te verwijzen).

Door bestanden rechtstreeks in de tekst te linken, verandert u uw documentatiemap in een kennisgraaf. Elke LLM-agent die een bestand analyseert, kan deze links volgen, net zoals een webcrawler HTML-ankers doorloopt.

Daadwerkelijke implementatie in dit portfolio

Dit portfolio implementeert OKF in de map /knowledge/. Hier is de daadwerkelijke structuur:

/knowledge/
  ├── index.md                    <-- Entry point with type: "index"
  ├── architecture/
  │   └── directory-layout.md     <-- Architecture documentation
  ├── guidelines/
  │   ├── journal-publishing.md   <-- Blog publishing guidelines
  │   ├── cover-art.md            <-- Cover art guidelines
  │   └── ...                     <-- Additional guidelines

Elk bestand begint met een juiste OKF-frontmatter. Hier is de daadwerkelijke YAML-header van /knowledge/index.md:

---
type: "index"
title: "dds.com Codebase Knowledge Base"
description: "Entry point for Google OKF-compliant repository knowledge graph describing layout and journal workflows."
timestamp: "2026-07-06T13:10:00Z"
tags: ["OKF", "documentation", "architecture", "guidelines"]
---

De inhoud bevat expliciete relaties tussen de documenten. In journal-publishing.md vindt u bijvoorbeeld:

For information on creating cover art for your posts, see the [Cover Art Guidelines](./cover-art.md). For an overview of the entire codebase architecture, refer to the [Directory Layout](../architecture/directory-layout.md).

Dit creëert een navigeerbare graaf die zowel mensen als AI-agenten effectief kunnen doorlopen.

Hoe agenten deze daadwerkelijke graaf doorlopen

Traditionele RAG zoekt naar trefwoorden of semantische vectoren, haalt de top 5 chunks op en dumpt ze in de prompt.

OKF maakt een traversale RAG-strategie mogelijk:

1. Selectie van het toegangspunt: De agent voert een lichtgewicht vectorzoekopdracht of trefwoordquery uit om het initiële relevante document te vinden (bijv. journal-publishing.md).
2. Recursieve parsing: De agent parseert het document, leest de YAML-header om het documenttype te identificeren en extraheert alle relatieve links.
3. Contextassemblage: Afhankelijk van de taak laadt de agent recursief de gekoppelde bestanden om een volledige context op te bouwen.

Als een agent bijvoorbeeld moet begrijpen hoe blogposts in dit portfolio worden gevalideerd, kan hij:

1. Beginnen met journal-publishing.md (gevonden via zoeken)
2. De link naar ../architecture/directory-layout.md volgen om de structuur van de codebase te begrijpen
3. Validatiescripts ontdekken in de architectuurdocumentatie
4. Gerelateerde richtlijnen laden, zoals blog-validation-tools.md, voor implementatiedetails

Dit voorkomt overloop van het contextvenster omdat de agent alleen bestanden ophaalt die expliciet relevant zijn, waardoor de ruis van algemene zoekopdrachten volledig wordt omzeild.

Geautomatiseerde validatie

Om ervoor te zorgen dat de OKF-structuur intact blijft, heb ik geautomatiseerde validatie geïmplementeerd:

• Een script controleert of alle markdown-bestanden de juiste frontmatter hebben
• Valideert vereiste velden (type, title, description, timestamp)
• Zorgt ervoor dat het indexbestand bestaat met type: "index"
• Waarschuwt over bestanden zonder relatieve links (mogelijk losgekoppelde nodes)

Deze validatie wordt automatisch uitgevoerd tijdens het bouwproces, waardoor wordt voorkomen dat kapotte of misvormde documentatie wordt geïmplementeerd.

Resultaten in de praktijk: is OKF het waard?

Nu ik OKF in deze daadwerkelijke codebase heb geïmplementeerd, is hier mijn eerlijke beoordeling op basis van echte ervaring:

De voordelen:

• Geen vendor lock-in: Het is gewoon Markdown. U kunt het bekijken in VS Code, hosten op GitHub of indexeren met elke LLM-provider.
• Git-compatibele versiebeheer: Documentatie-updates verlopen via standaard Pull Requests en merge-beoordelingen.
• Agentonafhankelijkheid: Agenten hebben geen aangepaste databasedrivers nodig; ze hebben alleen een markdown-parser nodig.
• Ontwikkelaarservaring: Engineers kunnen op dezelfde manier door documentatie navigeren als door code - door expliciete links te volgen.

De opgeloste uitdagingen:

• Linkrot: Onze geautomatiseerde validatie detecteert gebroken links tijdens het bouwproces.
• Onderhoudsoverhead: De validatiescripts zorgen ervoor dat nieuwe documentatie automatisch de OKF-conventies volgt.

In de praktijk heeft OKF de documentatie van dit portfolio veel navigeerbaarder gemaakt voor zowel mensen als AI-agenten. Wanneer ik vragen stel over de structuur van de codebase, kunnen agenten nu expliciete links volgen om een volledige context op te bouwen in plaats van te raden welke documenten relevant kunnen zijn.

OKF is een pragmatische aanpak voor contextassemblage. Als u worstelt met hallucinaties of een onvolledige agentcontext, is het structureren van de map /docs of /knowledge van uw repository om overeen te komen met OKF een goedkope architectuurbeslissing met een hoog rendement.