OKF + RAG: Una arquitectura híbrida para agentes de IA fiables

Si le preguntas a un agente de IA un hecho ampliamente conocido, responderá con fluidez. Pero si le pides la fórmula exacta de abandono de clientes de tu empresa, el esquema de una API interna o el manual de procedimientos para un fallo en la base de datos, podría generar algo que suene correcto pero que esté completamente inventado. Ese es el problema de las alucinaciones, y es una razón principal por la cual las empresas dudan en encomendarles trabajos reales a estos agentes.

La respuesta estándar de los últimos dos años ha sido RAG: conectar el modelo a una base de datos vectorial de documentos de la empresa, recuperar todo lo que parezca relevante y pegarlo en el prompt. Funciona bien con grandes cantidades de texto no estructurado. Su debilidad radica en que es probabilístico; devuelve fragmentos semánticamente similares a la pregunta, lo cual es diferente a fragmentos que sean fiables y autoritativos. Cuando la pregunta trata sobre la fórmula oficial de ingresos o el contrato de un endpoint de pago, la similitud no es suficiente.

En junio de 2026, Google Cloud presentó el Open Knowledge Format (OKF), una especificación neutral con respecto a los proveedores para conocimientos curados almacenados en archivos Markdown. Al combinar sus búsquedas precisas con el amplio alcance de RAG, se obtiene una arquitectura digna de consideración para agentes que deben ser tanto precisos como exploratorios.

Dos tipos de memorias

Imagínese a un nuevo empleado en su primer día. Se le presentan dos cosas.

La primera es una wiki interna curada: definiciones canónicas, documentación de APIs, fórmulas de métricas e instructivos, todo revisado, aprobado y controlado por versiones. Cuando necesitan la respuesta oficial, buscan allí. Ese es el papel del OKF.

El segundo es un motor de búsqueda que supera a todos los demás: miles de mensajes de chat, hilos de correo electrónico, tickets de soporte y transcripciones de reuniones. Cuando quieren saber qué dijeron las personas sobre un tema o buscar en archivos no estructurados, allí es donde realizan la búsqueda. Eso es RAG.

Ninguno de ellos es suficiente por sí solo. Juntos abarcan toda la gama de conocimientos que posee una organización.

Qué es OKF

OKF es deliberadamente sencillo. Un paquete es un directorio de archivos Markdown almacenados en Git. Cada archivo describe un concepto, como una tabla, una métrica, un punto de extremo de API o un manual de procedimientos, y comienza con un bloque de frontmatter en YAML para metadatos legibles por máquinas. La especificación exige muy poco a los creadores, y herramientas como Obsidian, Notion o MkDocs ya manejan el mismo formato de archivo. El proyecto se encuentra en un repositorio público.

Un archivo relacionado con una métrica empresarial puede incluir en su frontmatter el tipo, título, descripción, propietario, etiquetas y marca de tiempo. El cuerpo del archivo contiene luego la fórmula oficial, algunas reglas (por ejemplo, excluir las cuentas de prueba del denominador y no considerar las降graduaciones de plan como abandono de cliente), la tabla que sirve como fuente de información fiable y enlaces a conceptos relacionados.

---
type: metric
title: "Monthly Churn Rate"
description: "Official formula for calculating monthly customer churn."
owner: "data-engineering"
tags: [revenue, kpi, board-report]
timestamp: 2026-06-20T10:00:00Z
---

# Monthly Churn Rate

The official churn rate formula used in all board reports and investor decks:

    Churn Rate = (Customers Lost During Month / Customers at Start of Month) × 100

### Rules
- **Do NOT** use trial accounts in the denominator.
- **Do NOT** count plan downgrades as churn.
- Source of truth: `analytics.monthly_churn_summary` table.

### Related
- [Monthly Active Users](mau.md)
- [Revenue Dashboard](revenue_dashboard.md)

¿Por qué molestarse con esto?

• Sin matemáticas vectoriales. Cuando el agente necesita la fórmula de abandono, lee ese archivo directamente. No hay incrustación, ni puntuación de similitud ni top-k, solo la respuesta aprobada en cada ocasión.
• Es nativo de los flujos de trabajo de Git. Los cambios pasan por solicitudes de pull, revisiones e historial de commits, por lo que existe un registro de auditoría que muestra quién modificó la fórmula, cuándo y por qué.
• Sin infraestructura. No hay almacén de vectores, pipeline de incrustación, estrategia de fragmentación ni tarea de reindexación. Los archivos están en una carpeta.

Qué es RAG

RAG conecta un modelo con datos grandes e estructurados en seis pasos:

1. Ingresa documentos como PDFs, correos electrónicos, páginas de wiki y mensajes de chat.
2. Los fragmenta en segmentos más pequeños.
3. Incrusta cada fragmento como un vector con un modelo de incrustación.
4. Almacena los vectores en una base de datos como Pinecone, Weaviate o pgvector.

En el momento de la consulta, incrustar la pregunta en el mismo espacio y obtener los fragmentos más similares.

Añadir esos fragmentos al prompt para que el modelo pueda responder con contexto.

La ventaja de RAG es su alcance: puede sacar a la luz material relevante de miles de documentos que nadie podría organizar a mano. Su desventaja es la precisión; como la similitud guía la recuperación, puede devolver texto relacionado pero que no sea fiable. Si tres enfoques diferentes definen ligeramente de forma distinta el concepto de abandono, RAG podría elegir el incorrecto.

El diseño híbrido

La arquitectura combinada coloca un enrutador delante de ambas memorias. El enrutador examina cada consulta entrante y decide a dónde debe dirigirla: hacia el conjunto curado cuando la pregunta se refiere a una definición oficial, o hacia la búsqueda vectorial cuando es abierta y exploratoria.

Una versión simplificada en Python de ese router realiza cuatro tareas. Carga todos los archivos Markdown del paquete e indexa ellos según el título del frontmatter. Intenta realizar una coincidencia determinista de palabras clave de la consulta con esos títulos. Si encuentra un concepto, el contenido se transmite etiquetado como proveniente de la base de conocimientos oficial. De lo contrario, recurre a una búsqueda vectorial, etiquetada como búsqueda de documentos, y luego envía el contexto seleccionado al modelo con la instrucción de responder únicamente a partir de lo que se le ha proporcionado. Etiquetar la fuente en la instrucción es importante, ya que indica al modelo, y posteriormente al lector, cuánto peso merece ese contexto.

from openai import OpenAI
import os
import glob
import yaml

client = OpenAI()

# 1. Load the OKF knowledge bundle from the local directory
def load_okf_bundle(bundle_path: str) -> dict:
    """Reads all Markdown files in the OKF directory into a searchable dict."""
    knowledge = {}
    for filepath in glob.glob(f"{bundle_path}/**/*.md", recursive=True):
        with open(filepath) as f:
            content = f.read()
            # Extract the title from YAML frontmatter
            if content.startswith("---"):
                _, frontmatter, body = content.split("---", 2)
                meta = yaml.safe_load(frontmatter)
                title = meta.get("title", os.path.basename(filepath))
                knowledge[title.lower()] = body.strip()
    return knowledge

# 2. Search OKF (deterministic, keyword-based)
def search_okf(query: str, okf_knowledge: dict) -> str | None:
    """Simple keyword match against OKF titles."""
    for title, content in okf_knowledge.items():
        if title in query.lower():
            return content
    return None

# 3. Search RAG (probabilistic, vector-based)
def search_rag(query: str) -> str:
    """Placeholder for your vector DB search (Pinecone, Weaviate, etc.)."""
    # results = vector_db.similarity_search(query, top_k=5)
    return "RAG context: [retrieved chunks would appear here]"

# 4. The Intelligent Router
def answer_query(query: str, okf_bundle_path: str) -> str:
    okf_knowledge = load_okf_bundle(okf_bundle_path)

    # Try OKF first (deterministic path)
    okf_result = search_okf(query, okf_knowledge)

    if okf_result:
        context = f"[SOURCE: Official Knowledge Base (OKF)]\n{okf_result}"
    else:
        # Fall back to RAG (probabilistic path)
        context = f"[SOURCE: Document Search (RAG)]\n{search_rag(query)}"

    # Send to LLM with the retrieved context
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer using ONLY the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {query}"}
        ]
    )
    return response.choices[0].message.content

La correspondencia aquí es deliberadamente rudimentaria, basada en una búsqueda por título, para mantener la idea visible. Un sistema de producción utilizaría un enrutamiento mejor, como un clasificador o un filtro de metadatos, y manejaría el caso en el que ambas fuentes devuelvan algo relevante.

Conclusión

Para los agentes empresariales, no se trata de elegir entre OKF y RAG. El diseño más sólido utiliza ambos. Una base de conocimientos determinista, controlada por Git, protege los datos que nunca deben ser erróneos: KPIs, contratos de API y manuales operativos. Una búsqueda vectorial probabilística abarca el gran archivo de material no estructurado que nadie puede curar. El resultado es un agente que es preciso cuando la exactitud es importante y exploratorio cuando lo es el descubrimiento.