22 de junio de 2026 - Reflexión

Hoy, en lugar de insertar directamente la documentación oficial de Godot en Markdown en RAG, creé un flujo que primero la convierte a JSONL estructurado para revisarla. Al principio no tenía claro cómo dividir la documentación en Markdown, pero al crear una interfaz de conversión y ver los resultados por archivo, resultó mucho más sencillo.

Convertidor de Markdown → JSONL

Al subir un archivo Markdown de la documentación oficial de Godot, se clasifica la tabla objetivo mediante la API de Qwen y se separa el resultado en JSONL para docs_chunks, api_mapping y label_prototypes.

Al principio pensé en leer el Markdown y cargarlo directamente en la base de datos, pero eso dificultaba saber a qué tabla pertenecía cada documento. Por eso cambié a generar primero un JSONL como producto intermedio y a comparar el resultado de la conversión con el texto original en la pantalla.

Las ventajas de este método son las siguientes:

• Se pueden comparar el Markdown original y el JSONL convertido.
• Se puede verificar a cuál de docs_chunks, api_mapping o label_prototypes pertenece cada documento.
• Se pueden filtrar documentos mal clasificados o resultados vacíos antes de insertarlos en la base de datos.
• Si se modifican las reglas de conversión, basta volver a generar el JSONL y compararlo.

Verificación de los resultados de la conversión

El convertidor muestra en pantalla la cantidad de archivos JSONL guardados y el número de errores. En la vista de hoy, los resultados de docs_chunks se acumulaban primero, mientras que api_mapping, label_prototypes y los archivos con errores aún estaban vacíos.

Esta situación no es tanto un error como una señal de que los documentos iniciales son mayormente explicativos, por lo que es natural que terminen en docs_chunks. Lo importante es que los resultados no se insertan directamente en la base de datos, sino que se guardan primero como JSONL y pueden ser revisados por una persona.

Vista previa de JSONL y verificación en forma de tabla

Se permitió ver los resultados de JSONL tanto en formato JSON como en formato de tabla en la pantalla. Por ejemplo, el registro docs_chunks tiene campos como chunk_id, doc_version, source_url, source_file, source_sha256, doc_type, section_path, heading, content, code_blocks, api_symbols, token_count, metadata.

Al verlo así es mucho mejor que simplemente tener un archivo Markdown. En particular, como chunk_id y source_sha256 aparecen juntos, resulta más fácil rastrear más tarde de qué origen proviene cada fragmento. Lo más importante en RAG es no perder de vista de dónde proviene la evidencia, y parece que los productos intermedios de JSONL pueden cumplir esa función.

Registro de transformación

También se revisó el registro de transformación por archivo. Se pudo ver qué archivo comenzó, en qué tabla clasificó Qwen y cuántos registros válidos se generaron.

En el ejemplo revisado hoy, el documento about__complying_with_licenses se clasificó como docs_chunks y se transformó en varios fragmentos. Por el contrario, documentos como 404 no tenían tabla de destino y se omitieron en el flujo. Tener este registro permite rastrear dónde surgieron problemas al procesar los 1 570 documentos en su totalidad.

Configuración local de PostgreSQL

Después de crear el JSONL, también organizamos la base de datos para poder insertarlo en PostgreSQL local. Levantamos un contenedor basado en pgvector/pgvector:pg16 y creamos las tablas docs_chunks, api_mapping, label_prototypes, ingest_reports.

Lo que vimos como especialmente importante hoy es que el esquema de la base de datos no debe desalinearse con los nombres de los campos del JSONL. Si la base de datos agrega campos arbitrariamente, el contrato del JSONL se vuelve difuso y, más adelante, el transformador y el inyector podrían operar con criterios diferentes. Por eso, la columna payload de la base de datos se ajustó al esquema del JSONL, y las columnas de operación de la base de datos se minimizaron a id, embedding, search_tsv, created_at.

Ejecutamos la base de datos localmente y verificamos mediante pruebas de rollback tanto la inserción de muestra en formato JSONL como la búsqueda. Aunque aún no hemos cargado todos los documentos en la base de datos, el camino de JSONL → PostgreSQL se ha vuelto mucho más claro.

Decisión de hoy

El flujo que creamos hoy no es el clasificador final de RAG. Sin embargo, en esta etapa representa un avance bastante significativo.

Antes, era ambiguo cómo manejar la documentación oficial en Markdown, y pasar directamente al chunking o a la inserción en la base de datos podía desdibujar la estructura. Hoy, al introducir una etapa de conversión/validación a JSONL, creamos un entregable intermedio que puede ser revisado por una persona.

En conclusión, parece que el camino a seguir es este.

Documentación oficial de Godot Markdown  
-> Conversión a JSONL  
-> Vista previa/validación de JSONL  
-> Inyección de PostgreSQL  
-> Validación de búsqueda del Retriever  
-> Resumen de respuestas de Validator/Qwen

Después de mañana, cuando se haya convertido completamente los 1 570 documentos, será necesario verificar qué proporción aparecen docs_chunks, api_mapping y label_prototypes. En particular, como api_mapping y label_prototypes no deben ser generados arbitrariamente por Qwen, no se debe confiar ciegamente en los resultados automáticos; se debe incluir una fase de aprobación/validación.

Medición de la velocidad de procesamiento

Al calcular la velocidad de conversión, parece que convertir los 1 570 archivos Markdown a JSONL tomará aproximadamente 42 horas.

El tiempo real de procesamiento hasta ahora ha sido de alrededor de 1 hora 9 minutos. Durante ese período se procesaron un total de 43 archivos, combinando 39 done y 4 deferred. La velocidad media es de aproximadamente 1,6 minutos por archivo.

Tiempo real de procesamiento: aproximadamente 1 hora 9 minutos  
Archivos procesados actualmente: done 39 + deferred 4 = 43  
Velocidad promedio: aproximadamente 1.6 minutos por archivo  
Tiempo estimado total para convertir 1,570 elementos: aproximadamente 42 horas

Al principio pensé que tomaría aproximadamente 1 elemento por minuto, pero al calcularlo con los registros reales lleva un poco más de tiempo. Puede que sea difícil completar la conversión de los 1 500 elementos en un solo día, por lo que debemos avanzar registrando continuamente la velocidad de procesamiento y la cantidad de archivos fallidos o en espera.

Próximo plan de verificación

Mañana y pasado mañana probablemente no haya tiempo disponible, así que no podremos continuar de inmediato. Sin embargo, el trabajo que retomaremos más adelante ya está bastante organizado.

Primero, debemos cargar los archivos JSONL generados durante la recopilación y transformación en una base de datos PostgreSQL local. Hasta ahora, el convertidor que hemos creado se ha centrado en dividir el Markdown en JSONL para docs_chunks, api_mapping y label_prototypes; el siguiente paso es insertar esos JSONL en la base de datos real y verificar que sean buscables.

Luego, verificaremos de forma pequeña el flujo de trabajo que describimos en docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md mediante un script de Python.

source code
-> AST Parser
-> Retriever
-> evidence JSONL / evidence bundle
-> Llamada a la API Qwen 3.6
-> Verificar respuesta

En otras palabras, se insertará código fuente arbitrario de Godot en un script de Python y se verificará si el analizador AST extrae los símbolos y las señales de versión. El resultado se enviará al Recuperador para que, desde PostgreSQL, obtenga fragmentos de la documentación oficial o mapeos de API relacionados, y se comprobará periódicamente qué respuesta se obtiene al pasar el paquete JSONL/evidence devuelto a la API de Qwen 3.6.

Este proceso no es una automatización completa, sino una pequeña validación end‑to‑end para confirmar que cada etapa funciona realmente en conjunto. En particular, se debe verificar si Qwen responde basándose en la memoria o si responde basándose en la evidencia proporcionada por el Recuperador.

Pensamientos sobre hacer público el repositorio y volverlo privado

Recientemente publiqué este repositorio una vez y luego lo cambié a privado nuevamente. La razón parecía simple. No quería mostrar mis habilidades.

Mi nivel actual todavía me parece bastante deficiente. Sin embargo, al mismo tiempo pensé en crear un modelo exclusivo para Godot, subirlo a Hugging Face y usarlo como punto de partida para expandirlo a áreas como videos de conferencias, la universidad, portafolios y reconocimiento. De alguna manera, parece una ilusión demasiado soñadora. Aun así, pensé que si alguien pudiera usar mis reflexiones y registros de trabajo como trampolín para crecer, yo también podría crecer más rápidamente en ese proceso.

De hecho, todavía tengo la sensación de no querer publicar. Me asusta que lo que he creado pueda parecer superficial, y por otro lado también temo que alguien pueda copiar directamente la parte que, aunque sea de forma superficial, he entrelazado varios conocimientos para que parezca fácil. No es que el resultado sea una tecnología asombrosa, sino que me resulta agobiante que todo el rastro de mis reflexiones y conexiones hasta ahora se revele por completo.

Aunque configuré PR y pipelines CI/CD, el flujo que originalmente imaginé era que, cuando se subiera un PR en GitHub workflow, el endpoint local de LLM alojado en Oracle Cloud revisara automáticamente el PR. Como Oracle Cloud dispone de un entorno de 24 GB de VRAM, pensé que podría ejecutar casi cualquier modelo local y conectar el LLM alojado a la automatización de revisión de código. Sin embargo, perdí la cuenta de Oracle Cloud, por lo que este flujo no podrá volver a usarse por un tiempo. RunPod también presenta la molestia de tener que volver a configurarlo cada vez que se usa para validar PRs. Por eso, por ahora me centraré en el trabajo manual y la documentación, y dejaré la automatización de revisión de PR basada en LLM para más adelante, lo cual parece más realista.

Conclusión parece ser esta. Aunque es muy probable que nadie lo vea, yo estaba extremadamente preocupado por ser descubierto. Sin embargo, incluso si alguien consulta o toma mi trabajo, debo usar eso como trampolín para superarme aún más. La decisión de publicar debe seguir siendo cuidadosa, pero no debo detener la documentación por miedo.