RAG pragmatico: testare l'Open Knowledge Format (OKF) di Google

Se avete integrato agenti IA in una codebase reale, avrete probabilmente riscontrato i limiti della semplice ricerca vettoriale.

Chiedete a un agente di rifattorizzare un endpoint API ed esso recupera il corpo della funzione tramite ricerca vettoriale. Tuttavia, mancano lo schema del database, il middleware di autenticazione e il manuale di distribuzione perché non condividevano abbastanza sovrapposizione semantica nello spazio di embedding.

L'agente fallisce perché opera in un vuoto di contesto.

Per risolvere questo problema di "assemblaggio del contesto", Google Cloud ha pubblicato la specifica Open Knowledge Format (OKF). Si tratta di uno standard indipendente dal fornitore per convertire una directory di file di testo in un grafo di conoscenza semantica che gli agenti IA possono esplorare in modo ricorsivo.

Ecco la mia esperienza pratica con l'implementazione.

Implementazione nel mondo reale: OKF in questo portfolio

Invece di spiegare semplicemente il concetto, ho implementato OKF in tutta la documentazione di questo portfolio. È possibile esplorare la base di conoscenza reale nella directory /knowledge/ di questo repository.

L'OKF formalizza ciò che molti team di piattaforma stavano già facendo: strutturare la documentazione interna come un albero pulito di directory di file Markdown con frontmatter YAML.

Invece di introdurre database a grafo proprietari o pipeline di indicizzazione vettoriale complesse, l'OKF si basa su due standard web:

1. Frontmatter YAML per i metadati a livello di file (dichiarando cosa sia un file).
2. Collegamenti Markdown standard per dichiarare le relazioni tra i file (indirizzando l'agente al nodo successivo).

Collegando i file direttamente all'interno del testo, si trasforma la directory della documentazione in un grafo di conoscenza. Qualsiasi agente LLM che analizza un file può seguire questi collegamenti esattamente come un web crawler attraversa le ancore HTML.

Implementazione effettiva in questo portfolio

Questo portfolio implementa OKF nella directory /knowledge/. Ecco la struttura reale:

/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

Ogni file inizia con un frontmatter OKF appropriato. Ecco l'intestazione YAML reale da /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"]
---

Il contenuto include relazioni esplicite tra i documenti. Ad esempio, in journal-publishing.md, troverai:

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

Questo crea un grafo navigabile che sia gli umani che gli agenti IA possono percorrere efficacemente.

Come gli agenti percorrono questo grafo reale

Il RAG tradizionale cerca parole chiave o vettori semantici, recuperando i 5 frammenti principali e inserendoli nel prompt.

L'OKF abilita una strategia di RAG ad attraversamento:

1. Selezione del punto di ingresso: L'agente esegue una ricerca vettoriale leggera o una query di parole chiave per trovare il documento iniziale rilevante (ad esempio, journal-publishing.md).
2. Analisi ricorsiva: L'agente analizza il documento, legge l'intestazione YAML per identificare il tipo di documento ed estrae tutti i collegamenti relativi.
3. Assemblaggio del contesto: A seconda del compito, l'agente carica ricorsivamente i file collegati per creare un contesto completo.

Ad esempio, se un agente avesse bisogno di capire come vengono convalidati i post del blog in questo portfolio, potrebbe:

1. Iniziare con journal-publishing.md (trovato tramite ricerca)
2. Seguire il collegamento a ../architecture/directory-layout.md per comprendere la struttura della codebase
3. Scoprire gli script di convalida nella documentazione dell'architettura
4. Caricare le linee guida correlate come blog-validation-tools.md per i dettagli di implementazione

Questo elimina l'overflow della finestra di contesto perché l'agente estrae solo i file che sono esplicitamente rilevanti, bypassando completamente il rumore della ricerca generica.

Convalida automatizzata

Per garantire che la struttura OKF rimanga intatta, ho implementato una convalida automatizzata:

• Uno script verifica che tutti i file markdown abbiano un frontmatter appropriato
• Convalida i campi richiesti (type, title, description, timestamp)
• Garantisce che il file di indice esista con type: "index"
• Avvisa in caso di file senza collegamenti relativi (potenziali nodi scollegati)

Questa convalida viene eseguita automaticamente durante il processo di compilazione, impedendo la distribuzione di documentazione interrotta o malformata.

Risultati nel mondo reale: OKF ne vale la pena?

Avendo implementato OKF in questa codebase reale, ecco la mia onesta valutazione basata sull'esperienza reale:

I vantaggi:

• Nessun vincolo con il fornitore: È solo Markdown. Puoi visualizzarlo in VS Code, ospitarlo su GitHub o indicizzarlo con qualsiasi provider LLM.
• Versionamento compatibile con Git: Gli aggiornamenti della documentazione passano attraverso le Pull Request standard e le revisioni dei merge.
• Indipendenza dall'agente: Gli agenti non hanno bisogno di driver di database personalizzati; hanno solo bisogno di un parser markdown.
• Esperienza dello sviluppatore: Gli ingegneri possono navigare nella documentazione allo stesso modo in cui navigano nel codice, seguendo collegamenti espliciti.

Le sfide affrontate:

• Rot dei collegamenti: La nostra convalida automatizzata rileva i collegamenti interrotti durante il processo di compilazione.
• Costi di manutenzione: Gli script di convalida garantiscono che la nuova documentazione segua automaticamente le convenzioni OKF.

In pratica, OKF ha reso la documentazione di questo portfolio molto più navigabile sia per gli umani che per gli agenti IA. Quando pongo domande sulla struttura della codebase, gli agenti possono ora seguire collegamenti espliciti per creare un contesto completo, invece di indovinare quali documenti potrebbero essere rilevanti.

L'OKF è un approccio pragmatico all'assemblaggio del contesto. Se avete problemi di allucinazioni o di contesto incompleto dell'agente, strutturare la directory /docs o /knowledge del vostro repository in modo che corrisponda a OKF è una decisione di architettura a basso costo e ad alto rendimento.