idea_world_labDEV JOURNAL
miércoles, 17 de junio de 2026

2026-06-17 Reflexión sobre la Construcción del Detector LLM/RAG de Godot

Resumen en una línea

Hoy redefinimos la dirección del modelo de codificación especializado en Godot, pasando de un modelo simple de preguntas y respuestas a un Agente SWE a nivel de repositorio, y creamos la primera versión concreta del detector RAG basado en la documentación oficial y del pipeline de generación de datos que lo precede.

Gran flujo del día

Al principio, el objetivo era “crear un chatbot RAG con la documentación oficial de Godot”. Sin embargo, a medida que avanzaba la conversación y el trabajo, el objetivo se volvió más claro.

Recopilación de la documentación oficial de Godot  
-> Detector RAG basado en documentación oficial  
-> Etiquetado del proyecto Godot en GitHub  
-> Generación de datos SFT/DPO  
-> Modelo de codificación Godot 4 basado en Qwen  
-> Agente SWE a nivel de repositorio

En resumen, el objetivo de hoy no es crear un chatbot, sino establecer una base de detección/creación de datos para desarrollar un modelo que pueda leer y corregir proyectos de Godot en el futuro.

1. Se considera que un modelo de preguntas y respuestas simple es insuficiente

Lo primero que organizó hoy fue la naturaleza del objetivo del modelo.

En el pasado, consideramos crear un conjunto de datos de preguntas/respuestas sobre Godot 4 y entrenar el modelo para que respondiera bien al código de Godot 4. Sin embargo, al pensar en solicitudes como “hazme un mapa”, nos dimos cuenta de que no se trataba simplemente de un problema de preguntas y respuestas.

El flujo real de la solicitud se asemeja más a lo siguiente.

Comprender la solicitud del usuario  
-> Explorar la estructura del repositorio  
-> Encontrar scene/script/resource relacionados  
-> Verificar la ruta de los assets y el estilo de código existente  
-> Determinar la sintaxis/API de Godot 4  
-> Modificar el código  
-> Ejecutar/pruebas/validación  
-> Generar parche

Este flujo no es un problema de generar una sola respuesta, sino un problema de agente de ingeniería de software. Por eso hoy reorienté la dirección del modelo desde la perspectiva de SWE-agent trajectory training.

Palabras clave principales registradas hoy:

Long-context repository-level software engineering agent training
SWE-agent trajectory training
Godot repo-level patch generation
long-context trajectory dataset

También he organizado los casos de referencia.

SWE-agent trajectories
SWE-smith
SWE-Gym
CoderForge-Preview
ACC
RepoBench / CrossCodeEval / RepoCoder
aiXcoder CoLT
godot-dodo
wallstoneai/godot-gdscript-dataset

La conclusión de hoy fue que solo con pequeñas preguntas y respuestas de instrucciones no es suficiente. Lo que finalmente se necesita es una trayectoria de exploración, juicio, modificación y verificación a nivel de proyecto Godot.

Notas relacionadas:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md

2. Resumen del roadmap completo de Godot LLM

A continuación, se volvió a establecer el roadmap completo de desarrollo.

El flujo principal se organizó de la siguiente manera.

Datos
-> Chatbot RAG de primera fase
-> SFT
-> DPO
-> SWE Agent

Si dividimos los pasos con más detalle, es lo siguiente:

Etapa 0. Preparación  
Etapa 1. Recolección y estructuración de datos  
Etapa 2. Desarrollo del chatbot RAG de primera fase  
Etapa 3. Etiquetado de datos y creación del conjunto de datos  
Etapa 4. Entrenamiento del modelo  
Etapa 5. Desarrollo del agente SWE  
Etapa 6. Mejora continua

En este roadmap, la decisión más importante es no considerar el chatbot RAG de primera fase como una simple herramienta de preguntas y respuestas. Primero, se necesita crear un verificador RAG que actúe como experto en la documentación oficial de Godot, y mediante ese verificador etiquetar/procesar los datos de GitHub antes de expandirlos con SFT/DPO y el agente SWE.

En particular, el agente SWE de la Etapa 5 no debe ser solo un generador de código, sino que debe poseer las siguientes capacidades.

Análisis del proyecto  
Exploración de archivos necesarios  
Modificar código  
Verificar CLI de Godot o resultados de ejecución  
Análisis de la causa del fallo  
Generar parche

Hoja de ruta relacionada:

docs/roadmaps/2026-06-17-godot-llm-roadmap.md

3. Diseño de la estructura de generación de datos basada en el discriminador RAG

Hoy otra decisión importante fue “no delegar la decisión final de la etiqueta al LLM”.

Al principio era fácil pensar que el chatbot RAG podría determinar si se trata de Godot 3/4 al observar el código o la documentación de GitHub. Sin embargo, el etiquetado afecta directamente la calidad de los datos de entrenamiento, por lo que confiar en un juicio improvisado del LLM es arriesgado.

Así que estructuramos lo siguiente.

LLM es asistente de generación  
La etiqueta la decide el sistema  
El JSONL final es ensamblado/verificado por el pipeline de Python

Lo que el sistema debe encargarse:

Extracción de símbolos  
Consulta de la base de datos de mapeo API  
Búsqueda de vectores en la documentación oficial  
Búsqueda por palabras clave  
Búsqueda de prototipo de etiqueta  
Puntuación de etiquetas  
Cálculo de confianza  
Ensamblaje final de JSONL  
Verificación

Lo que el LLM puede encargarse:

Crear borrador de código corregido  
Generar explicación  
Generar preguntas/respuestas SFT  
Generar respuestas malas DPO  
Crear borrador de parche  
Asistencia para verificación/explicación de problemas

También se organizaron ocho conjuntos de datos objetivo.

version_classification
api_mapping
migration_fix
instruction_sft
dpo_preference
repo_explorer
patch_generation
metadata_verification

Este teorema se convirtió en el criterio de diseño del código de post‑procesamiento RAG que creamos hoy. En particular, la razón por la que se separaron api_mapping, symbol_catalog, keyword_index, search_text también proviene de aquí.

Notas relacionadas:

docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md

4. Flujo MVP desde el detector RAG hasta el modelo Qwen 3.6

Se ha elaborado por separado el diagrama de flujo MVP entre el detector RAG de Godot y el modelo de codificación Qwen 3.6.

Flujo organizado:

godot_docs_full.zip Preparar el documento original
-> Chunking inicial basado en chunk_docs.py
-> Postprocesamiento exclusivo para Godot
-> Construir infraestructura de búsqueda local
-> Recopilación y estructuración de datos de GitHub
-> Ejecutar el clasificador RAG
-> Generar conjunto de datos de entrenamiento
-> Qwen 3.6 SFT/DPO

Aquí, la infraestructura de búsqueda local no se refiere solo a una única base de datos vectorial.

Configuración necesaria:

Vector DB
Keyword Index
Reranker
API Mapping DB
Label Prototype DB

Además, los datos de GitHub deben ingresarse no como fragmentos de código simples, sino como una estructura a nivel de repositorio.

Entrada requerida:

.gd
.tscn
.tres
project.godot
README
repo tree
metadata

También he vuelto a organizar el objetivo del SFT de primera fase.

Godot 4 prioridad de pensamiento  
GDScript salida básica  
Rechazo de la API de Godot 3  
Explicación del fundamento de la conversión de Godot 3 → 4

Después, DPO debe definir con mayor claridad los criterios de respuestas buenas y respuestas malas.

Respuesta mala: respuesta mezclada con la API de Godot 3  
Respuesta buena: respuesta con código puro de Godot 4 y con fundamentos

Notas relacionadas:

docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md

5. v1 Chunks de la documentación oficial

Después de organizar el diseño, creamos una forma de insertar los datos reales de la documentación oficial en RAG.

El primer entregable creado es el siguiente archivo.

work/godot_rag/chunks/docs_chunks.jsonl

Documentación oficial Markdown 1.570 se dividió según encabezados y longitud, creando 9.741 fragmentos.

Resultado:

Input pages: 1,570
Output chunks: 9,741
Max chunk chars: 2,800
Overlap chars: 350

Lo que fue bueno en v1:

  • Se creó todo el documento oficial en fragmentos JSONL.
  • El análisis de JSONL fue estable.
  • Se clasificaron tipos de documentos básicos como class_reference, tutorial, migration.

Problemas de v1:

  • Quedan muchos textos residuales de Sphinx.
  • Había fragmentos de ruido demasiado cortos.
  • heading, section, la estructura de método/propiedad no estaba lo suficientemente presente.
  • La referencia de clase no se separó de manera precisa por unidades de API.

v1 era la fase de “recolección de documentación oficial y chunking básico”. Fue el punto de partida del MVP de búsqueda, pero resultó insuficiente para el clasificador de etiquetas.

6. v2 post‑procesamiento

A continuación, se creó postprocess_chunks.py y se generaron los chunks de v2.

Archivo:

work/godot_rag/postprocess_chunks.py
work/godot_rag/chunks/docs_chunks_v2.jsonl

¡Lo que se procesó en v2:!

Eliminar fragmento 404  
Eliminar fragmento de ruido corto  
Eliminar texto residual de Sphinx  
Extraer símbolos  
Extraer nombre_de_clase  
Refuerzo de sección/tipo_de_miembro/nombre_de_miembro  
Mostrar fragmentos relacionados con migración

Resultado:

Input chunks: 9,741
Output chunks: 8,778
Dropped 404 chunks: 3
Dropped short/noise chunks: 960
Migration-related chunks: 695

v2 está en un estado en el que puede usarse como MVP de búsqueda RAG basado en la documentación oficial. Sin embargo, aún es insuficiente para considerarse el verificador final de etiquetas. En particular, cambios de sintaxis/API como move_and_slide, velocity, @export, await no estaban separados como criterios de verificación independientes.

7. Dirección incorrecta de v3 y retroceso

El v3 que se pensó inicialmente consistía en codificar de forma rígida algunas API clave para crear fragmentos api_focus.

Ejemplo:

KinematicBody2D
CharacterBody2D
move_and_slide
@export
await

Esta forma puede parecer que aumenta rápidamente el rendimiento de búsqueda. Sin embargo, en la práctica era peligrosa.

Problema:

  • El motor de búsqueda puede sobreajustarse a la API elegida por la persona.
  • Las API fuera de la lista se debilitan.
  • Algunas API representativas pueden parecer que representan toda la API de Godot.
  • Las API omitidas pueden conducir más tarde a errores de etiquetado.

Por eso se revirtió la versión v3 anterior. Esta decisión fue importante. A corto plazo parece una pérdida, pero considerando la calidad final del clasificador, los fragmentos de enfoque codificados manualmente eran una dirección incorrecta.

8. Rediseño de v3 basado en catálogos

Después de revertir, se cambió la dirección.

Nuevos principios:

No se pierde ni un solo chunk de v2.  
No se crean chunks de foco nuevos arbitrariamente.  
Se extrae automáticamente symbol/catalog/index/mapping de toda la documentación oficial.  
La información de refuerzo de búsqueda se adjunta como metadata.

Código añadido:

work/godot_rag/build_symbol_catalog.py
work/godot_rag/build_keyword_index.py
work/godot_rag/build_api_mapping.py
work/godot_rag/make_chunks_v3.py
work/godot_rag/validate_rag_artifacts.py
work/godot_rag/retrieval_smoke_test.py

Producto generado:

work/godot_rag/catalog/symbol_catalog.jsonl
work/godot_rag/catalog/keyword_index.json
work/godot_rag/catalog/api_mapping.jsonl
work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl
work/godot_rag/validation/validation_report.json
work/godot_rag/validation/retrieval_smoke_test.json

El archivo completo docs_chunks_v3.jsonl tiene aproximadamente 189 MB, por lo que podría superar el límite de un solo archivo en GitHub. Por eso, subí al repositorio los archivos divididos que se conservan línea por línea, y si es necesario los vuelvo a combinar localmente.

cat work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl \
  > work/godot_rag/chunks/docs_chunks_v3.jsonl

9. Verificación de consistencia v3

En v3 lo que se consideró más importante fue prevenir omisiones. Si falta siquiera un fragmento de v2, la evidencia de la documentación oficial podría desaparecer más adelante.

Por eso se creó validate_rag_artifacts.py.

Criterios de validación:

v2 chunk_id set == v3 chunk_id set
no missing or extra v3 chunks
catalog/index/mapping references point to existing chunks
search_text is present
no old hardcoded api_focus fields remain

Resultado de la verificación:

status: pass
v2 chunks: 8,778
v3 chunks: 8,778
v2 unique chunk_id: 8,778
v3 unique chunk_id: 8,778
symbol catalog entries: 134,922
keyword index keys: 192,257
api mapping records: 144
v3 chunks with api mappings: 1,900
v3 migration-related chunks: 2,392

Además, también se realizó una prueba de humo basada en lexical/palabras clave antes de la etapa de incrustación.

Consulta representativa:

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Resultado pasó todas las 5 pruebas.

10. El mayor riesgo descubierto hoy

La visión más importante de hoy fue que “lo que se extrae mucho” y “lo que se escribe confiando en la etiqueta” son diferentes.

Si se extrae de forma amplia en toda la documentación oficial, el recall mejora. Sin embargo, si se trata todo el resultado con el mismo nivel de confianza, el índice de palabras clave se contamina.

Por ejemplo, lo siguiente probablemente sea un elemento real de API o de sintaxis.

CharacterBody2D
move_and_slide
FileAccess
@export
await

Por otro lado, es probable que lo siguiente sea una palabra general del documento o una columna de tabla.

Returns
See
Tip
MIT
Software
Type

En el proceso de verificar la prueba de humo, descubrimos un problema en el que una columna de tabla normal, como Type -> EditorSceneFormatImporterFBX2GLTF, podía ser capturada como candidata de mapeo de API. Este problema se corrigió excluyendo Type de las candidatas de mapeo.

La conclusión obtenida aquí es clara.

Es necesario extraer de manera amplia.  
Sin embargo, no se debe usar todo lo extraído de manera amplia como un hecho confiable.

11. v3.1 Estructura de separación de confiabilidad

Después de confirmar el riesgo anterior, se determinó que no se debía usar v3 tal cual en el detector final de etiquetas. Por eso, en v3.1 no se agrupa todo el catálogo en uno solo, sino que se separa por confiabilidad y por uso.

Estructura nueva introducida en v3.1:

trusted_api_symbols
syntax_symbols
migration_mappings
mentioned_symbols
candidate_terms
rejected_terms
retrieval_keys
search_text

Cada campo también se ha dividido claramente.

trusted_api_symbols:
class reference estructura verificada directamente class/method/property/signal/constant

syntax_symbols:
Elementos de sintaxis verificados en la documentación de sintaxis de GDScript y en la documentación de migración

migration_mappings:
mapeo de cambios de Godot 3 -> 4 vinculado con fragmentos de evidencia de la relación old -> new

mentioned_symbols:
símbolos mencionados en tutorial/body pero que ya están en el catálogo trusted/syntax

candidate_terms:
palabras candidatas de ayuda para la recuperación de búsqueda

rejected_terms:
palabras comunes que no deben usarse como etiquetas, como Returns, See, Tip, MIT, Software

Código añadido:

work/godot_rag/build_v31_artifacts.py
work/godot_rag/validate_v31_artifacts.py

Producto v3.1 generado:

work/godot_rag/chunks/docs_chunks_v3_1.jsonl
work/godot_rag/chunks/docs_chunks_v3_1.summary.json
work/godot_rag/catalog_v3_1/trusted_api_catalog.jsonl
work/godot_rag/catalog_v3_1/syntax_catalog.jsonl
work/godot_rag/catalog_v3_1/api_mapping.jsonl
work/godot_rag/catalog_v3_1/mention_index.json
work/godot_rag/catalog_v3_1/keyword_index.json
work/godot_rag/catalog_v3_1/v3_1.summary.json
work/godot_rag/validation_v3_1/validation_report.json
work/godot_rag/validation_v3_1/retrieval_smoke_test.json

Resultado v3.1:

Source v2 chunks: 8,778
Output v3.1 chunks: 8,778
Trusted API catalog entries: 26,318
Syntax catalog entries: 68
API mapping records: 144
Mention index keys: 10,292
Keyword keys: 71,543
Validation status: pass
Retrieval smoke tests: 5 / 5 passed

Hubo también una parte importante que se corrigió.

En el proceso de creación de la versión v3.1, si se confiaba ciegamente en class_name extraído de los metadatos de v2, valores incorrectos como Tutorials, All, String podían subir al catálogo de confianza. Por eso se volvió a generar el nombre de clase canónico basándose en la URL de origen y la ruta de referencia de la clase. Después de esta corrección, problemas de mayúsculas como Characterbody2d también se ajustaron a CharacterBody2D.

Otra verificación crucial fue move_and_slide. En el método de extracción amplio existía el riesgo de que aparecieran entradas falsas de confianza como ProjectSettings.move_and_slide. En la v3.1 se limitó la promoción a confianza solo a los miembros confirmados en la sección estructurada de la referencia de clase, y al final la entrada de confianza move_and_slide quedó únicamente en la clase real de Godot, como se muestra a continuación.

CharacterBody2D.move_and_slide
CharacterBody3D.move_and_slide

¡En otras palabras, lo que se hizo en la versión 3.1 no fue simplemente añadir más campos, sino cambiar a una estructura en la que “se usa de manera amplia para la búsqueda, pero se emplean solo evidencias estrechas y confiables para la determinación de etiquetas”.

12. v3.1 verificación de consistencia

En v3.1 la omisión era especialmente peligrosa. Si falta siquiera uno de los 8 778 fragmentos de la v2, la base documental oficial puede desaparecer.

Criterio de validación:

v2 chunk_id set == v3.1 chunk_id set  
v3.1 unique chunk_id count == 8,778  
doc_type mantener distribución  
legacy eliminar campo mixto  
trusted/syntax/migration catalog verificar integridad de referencia  
search_text verificar existencia

Resultado de la verificación:

status: pass
errors: 0
warnings: 0
v2 chunks: 8,778
v3.1 chunks: 8,778

También volví a ejecutar la prueba de humo de búsqueda.

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Resultado pasó todas las 5 pruebas. El significado de esta etapa no es “el etiquetador final está completo”, sino que la estructura v3.1 es lo suficientemente íntegra como para pasar al menos a un índice MVP de vectores/palabras clave.

13. Reflejo en GitHub y organización de registros

Hoy no solo creé los entregables de código y datos, sino que también organicé la actualización en GitHub.

Tareas realizadas:

# Configuración remota
División de archivos v3 de gran tamaño
Push de la rama de trabajo
Fusión del historial local con el main remoto
Push al main
Organización del directorio de documentación

docs_chunks_v3.jsonl tiene aproximadamente 189 MB, por lo que subirlo tal cual podría superar el límite de archivo único de GitHub. Por eso se dividió en docs_chunks_v3.part-000.jsonl, docs_chunks_v3.part-001.jsonl, docs_chunks_v3.part-002.jsonl.

Además, al principio la retrospectiva se creó en la raíz retrospectives/, pero no coincidía con la estructura del repositorio existente. Por eso la estructura de la documentación se organizó de la siguiente manera.

docs/research-notes/   Memoria de diseño
docs/roadmaps/         Hoja de ruta completa
docs/retrospectives/   Retrospectivas por fecha
work/godot_rag/        Código RAG y entregables
outputs/godot_docs_full/ Resultados del rastreo de la documentación oficial

Además, creé docs/README.md para organizar también la función del directorio de documentación.

14. Organización del autor/email de Git

Como anoté en el README de hoy, también resolví el problema de la reflección del contribution graph de GitHub.

Problemas confirmados:

Los correos electrónicos del autor/committer del historial **main** están mezclados  
Correo electrónico del localhost  
Correo electrónico de naver  
Correo electrónico noreply de GitHub

Dirección procesada:

# Configuración global de Git cambiada a yyeongjin <appsky1888@gmail.com>
Unificar autor/committer en el historial de main  
Reflejar en el remoto  
Guardar una rama de respaldo antes de reescribir

Rama de respaldo:

backup/before-author-email-rewrite-2026-06-17

Esta tarea no está directamente vinculada al propio RAG, pero fue una de las labores de organización importantes de hoy. Fue un trabajo de base para que los registros y los commits se reflejen correctamente en el perfil de GitHub.

15. Documentos creados/organizados hoy

Principales documentos creados o organizados hoy:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md
docs/roadmaps/2026-06-17-godot-llm-roadmap.md
docs/retrospectives/2026-06-17-godot-rag-judge.md
docs/README.md

También agregué la sección de registro de desarrollo del 17 de junio y la preparación de datos RAG al README.

16. Conclusión actual

El estado actual se puede resumir así.

**Dirección:**  
No debe ser un modelo de preguntas y respuestas de Godot, sino un agente Godot SWE.

**Datos:**  
El RAG de la documentación oficial debe actuar como un discriminador para la generación de datos de entrenamiento.

**Etiqueta:**  
No debe decidirlo un LLM, sino una canalización de Python.

**RAG:**  
- v2 es un conjunto de fragmentos básico y seguro.  
- v3 es un producto intermedio del catálogo extraído de forma amplia.  
- v3.1 es el producto RAG recomendado actualmente, que incluye la separación por confiabilidad.

**Riesgo:**  
No se deben usar todos los símbolos extraídos con el mismo nivel de confianza.

Hoy el trabajo no consistió solo en crear algunos archivos, sino en varios momentos en los que fue fácil tomar un rumbo equivocado. En particular, fueron cruciales las decisiones de revertir el chunk de API hardcodeado, de detectar el riesgo de ruido en broad v3 y de separar trusted/syntax/migration/mention/candidate/rejected en v3.1.

17. Próximas tareas

La siguiente tarea no es simplemente etiquetar código en GitHub.

Lo que hay que hacer primero:

  1. Generar embeddings basados en search_text de docs_chunks_v3_1.jsonl
  2. Probar una recuperación híbrida que combine búsqueda vectorial y búsqueda por palabras clave
  3. Diseñar un pipeline en Python para decidir etiquetas a partir de trusted_api_symbols, syntax_symbols, migration_mappings
  4. Definir el formato de entrada de datos para estructurar el repositorio de GitHub
  5. Diseñar el flujo de determinación a nivel de repositorio que considere .gd, .tscn, .tres, project.godot y el README conjuntamente
  6. Conectar los resultados del clasificador RAG con un pipeline que genere un conjunto de datos JSONL de 8 tipos
  7. Cuando el endpoint remoto de LLM esté listo, enlazarlo para asistir en la generación de código/modificaciones, explicaciones, candidatos SFT/DPO
  8. Luego ampliar con aprendizaje de trayectoria SFT/DPO basado en Qwen y del agente SWE

La lección final de hoy es esta.

En lugar de recopilar muchos documentos,  
es más importante separar con qué grado de confianza se utilizará el conocimiento recopilado.