RAG pragmatico: testare l'Open Knowledge Format (OKF) di Google
La ricerca vettoriale da sola non risolve il problema dell'assemblaggio del contesto per gli agenti IA. Ecco come ho strutturato la documentazione di un repository come grafo markdown navigabile.
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.
Il concetto: cos'è l'OKF?
L'OKF formalizza ciò che molti team stavano già facendo: strutturare la documentazione interna come una directory pulita di file Markdown con intestazioni YAML.
Invece di introdurre database a grafo complessi, l'OKF si basa su due standard web:
- YAML Frontmatter per i metadati del file (dichiarare cos'è il file).
- Collegamenti Markdown standard per dichiarare le relazioni tra i file.
Collegando i file direttamente nel testo, trasformate la vostra documentazione in un grafo di conoscenza. Qualsiasi agente che analizza un file può seguire questi link come un web crawler.
Un esempio concreto
In un repository di una libreria di componenti dell'interfaccia utente, potreste strutturare la vostra base di conoscenza OKF in questo modo:
/knowledge-base
├── components/
│ └── interactive-modal.md
├── compliance/
│ └── wcag-checklist.md
└── tokens/
└── theme-palette.mdCiascuno di questi file inizia con un blocco di metadati minimo. La specifica è leggera, l'unico campo richiesto è type.
Ecco l'intestazione YAML per interactive-modal.md:
---
type: "ui-component"
title: "Interactive Modal Dialog"
description: "Accessibility-compliant overlay specification supporting dynamic focus trapping and theme tokens."
timestamp: "2026-07-06T12:00:00Z"
tags: ["react", "wcag", "accessibility", "design-system"]
---E all'interno del contenuto markdown, definiamo relazioni tramite collegamenti relativi:
The Modal component manages overlays and traps keyboard focus internally.
For semantic HTML and ARIA attribute rules, refer to the [WCAG AA Compliance Checklist](../compliance/wcag-checklist.md).
To style backdrop filters and component states, import design tokens from the [Theme Palette Config](../tokens/theme-palette.md).Come gli agenti esplorano il grafo
Il RAG tradizionale cerca parole chiave o vettori, recupera i primi 5 frammenti e li inserisce nel prompt.
L'OKF consente una strategia di RAG di esplorazione:
- Selezione del punto di ingresso: L'agente trova il primo documento rilevante (es.
interactive-modal.md). - Analisi ricorsiva: L'agent analizza il documento ed estrae tutti i collegamenti relativi.
- Assemblaggio del contesto: L'agente carica ricorsivamente i file collegati (linee guida WCAG e token di progettazione) per creare un contesto completo prima di scrivere il codice React.
Conclusione: ne vale la pena?
I vantaggi:
- Nessun vincolo di fornitore: È solo Markdown.
- Controllo di versione con Git: Gli aggiornamenti passano attraverso standard Pull Request.
- Indipendenza dell'agente: Gli agenti hanno solo bisogno di un parser markdown standard.
I contro:
- Collegamenti interrotti: I collegamenti relativi si interrompono se i file vengono spostati. Utilizzate un linter nella vostra pipeline di CI.
- Costi di manutenzione: Richiede l'impegno di aggiornare intestazioni e collegamenti a ogni modifica del codice.