Markdown -> JSONL LLM método de clasificación

Fecha de creación: 25 de junio de 2026

Propósito

Registra el método mediante el cual el convertidor web make_md determina, mediante LLM, a cuál objetivo JSONL (docs_chunks, api_mapping, label_prototypes) debe enviarse la documentación Markdown.

Este documento no almacena el código de la aplicación web ni la clave API. Basado en la implementación local que está en funcionamiento, se resume qué entrada se proporciona al LLM y qué salida se permite.

Estado de ejecución actual

La UI web local se ejecuta en la siguiente dirección.

http://localhost:8501/

El proceso en ejecución actual está en /Users/joyeongjin/make_md y se ejecuta con streamlit run app.py --server.port 8501.

Ubicación de la llamada de clasificación

En la implementación actual, la clasificación de tablas está a cargo de classify_tables().

/Users/joyeongjin/make_md/app.py

La llamada de clasificación se ejecuta antes que la transformación.

-> classify_tables()
-> lista de tablas seleccionadas
-> call_qwen_api() por tabla
-> creación de registro JSONL
-> validate_record()
-> guardar

Entrada LLM

En la etapa de clasificación, los tres tipos de entrada que se pasan al LLM son los siguientes.

Entrada	Descripción
mensaje del sistema	Obliga a devolver solo JSON. Se prohíbe Markdown, explicaciones y texto de razonamiento.
nombre de archivo	Nombre del archivo Markdown subido
markdown completo	Todo el contenido del Markdown

La fase de clasificación debe enviar todo el documento Markdown completo. No se debe enviar solo el extracto inicial. Si solo se revisa la parte inicial de la documentación oficial, se pueden clasificar incorrectamente documentos donde los límites aparecen en ejemplos posteriores o descripciones detalladas, como api_mapping y label_prototypes.

Formato de salida del LLM

El LLM debe devolver únicamente una única matriz JSON.

Valores permitidos:

["docs_chunks", "api_mapping", "label_prototypes"]

Ejemplo:

["docs_chunks"]

["api_mapping", "label_prototypes"]

[]

[] se debe usar solo cuando se determine que no es contenido útil de la documentación oficial.

Resumen actual del prompt

El núcleo del prompt de clasificación debe ser el siguiente.

Classify this Markdown into zero or more target tables.
Return exactly one JSON array.
Valid values are:
["docs_chunks", "api_mapping", "label_prototypes"]

Table boundaries:
- docs_chunks: official documentation explanations, tutorials, class reference chunks.
- api_mapping: Godot 3 -> Godot 4 function/class/symbol name changes.
- label_prototypes: usage-pattern migrations where arguments, call shape, or usage style changed, not just the name.

Rules:
- Use [] only if the file is not useful documentation content.
- Use one or more valid table names when conversion is needed.
- Do not include explanations, markdown fences, or any text outside JSON.

FILE: <filename>
FULL MARKDOWN:
<entire markdown text>

Criterios de clasificación

Se debe proporcionar a LLM los límites de las tres tablas simultáneamente.

Tabla	Límite previsto
`docs_chunks`	Texto descriptivo de la documentación oficial, tutoriales, fragmentos de referencia de clases
`api_mapping`	Cómo cambian los nombres de funciones, clases y símbolos de Godot 3 a Godot 4
`label_prototypes`	Cómo proceder cuando el modo de uso de una función, la composición de sus argumentos o el patrón de llamada cambian por completo

Los límites de api_mapping y label_prototypes son especialmente importantes. Si solo cambia el nombre, corresponde a api_mapping; si cambian la composición de los argumentos o el método de llamada, corresponde a label_prototypes.

Flujo de corrección de JSON

Si LLM no devuelve correctamente un arreglo JSON, se envía una solicitud de corrección adicional.

El núcleo de la solicitud de corrección es el siguiente.

Your previous classification response was not valid JSON.
Rewrite it as exactly one JSON array using only these strings:
["docs_chunks", "api_mapping", "label_prototypes"].
Use [] only if this file is not useful documentation content.

Si la corrección también falla, el archivo se registra como error de clasificación.

¿Existe un fallback codificado?

En la etapa actual de clasificación, no se fuerza la selección de la tabla mediante un fallback codificado basado en el nombre del archivo, la ruta o expresiones regulares.

Si no hay una clave API, no se realiza la clasificación. Si la respuesta de Qwen no es un arreglo JSON válido y la corrección también falla, no se elige ninguna tabla arbitrariamente para guardar; en su lugar, se deja como error.

Registro de depuración

Los resultados de la clasificación se registran en el estado de la sesión con la siguiente forma.

{
  "file": "example.md",
  "parsed_result": ["docs_chunks"],
  "matched_tables": ["docs_chunks"],
  "raw_response": "<qwen raw response>"
}

Este registro se utiliza para identificar la causa cuando Qwen responde con algo que no es JSON, devuelve [] o devuelve un nombre de tabla no válido.