2026-06-25 Análisis de fuentes y reflexión sobre la clasificación de Markdown

Hoy volví a organizar los criterios para dividir el Markdown de la documentación oficial en tres tablas JSONL.

Al principio pensé en dividir el Markdown de la documentación oficial de Godot en las tablas docs_chunks, api_mapping y label_prototypes. Sin embargo, mientras que los roles de docs_chunks y api_mapping estaban claros, los límites de label_prototypes eran difusos.

Al principio los límites entre las tres tablas eran confusos. Luego, al revisar el diagrama de flujo, me di cuenta de que las tres tablas comparten el mismo objetivo: clasificar el Markdown de la documentación oficial en JSONL para su almacenamiento.

La conclusión organizada es la siguiente:

docs_chunks contiene la evidencia de la documentación oficial de Godot 4.
api_mapping es el objetivo JSONL que guarda cómo cambiaron los nombres de funciones, clases y símbolos al pasar de Godot 3 a Godot 4.
label_prototypes es el objetivo JSONL que guarda cómo escribir cuando el modo de uso de una función, su composición de argumentos o su patrón de llamada cambian por completo.

En adelante, analizaré los proyectos de Godot por unidad de sistema de archivos. Dividiré archivos como .gd, .tscn, .tres, project.godot en fragmentos AST/código y usaré la evidencia JSONL de la documentación oficial según sea necesario. Luego, invocaré Qwen 3.6 bajo demanda para determinar si el fragmento pertenece a Godot 3, Godot 4, si necesita migración o si puede usarse como datos de explicación de código.

Guardaré este resultado de juicio en la base de datos de puntuaciones y clasificaré los sistemas de archivos del proyecto como Godot 3 / Godot 4 / mixto / desconocido. Posteriormente, crearé fuentes para diseñar SFT y DPO basadas en los sistemas de archivos clasificados.

Roadmap relacionado:

docs/roadmaps/2026-06-25-source-analysis-scoring-architecture.md
docs/roadmaps/2026-06-25-markdown-jsonl-llm-classification.md

Reinicio de la clasificación de Markdown

Hoy descarté los resultados de la clasificación Markdown → JSONL.

La razón es que, en la fase de clasificación, solo se estaban enviando los primeros 3000 caracteres al LLM, no el Markdown completo. La intención y la necesidad del usuario era clasificar basándose en la documentación completa desde el principio. Sin embargo, el rango de transmisión del código generado por el LLM se limitó arbitrariamente a la parte inicial, y no lo detecté a tiempo. En la documentación oficial, a veces el carácter del documento no se revela con solo la parte inicial, y especialmente los límites de api_mapping y label_prototypes requieren ver si se trata de un cambio de nombre de función/símbolo o de un cambio en el modo de uso, argumentos o patrón de llamada.

Criterios organizados:

La clasificación de Markdown debe recibir el nombre del archivo y el cuerpo completo del Markdown.
No se elige una tabla basándose solo en el extracto inicial.
Los productos JSONL y los datos insertados en PostgreSQL se consideran resultados de criterios incorrectos y se descartan todos.
Vaciar la base de datos y los JSONL y volver a iniciar la clasificación.

Resultados del reinicio:

godot_rag.docs_chunks: 0 registros
godot_rag.api_mapping: 0 registros
godot_rag.label_prototypes: 0 registros
godot_rag.ingest_reports: 0 registros
Eliminación de los JSONL locales
Reinicio de la aplicación Streamlit

En este trabajo se repitió un error similar.

No fue que el usuario diseñara mal desde el principio, sino que el código y la documentación generados por el LLM se desviaron de la intención del usuario y no se detectó la diferencia a tiempo. No se trató solo de una omisión puntual, sino de una repetición de omisiones al organizar los límites de las tablas y el flujo de datos. Como se dice, los errores repetidos son parte de la habilidad; esta parte debe revisarse con mayor cuidado.

En particular, hubo problemas al afirmar la documentación sin verificar primero la implementación, o al escribir esquemas y flujos aún no definidos como si fueran definitivos. Incluso cuando docs_chunks, api_mapping y label_prototypes debían estar al mismo nivel, se describió una tabla como si tuviera un flujo especial, rompiendo la consistencia del documento.

De ahora en adelante, redactar la documentación será casi un procedimiento obligatorio en cada paso del trabajo. El objetivo de la documentación no es solo organizar para mostrar, sino confirmar bajo qué criterio se está juzgando en ese momento. Si el código o los datos cambian, aunque sea un poco, se debe registrar de dónde proviene el cambio y evitar repetir el mismo error.

Si esta vez hubiera continuado sin documentar la estructura actual del código, podría haber descubierto el problema más tarde. Al redactar la documentación del método de clasificación del LLM, confirmé que el código realmente enviaba solo los primeros 3000 caracteres en lugar del Markdown completo, y pude corregirlo para que enviara todo el Markdown según la solicitud original. Por lo tanto, este caso reafirma que la documentación no es solo una organización simple, sino una verificación de que el comportamiento real del código coincide con la intención del usuario.

Observación de la interrupción de RunPod y reanudación de la conversión

Durante la conversión Markdown → JSONL, el servidor RunPod se detuvo inesperadamente, lo que también interrumpió la conversión en la aplicación web local. Luego, reinicié la aplicación Streamlit y verifiqué si el estado se mantenía o si todo comenzaba de nuevo.

Los criterios de observación fueron el estado por archivo guardado en state.json y el Latest Processing Log de la aplicación web. Las pruebas clave antes y después del reinicio fueron:

Antes del reinicio, el estado era done 47, deferred 7, converting 1, pending 1515.
El archivo que se estaba procesando era pages/classes__class_astar3d__23ef6ac2.md.
Después del reinicio, el registro mostró 앱 재시작 후 자동 이어하기를 일시정지함 (se pausó la reanudación automática tras reiniciar la app).
Luego apareció el registro 처리 중이던 파일을 pending으로 되돌림 (el archivo en proceso se devolvió a pending), y el archivo objetivo siguió siendo pages/classes__class_astar3d__23ef6ac2.md.
Al reanudar, se registró 기존 분류 재사용 (reutilización de la clasificación existente) y, tras completar ese archivo, se pasó al siguiente.
Posteriormente, los archivos pages/classes__class_astargrid2d__51463855.md, pages/classes__class_atlastexture__336f837e.md y pages/classes__class_audiobuslayout__a2e0df1f.md se procesaron secuencialmente, aumentando el conteo de done.

De esta observación se concluyó:

El resultado total de la conversión no se reinició.
El archivo en proceso volvió de forma segura a pending.
Los archivos ya completados no se reprocesaron.
Si existía una clasificación previa, se reutilizó.
Al reiniciar, la ejecución continuó desde el punto donde se había interrumpido.

Sin embargo, cuando el servidor RunPod se detiene inesperadamente, el flujo de conversión puede quedar en espera o detenerse durante mucho tiempo. En tareas de conversión largas, es necesario configurar notificaciones que detecten rápidamente el estado del servidor RunPod, fallos de respuesta de la API y reinicios de la aplicación local. Solo observar la pantalla de la aplicación web no permite distinguir si el servidor se cayó, si se está esperando una respuesta de la API o si la aplicación local se cerró.

Si se sigue usando este flujo, al menos los siguientes estados deben notificarse de forma visible:

Imposibilidad de respuesta del servidor RunPod
Reintentos de timeout de la API o respuestas 5xx repetidas
Terminación del proceso de la aplicación Streamlit
Un archivo en proceso permanece en la misma etapa de tabla por un tiempo prolongado
La reanudación automática se pausa debido al reinicio de la app