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.

El concepto: ¿Qué es OKF?

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 encabezados YAML.

En lugar de introducir bases de datos de gráficos complejas, OKF se basa en dos estándares web:

YAML Frontmatter para metadatos a nivel de archivo (declarar qué es el archivo).
Enlaces Markdown estándar para declarar relaciones entre archivos.

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

Un ejemplo concreto

En un repositorio de biblioteca de componentes de interfaz de usuario, podría estructurar su base de conocimiento OKF así:

/knowledge-base
  ├── components/
  │   └── interactive-modal.md
  ├── compliance/
  │   └── wcag-checklist.md
  └── tokens/
      └── theme-palette.md

Cada uno de estos archivos comienza con un bloque de encabezado mínimo. La especificación es ligera; el único campo requerido es type.

Aquí está el encabezado YAML para 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"]
---

And dentro del contenido de markdown, definimos relaciones mediante enlaces relativos:

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

Cómo los agentes recorren el gráfico

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

OKF permite una estrategia de RAG de recorrido:

Selección del punto de entrada: El agente encuentra el primer documento relevante (por ejemplo, interactive-modal.md).
Análisis recursivo: El agente analiza el documento y extrae todos los enlaces relativos.
Ensamblaje del contexto: El agente carga recursivamente los archivos vinculados (las pautas de WCAG y los tokens de diseño) para crear un contexto de dependencia completo antes de escribir el código React.

Conclusión: ¿Vale la pena?

Las ventajas:

Sin bloqueo de proveedor: Es simplemente Markdown.
Control de versiones con Git: Las actualizaciones de documentación pasan por flujos de trabajo estándar de Pull Request.
Independencia del agente: Los agentes solo necesitan un analizador de markdown estándar.

Los inconvenientes:

Enlaces rotos: Los enlaces relativos se rompen si los archivos se mueven. Es recomendable usar un linter en su flujo de CI.
Coste de mantenimiento: Requiere el compromiso de actualizar los encabezados y enlaces con cada cambio en el código.