RAG pragmatique : Test du format de connaissances ouvertes (OKF) de Google

Si vous avez intégré des agents IA dans une base de code réelle, vous avez probablement atteint les limites de la recherche vectorielle naïve.

Vous demandez à un agent de refactoriser un point de terminaison d'API, et il récupère le corps de la fonction via une recherche vectorielle. Mais il lui manque le schéma de la base de données, le middleware d'authentification et le manuel de déploiement, car ils ne partageaient pas assez de similitudes sémantiques.

L'agent échoue car il fonctionne dans un vide contextuel.

Pour résoudre ce problème "d'assemblage de contexte", Google Cloud a publié la spécification Open Knowledge Format (OKF). Il s'agit d'un standard neutre pour convertir un répertoire de fichiers texte en un graphe de connaissances sémantiques navigable par les agents de manière récursive.

Voici mon retour d'expérience sur sa mise en œuvre.

Implémentation réelle : OKF dans ce portfolio

Plutôt que d'expliquer simplement le concept, j'ai implémenté l'OKF dans toute la documentation de ce portfolio. Vous pouvez explorer la base de connaissances réelle dans le répertoire /knowledge/ de ce dépôt.

L'OKF formalise ce que de nombreuses équipes de plateforme faisaient déjà : structurer la documentation interne sous forme d'une arborescence propre de fichiers Markdown avec des en-têtes YAML.

Au lieu d'introduire des bases de données de graphes propriétaires ou des pipelines d'indexation vectorielle complexes, l'OKF repose sur deux standards du web :

1. YAML Frontmatter pour les métadonnées au niveau du fichier (déclarer ce qu'est un fichier).
2. Liens Markdown standard pour déclarer les relations entre les fichiers (indiquer le nœud suivant à l'agent).

En liant les fichiers directement dans le texte, vous transformez votre répertoire de documentation en un graphe de connaissances. Tout agent LLM analysant un fichier peut suivre ces liens exactement de la même manière qu'un robot d'indexation parcourt les ancres HTML.

Implémentation concrète dans ce portfolio

Ce portfolio implémente l'OKF dans le répertoire /knowledge/. Voici la structure réelle :

/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

Chaque fichier commence par un en-tête OKF approprié. Voici l'en-tête YAML réel de /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"]
---

Le contenu inclut des relations explicites entre les documents. Par exemple, dans journal-publishing.md, vous trouverez :

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

Cela crée un graphe navigable que les humains et les agents IA peuvent parcourir efficacement.

Comment les agents parcourent ce graphe réel

Le RAG traditionnel recherche des mots-clés ou des vecteurs, récupère les 5 meilleurs extraits et les intègre au prompt.

L'OKF permet une stratégie de RAG par parcours :

1. Sélection du point d'entrée : L'agent exécute une recherche vectorielle légère ou une requête par mots-clés pour trouver le document initial pertinent (par exemple, journal-publishing.md).
2. Analyse récursive : L'agent analyse le document, lit l'en-tête YAML pour identifier le type de document et extrait tous les liens relatifs.
3. Assemblage du contexte : Selon la tâche, l'agent charge récursivement les fichiers liés pour construire un contexte complet.

Par exemple, si un agent avait besoin de comprendre comment les articles de blog sont validés dans ce portfolio, il pourrait :

1. Commencer par journal-publishing.md (trouvé via la recherche)
2. Suivre le lien vers ../architecture/directory-layout.md pour comprendre la structure de la base de code
3. Découvrir les scripts de validation dans la documentation de l'architecture
4. Charger les directives associées comme blog-validation-tools.md pour les détails d'implémentation

Cela élimine le dépassement de la fenêtre de contexte car l'agent n'importe que les fichiers qui sont explicitement pertinents, évitant ainsi le bruit des recherches génériques.

Validation automatisée

Pour garantir que la structure OKF reste intacte, j'ai implémenté une validation automatisée :

• Un script vérifie que tous les fichiers markdown ont un en-tête approprié
• Il valide les champs requis (type, title, description, timestamp)
• Il s'assure que le fichier d'index existe avec le type type: "index"
• Il avertit en cas de fichiers sans liens relatifs (nœuds potentiellement déconnectés)

Cette validation s'exécute automatiquement pendant le processus de build, empêchant le déploiement de documentation corrompue ou mal formée.

Résultats réels : l'OKF en vaut-il la peine ?

Après avoir implémenté l'OKF dans cette base de code réelle, voici mon évaluation honnête basée sur mon expérience :

Les victoires :

• Pas de dépendance fournisseur : C'est simplement du Markdown. Vous pouvez le visualiser dans VS Code, l'héberger sur GitHub ou l'indexer avec n'importe quel fournisseur de LLM.
• Gestion des versions avec Git : Les mises à jour de la documentation passent par des Pull Requests standard et des revues de fusion.
• Indépendance de l'agent : Les agents n'ont pas besoin de pilotes de base de données personnalisés ; ils ont seulement besoin d'un analyseur markdown.
• Expérience développeur : Les ingénieurs peuvent naviguer dans la documentation de la même manière qu'ils naviguent dans le code – en suivant des liens explicites.

Les défis relevés :

• Liens brisés : Notre validation automatisée détecte les liens brisés pendant le processus de build.
• Surcharge de maintenance : Les scripts de validation garantissent que la nouvelle documentation respecte automatiquement les conventions OKF.

En pratique, l'OKF a rendu la documentation de ce portfolio beaucoup plus navigable pour les humains et les agents IA. Lorsque je pose des questions sur la structure de la base de code, les agents peuvent désormais suivre des liens explicites pour construire un contexte complet plutôt que de deviner quels documents pourraient être pertinents.

L'OKF is une approche pragmatique pour l'assemblage de contexte. Si vous rencontrez des hallucinations ou un contexte d'agent incomplet, structurer le répertoire /docs ou /knowledge de votre dépôt pour correspondre à l'OKF est une décision d'architecture peu coûteuse et à fort rendement.