RAG pragmático: Probando el Formato de Conocimiento Abierto (OKF) de Google

Si ha integrado agentes de IA en una base de código real, es probable que haya alcanzado los límites de la búsqueda vectorial ingenua.

Le pide a un agente que modifique un endpoint de API y este recupera el cuerpo de la función mediante una búsqueda vectorial. Sin embargo, se pierde el esquema de la base de datos, el middleware de autenticación y el manual de implementación porque no compartían suficiente superposición semántica en el espacio de incrustación.

El agente falla porque opera en un vacío de contexto.

Para resolver este problema de "ensamblaje de contexto", Google Cloud publicó la especificación Open Knowledge Format (OKF). Es un estándar independiente del proveedor para convertir un directorio de archivos de texto en un gráfico de conocimiento semántico que los agentes de IA pueden navegar de forma recursiva.

Esta es mi experiencia práctica con su implementación.

Implementación en el mundo real: OKF en este portafolio

En lugar de simplemente explicar el concepto, he implementado OKF en toda la documentación de este portafolio. Puede explorar la base de conocimientos real en el directorio /knowledge/ de este repositorio.

OKF formaliza lo que muchos equipos de plataforma ya estaban haciendo: estructurar la documentación interna como un árbol de directorios limpio de archivos Markdown con frontmatter YAML.

En lugar de introducir bases de datos de gráficos propietarias o pipelines de indexación de vectores complejos, OKF se basa en dos estándares web:

1. Frontmatter YAML para metadatos a nivel de archivo (declarar qué es un archivo).
2. Enlaces Markdown estándar para declarar relaciones entre archivos (apuntar al agente al siguiente nodo).

Al vincular archivos directamente dentro del texto, convierte su directorio de documentación en un gráfico de conocimiento. Cualquier agente de LLM que analice un archivo puede seguir estos enlaces exactamente como un rastreador web recorre los enlaces HTML.

Implementación real en este portafolio

Este portafolio implementa OKF en el directorio /knowledge/. Aquí está la estructura real:

/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

Cada archivo comienza con un frontmatter OKF adecuado. Aquí está el encabezado YAML real 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"]
---

El contenido incluye relaciones explícitas entre los documentos. Por ejemplo, en journal-publishing.md, encontrará:

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

Esto crea un gráfico navegable que tanto los humanos como los agentes de IA pueden recorrer de manera efectiva.

Cómo recorren los agentes este gráfico real

El RAG tradicional busca palabras clave o vectores semánticos, recupera los 5 fragmentos principales y los vuelca en el prompt.

OKF permite una estrategia de RAG de recorrido:

1. Selección del punto de entrada: El agente ejecuta una búsqueda de vectores ligera o una consulta de palabras clave para encontrar el documento relevante inicial (por ejemplo, journal-publishing.md).
2. Análisis recursivo: El agente analiza el documento, lee el encabezado YAML para identificar el tipo de documento y extrae todos los enlaces relativos.
3. Ensamblaje del contexto: Dependiendo de la tarea, el agente carga recursivamente los archivos vinculados para crear un contexto completo.

Por ejemplo, si un agente necesitara comprender cómo se validan las publicaciones de blog en este portafolio, podría:

1. Comenzar con journal-publishing.md (encontrado a través de la búsqueda)
2. Seguir el enlace a ../architecture/directory-layout.md para comprender la estructura de la base de código
3. Descubrir los scripts de validación en la documentación de la arquitectura
4. Cargar pautas relacionadas como blog-validation-tools.md para detalles de implementación

Esto elimina el desbordamiento de la ventana de contexto porque el agente solo extrae archivos que son explícitamente relevantes, evitando por completo el ruido de búsqueda genérico.

Validación automatizada

Para garantizar que la estructura OKF permanezca intacta, he implementado una validación automatizada:

• Un script comprueba que todos los archivos markdown tengan un frontmatter adecuado
• Valida los campos requeridos (type, title, description, timestamp)
• Asegura que el archivo de índice exista con type: "index"
• Advierte sobre archivos sin enlaces relativos (nodos potencialmente desconectados)

Esta validación se ejecuta automáticamente durante el proceso de compilación, evitando que se implemente documentación rota o mal formada.

Resultados en el mundo real: ¿Vale la pena OKF?

Habiendo implementado OKF en esta base de código real, aquí está mi evaluación honesta basada en la experiencia real:

Las ventajas:

• Cero bloqueo de proveedor: Es solo Markdown. Puede verlo en VS Code, alojarlo en GitHub o indexarlo con cualquier proveedor de LLM.
• Versiones compatibles con Git: Las actualizaciones de la documentación pasan por solicitudes de extracción estándar y revisiones de fusión.
• Independencia del agente: Los agentes no necesitan controladores de base de datos personalizados; solo necesitan un analizador markdown.
• Experiencia del desarrollador: Los ingenieros pueden navegar por la documentación de la misma manera que navegan por el código, siguiendo enlaces explícitos.

Los desafíos abordados:

• Rotura de enlaces: Nuestra validación automatizada detecta enlaces rotos durante el proceso de compilación.
• Gastos generales de mantenimiento: Los scripts de validación garantizan que la nueva documentación siga automáticamente las convenciones de OKF.

En la práctica, OKF ha hecho que la documentación de este portafolio sea mucho más navegable tanto para humanos como para agentes de IA. Cuando hago preguntas sobre la estructura de la base de código, los agentes ahora pueden seguir enlaces explícitos para construir un contexto completo en lugar de adivinar qué documentos podrían ser relevantes.

OKF es un enfoque pragmático para el ensamblaje de contexto. Si tiene problemas con las alucinaciones o el contexto incompleto del agente, estructurar el directorio /docs o /knowledge de su repositorio para que coincida con OKF es una decisión de arquitectura de bajo costo y alto rendimiento.