Esquema y arquitectura del clasificador RAG de la documentación oficial de Godot

Fecha de creación: 21 de junio de 2026

Propósito

Organizar la arquitectura de referencia para conectar la recopilación completa de la documentación oficial de Godot mediante el flujo JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6. Este documento no es una guía de implementación para generar datos de entrenamiento, sino un criterio de diseño que define cómo estructurar la documentación Markdown ya reunida en outputs/godot_docs_full/pages y convertirla en una base de datos de evidencia buscable.

Datos de entrada actuales

Los resultados de la recopilación de la documentación oficial se encuentran bajo outputs/godot_docs_full en el repositorio.

Línea base actual:

Pipeline completo

1. El crawler recopila la documentación oficial de Godot desde Internet.
2. Los resultados de la recopilación se guardan como Markdown por página.
3. El Markdown se normaliza y se le añaden metadatos para convertirlo en registros JSONL.
4. Los JSONL se inyectan en PostgreSQL.
5. PostgreSQL almacena los fragmentos de documento, el mapeo de API y los prototipos de etiquetas por separado.
6. Cuando el usuario solicita un análisis del código fuente de Godot, el AST Parser estructura el código del proyecto.
7. El Retriever busca evidencia en PostgreSQL basándose en la pregunta del usuario y los resultados del análisis AST.
8. El Validator agrupa la pregunta, el resultado del AST y la evidencia encontrada y la envía a Qwen 3.6.
9. Qwen 3.6 no actúa como decisor final, sino que elabora la respuesta usando la evidencia verificada.
10. El Validator verifica la evidencia/formato/patrones prohibidos de la respuesta y la devuelve al usuario.

Conversión de Markdown a JSONL

Los archivos pages/*.md son la versión original legible por humanos, pero son demasiado grandes para RAG. Por lo tanto, el script de conversión divide cada página en secciones/miembros de API/ejemplos y conserva la URL original y el tipo de documento.

Reglas comunes de normalización

Salida JSONL

Esquema de docs_chunks.jsonl

{
  "chunk_id": "godot-stable:classes/class_node.html#description:0001",
  "doc_version": "stable",
  "source_url": "https://docs.godotengine.org/en/stable/classes/class_node.html",
  "source_file": "outputs/godot_docs_full/pages/classes__class_node__....md",
  "source_sha256": "...",
  "doc_type": "class_reference",
  "symbol": "Node",
  "section_path": ["Node", "Description"],
  "heading": "Description",
  "content": "Nodes are Godot's building blocks...",
  "code_blocks": [],
  "language_tags": ["gdscript"],
  "godot_version_tags": ["4.x", "stable"],
  "api_symbols": ["Node", "_ready", "_process", "queue_free"],
  "token_count": 420,
  "metadata": {
    "status": "copied_old",
    "bytes": 12345
  }
}

Campos obligatorios:

Esquema api_mapping.jsonl

{
  "mapping_id": "godot3-to-4:kinematicbody2d-to-characterbody2d",
  "source_api": "KinematicBody2D",
  "target_api": "CharacterBody2D",
  "change_type": "rename_or_replacement",
  "godot_from": "3.x",
  "godot_to": "4.x",
  "confidence": "verified_from_docs",
  "evidence_chunk_ids": [
    "godot-stable:tutorials/migrating/upgrading_to_godot_4.html#..."
  ],
  "match_terms": ["KinematicBody2D", "CharacterBody2D"],
  "notes": "Godot 4 character movement node replacement candidate.",
  "negative_patterns": ["do not suggest KinematicBody2D for Godot 4 projects"]
}

Principios:

Esquema de label_prototypes.jsonl

{
  "prototype_id": "label:godot3-api-in-godot4:kinematicbody2d",
  "label": "godot3_api_in_godot4",
  "task_type": "version_classification",
  "input_pattern": "extends KinematicBody2D",
  "expected_finding": "Godot 3 style physics body API detected.",
  "recommended_action": "Use CharacterBody2D or CharacterBody3D depending on project dimension.",
  "evidence_mapping_ids": [
    "godot3-to-4:kinematicbody2d-to-characterbody2d"
  ],
  "evidence_chunk_ids": [],
  "severity": "high",
  "validator_rules": {
    "requires_ast_symbol": "KinematicBody2D",
    "forbidden_answer_terms": ["KinematicBody2D is recommended in Godot 4"]
  }
}

Etiqueta candidata:

Borrador del esquema PostgreSQL

PostgreSQL asume por defecto el uso de pgvector. La búsqueda por palabras clave se realiza con tsvector o índices trigram.

docs_chunks

Índices:

api_mapping

Índices:

label_prototypes

Índices:

AST Parser entrada/salida

AST Parser convierte el código fuente del usuario en una estructura buscable antes de pasarlo directamente al LLM. El objetivo inicial son .gd, .tscn, project.godot.

Entrada

Esquema de salida

{
  "project_id": "local-analysis-...",
  "godot_project": {
    "config_version": 5,
    "features": ["4.4", "Forward Plus"]
  },
  "files": [
    {
      "path": "scripts/player.gd",
      "language": "gdscript",
      "extends": "CharacterBody2D",
      "class_name": "Player",
      "symbols": ["CharacterBody2D", "Input", "move_and_slide"],
      "annotations": ["@onready"],
      "version_signals": ["godot4_annotation_syntax"],
      "diagnostics": []
    }
  ],
  "version_evidence": {
    "godot4": ["config_version=5", "@onready"],
    "godot3": []
  }
}

Inicial campo de extracción:

Funcionamiento del Retriever

El Retriever es una capa que selecciona evidencia antes que el LLM.

1. Extrae la intención y la tarea objetivo de la pregunta del usuario.
2. Obtiene símbolos de API, señales de versión y rutas de archivo del resultado del AST Parser.
3. Realiza primero una búsqueda exacta en api_mapping.
4. Ejecuta simultáneamente filtrado de símbolos de API + búsqueda por palabras clave + búsqueda vectorial en docs_chunks.
5. Obtiene etiquetas similares y reglas de validación de label_prototypes.
6. Ordena los resultados de búsqueda en paquetes de evidencia.

Paquetes de evidencia:

{
  "query_id": "analysis-...",
  "task_type": "version_classification",
  "ast_summary": {},
  "doc_evidence": [],
  "api_mapping_evidence": [],
  "label_evidence": [],
  "retrieval_scores": {
    "exact_api_hits": 2,
    "keyword_hits": 8,
    "vector_hits": 12
  }
}

Separación de roles entre Validator y Qwen 3.6

Qwen 3.6 es el modelo que lee la evidencia encontrada y organiza la respuesta. El Validator se encarga de la etiqueta final, la adopción de evidencia y la verificación de patrones prohibidos.

Elementos que Validator debe comprobar:

Orden de inyección

1. Revisar outputs/godot_docs_full/summary.json y failed.json.
2. Cargar manifest.json y pages/*.md.
3. Generar el informe de normalización de Markdown.
4. Crear docs_chunks.jsonl.
5. Generar candidatos api_mapping.jsonl a partir de la documentación migration/class.
6. Crear label_prototypes.jsonl con reglas aprobadas y casos representativos.
7. Insertar (upsert) en PostgreSQL solo los registros que pasen la validación del esquema JSONL.
8. Generar embeddings y actualizar el índice vectorial.
9. Actualizar el índice de palabras clave y el índice exacto.
10. Verificar los resultados del Retriever con preguntas de muestra.

Lista de verificación de calidad

Prioridades de implementación

1. Redactar informe de análisis de la estructura de pages/*.md.
2. Crear script de transformación para docs_chunks.jsonl.
3. Crear script de validación del esquema JSONL.
4. Redactar DDL de PostgreSQL.
5. Inyección y verificación de búsqueda de docs_chunks.
6. Generar candidatos api_mapping y diseñar flujo de aprobación manual.
7. Crear conjunto inicial de etiquetas en label_prototypes.
8. Extraer campos mínimos con el AST Parser.
9. Generar salida del bundle de evidencia del Retriever.
10. Conectar el bucle de organización de respuestas de Validator + Qwen 3.6.

Principios clave

• No modificar ni eliminar el Markdown original de la documentación oficial.
• Tratar JSONL como artefacto intermedio reproducible.
• En la base de datos registrar siempre la ruta original, la URL original, el hash y la versión del script de transformación.
• Evitar que el LLM invente etiquetas.
• La determinación Godot 3/4 se basa en señales del AST, mapeo de API y evidencia de la documentación oficial.
• Los candidatos inciertos no se usan directamente como datos de entrenamiento, sino que se mantienen en estado candidate.
• Qwen 3.6 actúa como organizador de respuestas; los criterios de decisión los poseen Retriever y Validator.

Próximas tareas

El siguiente paso es analizar la estructura de Markdown en outputs/godot_docs_full/pages. Dado que la referencia de clases, la migración y los tutoriales tienen estructuras diferentes, primero se debe definir una estrategia de fragmentación por tipo de documento en lugar de aplicar una única regla de fragmentación.