Zurück zum Journal
•5 Min. Lesezeit

Pragmatisches RAG: Testen von Googles Open Knowledge Format (OKF)

Vektorsuche allein löst das Problem der Kontextzusammenstellung für KI-Agenten nicht. So habe ich die Dokumentation eines Repositories als navigierbaren Markdown-Graphen mit der OKF-Spezifikation strukturiert.

Google CloudAI AgentsRAGMarkdownOKFDocumentation
Pragmatisches RAG: Testen von Googles Open Knowledge Format (OKF)

Wenn Sie KI-Agenten in eine echte Codebasis integriert haben, sind Sie wahrscheinlich an die Grenzen der einfachen Vektorsuche gestoßen.

Sie bitten einen Agenten, einen API-Endpunkt zu refaktorieren, und er ruft den Funktionskörper über die Vektorsuche ab. Dabei fehlen jedoch das Datenbankschema, die Authentifizierungs-Middleware und das Bereitstellungs-Handbuch, da sie im Einbettungsraum nicht genügend semantische Überlappung aufwiesen.

Der Agent scheitert, weil er in einem Kontextvakuum arbeitet.

Um dieses Problem der „Kontextzusammenstellung“ zu lösen, hat Google Cloud die Open Knowledge Format (OKF) Spezifikation veröffentlicht. Es ist ein herstellerneutraler Standard, um ein Verzeichnis von Textdateien in einen semantischen Wissensgraphen umzuwandeln, den KI-Agenten rekursiv navigieren können.

Hier ist meine praktische Erfahrung mit der Implementierung.

Reale Implementierung: OKF in diesem Portfolio

Anstatt nur das Konzept zu erklären, habe ich OKF in der gesamten Dokumentation dieses Portfolios implementiert. Sie können die tatsächliche Wissensdatenbank im Verzeichnis /knowledge/ dieses Repositories erkunden.

OKF formalisiert, was viele Plattformteams bereits getan haben: Die Strukturierung der internen Dokumentation als sauberer Verzeichnisbaum aus einfachen Markdown-Dateien mit YAML-Frontmatter.

Anstatt proprietäre Graphdatenbanken oder komplexe Vektorindizierungs-Pipelines einzuführen, stützt sich OKF auf zwei Webstandards:

  1. YAML-Frontmatter für Metadaten auf Dateiebene (Deklaration, was eine Datei ist).
  2. Standard-Markdown-Links, um Beziehungen zwischen Dateien zu deklarieren (Verweis des Agenten auf den nächsten Knoten).

Indem Sie Dateien direkt im Text verlinken, verwandeln Sie Ihr Dokumentationsverzeichnis in einen Wissensgraphen. Jeder LLM-Agent, der eine Datei analysiert, kann diesen Links genau wie ein Webcrawler folgen, der HTML-Anker durchläuft.

Tatsächliche Implementierung in diesem Portfolio

Dieses Portfolio implementiert OKF im Verzeichnis /knowledge/. Hier ist die tatsächliche Struktur:

TEXT
/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

Jede Datei beginnt mit einem ordnungsgemäßen OKF-Frontmatter. Hier ist der tatsächliche YAML-Header aus /knowledge/index.md:

YAML
---
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"]
---

Der Inhalt enthält explizite Beziehungen zwischen den Dokumenten. In journal-publishing.md finden Sie beispielsweise:

MARKDOWN
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).

Dies schafft einen navigierbaren Graphen, den sowohl Menschen als auch KI-Agenten effektiv durchlaufen können.

Wie Agenten diesen tatsächlichen Graphen durchlaufen

Traditionelles RAG sucht nach Schlüsselwörtern oder Vektoren, ruft die besten 5 Abschnitte ab und fügt sie in den Prompt ein.

OKF ermöglicht eine traversierende RAG-Strategie:

  1. Auswahl des Einstiegspunkts: Der Agent führt eine leichtgewichtige Vektorsuche oder Keyword-Abfrage durch, um das erste relevante Dokument zu finden (z. B. journal-publishing.md).
  2. Rekursives Parsen: Der Agent analysiert das Dokument, liest den YAML-Header, um den Dokumenttyp zu identifizieren, und extrahiert alle relativen Links.
  3. Kontextzusammenstellung: Je nach Aufgabe lädt der Agent die verlinkten Dateien rekursiv, um einen vollständigen Kontext aufzubauen.

Wenn ein Agent beispielsweise verstehen müsste, wie Blog-Beiträge in diesem Portfolio validiert werden, könnte er:

  1. Mit journal-publishing.md beginnen (über die Suche gefunden)
  2. Dem Link zu ../architecture/directory-layout.md folgen, um die Struktur der Codebasis zu verstehen
  3. Validierungsskripte in der Architektur-Dokumentation entdecken
  4. Zugehörige Richtlinien wie blog-validation-tools.md für Implementierungsdetails laden

Dies verhindert einen Überlauf des Kontextfensters, da der Agent nur Dateien lädt, die explizit relevant sind, wodurch das Rauschen der generischen Suche vollständig umgangen wird.

Automatisierte Validierung

Um sicherzustellen, dass die OKF-Struktur intakt bleibt, habe ich eine automatisierte Validierung implementiert:

  • Ein Skript prüft, ob alle Markdown-Dateien ein ordnungsgemäßes Frontmatter haben
  • Validiert erforderliche Felder (type, title, description, timestamp)
  • Stellt sicher, dass die Indexdatei mit type: "index" existiert
  • Warnt vor Dateien ohne relative Links (potenziell isolierte Knoten)

Diese Validierung wird automatisch während des Build-Prozesses ausgeführt und verhindert die Bereitstellung fehlerhafter oder fehlerhaft formatierter Dokumentation.

Reale Ergebnisse: Lohnt sich OKF?

Nach der Implementierung von OKF in dieser tatsächlichen Codebasis ist hier meine ehrliche Einschätzung basierend auf echter Erfahrung:

Die Vorteile:

  • Kein Vendor-Lock-in: Es ist nur Markdown. Sie können es in VS Code anzeigen, auf GitHub hosten oder mit jedem LLM-Anbieter indizieren.
  • Git-kompatible Versionierung: Dokumentationsaktualisierungen erfolgen über Standard-Pull-Requests und Merge-Reviews.
  • Agenten-Unabhängigkeit: Agenten benötigen keine benutzerdefinierten Datenbanktreiber; sie benötigen lediglich einen Markdown-Parser.
  • Entwicklererfahrung: Entwickler können sich in der Dokumentation auf dieselbe Weise bewegen wie im Code – indem sie expliziten Links folgen.

Die gelösten Herausforderungen:

  • Kaputte Links: Unsere automatisierte Validierung fängt kaputte Links während des Build-Prozesses ab.
  • Wartungsaufwand: Die Validierungsskripte stellen sicher, dass neue Dokumente automatisch den OKF-Konventionen folgen.

In der Praxis hat OKF die Dokumentation dieses Portfolios sowohl für Menschen als auch für KI-Agenten erheblich navigierbarer gemacht. Wenn ich Fragen zur Struktur der Codebasis stelle, können Agenten nun expliziten Links folgen, um einen vollständigen Kontext aufzubauen, anstatt zu raten, welche Dokumente relevant sein könnten.

OKF ist ein pragmatischer Ansatz zur Kontextzusammenstellung. Wenn Sie mit Halluzinationen oder unvollständigem Agentenkontext kämpfen, ist die Strukturierung des /docs- oder /knowledge-Verzeichnisses Ihres Repositories gemäß OKF eine kostengünstige Architektur-Entscheidung mit hohem Nutzen.

Share this article