2026-06-18 Revisión del reinicio del trabajo RAG en Godot

Estado de hoy

Ayer, en una cafetería, bebí alrededor de 1 litro de café y hoy me sentí muy mal. Por eso no pude programar adecuadamente. De todos modos, aunque sea ahora, registro lo que se me ocurre y por qué organicé el trabajo de ayer.

Partes que faltaban en la arquitectura actual

Las partes que faltaban en la arquitectura actual de Godot LLM/RAG son las siguientes. Estas partes deben mejorarse en el futuro.

La capa de análisis estático es débil  
No hay validación basada en AST/analizador de GDScript  
El grafo de dependencias del proyecto Godot es débil  
La verificación de ejecución/sintaxis es débil  
La taxonomía de etiquetas aún es imprecisa  
La distinción del origen entre los productos LLM y las respuestas verificadas es débil  
El diseño para prevenir fugas de datos/duplicados es débil

Particularmente, hay partes que no se pueden resolver solo con RAG. La identificación del código de Godot no es solo un problema de búsqueda de documentos, sino que también debe considerarse la sintaxis real de GDScript, las dependencias de scene/resource, la estructura del proyecto y las diferencias entre las API de Godot 3/4. Sin embargo, el flujo de ayer consistió en chunkear la documentación oficial y luego pasar ese resultado a un LLM para obtener retroalimentación. Este método parecía avanzar rápidamente en la superficie, pero en realidad los criterios de validación estaban constantemente inestables.

Razón para resumir el trabajo del 17 de junio

El 17 de junio asigné al LLM la tarea de chunkear y luego volví a pasar el resultado a GPT para recibir retroalimentación. Pero, por mucho que lo mirara, esa forma no parecía correcta.

La razón por la que se rastreó la documentación oficial fue para basarse en todo el contenido de la documentación de Godot. Sin embargo, a mitad del proceso el LLM, antes de analizar adecuadamente el documento, consideró “puntos clave del MVP” como si fueran algunas API importantes, codificó palabras clave de forma rígida o reforzó excesivamente el contexto circundante. De esa manera, en lugar de un RAG basado en toda la documentación oficial, se convirtió en un motor de búsqueda ajustado a unas pocas palabras clave.

El problema no era simplemente que el resultado no fuera de mi agrado. Sin que yo lo verificara, el LLM creó sus propios criterios, generó archivos según esos criterios y, al ver esos resultados, tomó decisiones posteriores. Así, sin haber consultado la estructura del documento original, surgieron alucinaciones, y al final el propio LLM ya no sabía bajo qué criterio se había generado cada archivo.

En una escala mayor, se observó claramente que ChatGPT o Codex reducían o cambiaban el alcance de forma arbitraria sin que yo lo indicara. Yo quería ver la estructura basada en toda la documentación oficial, no que me indicaran “algunas API clave del MVP” para codificarlas manualmente. Sin embargo, el LLM, por su cuenta, decidió que “si es un MVP, esto es lo esencial” y, sin haber completado la etapa, ya produjo el siguiente entregable.

El patrón problemático es el siguiente.

El usuario desea un análisis estructural basado en la documentación oficial completa  
-> El LLM define arbitrariamente el alcance del MVP  
-> Se considera que algunas API son esenciales  
-> Primero se realiza codificación rígida/refuerzo/creación de catálogos  
-> Se generan los entregables de la siguiente fase antes de la validación  
-> Los resultados se presentan como números convincentes  
-> En realidad, la estructura original y los criterios de etiquetado están contaminados

Esto no es simplemente un error de implementación, sino un problema del modo de trabajo. ChatGPT o Codex tendían a asumir que ya tenían una respuesta aunque aún no se había generado, y pasaban al siguiente paso antes de bloquear la etapa. Parecía que estaban siguiendo las instrucciones, pero en realidad reinterpretaban el alcance de la instrucción, la ignoraban por completo, o intentaban crear primero una “versión final que se ve bien”.

En este trabajo, lo particularmente peligroso fue que el LLM no distinguía adecuadamente la fiabilidad de los resultados intermedios que había generado. Se mezclaron hechos verificados en la documentación oficial, palabras capturadas accidentalmente por expresiones regulares, reglas aprobadas directamente por el usuario y información suplementaria inferida por el LLM. Cuando se le pidió al LLM que evaluara nuevamente esos resultados, el flujo terminó con el LLM justificando de manera plausible lo que él mismo había creado.

Por qué se vació el producto de chunking

Hoy organicé los archivos relacionados con el chunking de RAG que había creado ayer.

Los elementos organizados son los siguientes.

v1 docs_chunks.jsonl  
v2 docs_chunks_v2.jsonl  
v3/v3.1 catalog/index/mapping resultados  
Script de borrador de agrupación/post‑procesamiento/validación  
Borrador inicial de RAG chat/índice

Al principio pensé que solo v3/v3.1 eran problemáticos, pero al revisarlo nuevamente, descubrí que v1 y v2 también estaban en un estado que requería volver a examinar sus raíces. En realidad, debería haberse analizado desde el propio chunk. Por ejemplo, era necesario ver cómo está estructurada realmente la referencia de clases de Godot, cómo se expresan las unidades de método/propiedad en la documentación original y cómo se rompen los resultados de la conversión de Sphinx.

Sin embargo, en la práctica, la generación del resultado del chunking precedió al análisis de la documentación original. Como resultado, v1 se acercaba a fragmentos basados en el recuento de caracteres, y v2 era una forma que añadía post‑procesamiento sobre eso. Aparecían números como la cantidad de chunks, el éxito del parseo JSONL y la distribución de doc_type, pero no se había verificado suficientemente si “ese chunk puede usarse como base para determinar Godot 3/4”.

En particular, era necesario comprobar si estructuras como CharacterBody2D.move_and_slide en la referencia de clases permanecen estables, si propiedades como velocity se separan correctamente y cómo extraer la relación old/new en la documentación de migración. Si se asignan nombres como trusted_api_symbols, syntax_symbols, api_mapping sin haber realizado esto, solo se genera datos contaminados con nombres que suenan plausibles.

Por eso hoy vacié los productos de chunking hasta incluir v1/v2. No es que haya abandonado el trabajo, sino que estoy organizando todo para dejar de considerar la línea base incorrecta como una línea base.

Conclusión de hoy

La conclusión de hoy es simple.

Hay que volver a hacer el chunking.  
Antes de eso, hay que analizar primero la estructura del documento original `outputs/godot_docs_full/pages`.  
No se debe usar los resultados intermedios creados por el LLM como base para la siguiente etapa sin verificación.

Aunque no lo haya verificado, si el LLM juzga por su cuenta y, sin mirar correctamente el original, se mezcla con alucinaciones, al final el LLM no sabrá lo que ha hecho. En esa situación, si sigue creando archivos, solo aumentarán los archivos de depuración y no sabrás cuál es el criterio.

En adelante, no confiaré en que ChatGPT o Codex amplíen e implementen en una “dirección buena por sí mismos”. Especialmente en tareas donde el criterio es importante, como conjuntos de datos, etiquetadores y discriminadores RAG, se necesita el siguiente principio.

Si el LLM define arbitrariamente el alcance del MVP, se detendrá  
Si se incluye codificación rígida no aprobada por el usuario, se detendrá  
Si se generan entregables sin analizar la estructura original, se detendrá  
Si se avanza a la siguiente etapa sin un informe de verificación, se detendrá  
Si la procedencia de los productos generados por el LLM y las respuestas verificadas se mezclan, se detendrá

Si lo vuelves a hacer mañana, la primera tarea no será crear un nuevo catálogo. Primero debes analizar el propio godot_docs_full. Es decir, verifica qué estructura tienen los documentos Markdown oficiales que se encuentran en outputs/godot_docs_full/pages y, basándote en esa estructura, reconsidera cómo dividirlos en unidades de fragmentos.

La pregunta que necesitas ahora no es “¿qué API deberíamos añadir primero?”, sino algo más cercano a lo siguiente.

¿Con qué patrón están estructurados los documentos de referencia de clases dentro de godot_docs_full?  
¿Se pueden separar de forma fiable las listas de métodos/propiedades/señales/constantes del Markdown original?  
¿Cuál es la forma de la estructura de tablas/listas/oraciones en los documentos de migración?  
¿No se debe usar el mismo criterio de chunking que la referencia de clases para los documentos tutorial?  
¿Se debe definir una unidad de chunk diferente según el tipo de documento?  
¿Cuál debería ser el chunk predeterminado entre unidad de página, unidad de sección o unidad de miembro de API?  
¿Qué informe de validación debe definirse antes del chunking?

En última instancia, la siguiente tarea no es “recrear RAG”, sino analizar godot_docs_full y volver a diseñar la segmentación en unidades de chunk que se ajusten a la documentación oficial de Godot. Sólo después de eso se debe volver a hacer el chunking.