Méthode de classification Markdown -> JSONL LLM

Date de rédaction : 25 juin 2026

Objectif

Dans le convertisseur web make_md, on consigne la façon dont on fait juger par le LLM vers quel fichier JSONL parmi docs_chunks, api_mapping, label_prototypes envoyer le Markdown de la documentation officielle.

Ce document ne stocke ni le code de l'application web ni les clés d'API. En se basant sur l'implémentation locale actuellement en cours d'exécution, il résume quelles entrées sont fournies au LLM et quelles sorties sont autorisées.

État d'exécution actuel

L'interface web locale s'exécute à l'adresse suivante.

http://localhost:8501/

Le processus d'exécution actuel est lancé depuis /Users/joyeongjin/make_md avec streamlit run app.py --server.port 8501.

Emplacement de l'appel de classification

Dans l'implémentation actuelle, la classification des tables est gérée par classify_tables().

/Users/joyeongjin/make_md/app.py

Les appels de classification sont exécutés avant la conversion.

-> classify_tables()
-> Liste des tables sélectionnées
-> Appeler call_qwen_api() par table
-> Création d'un enregistrement JSONL
-> validate_record()
-> Enregistrer

Entrée LLM

Dans l'étape de classification, les trois entrées transmises au LLM sont les suivantes.

Entrée	Description
message système	Contraint à ne renvoyer que du JSON. Le Markdown, les explications et le texte de réflexion sont interdits.
nom de fichier	Nom du fichier Markdown téléchargé
markdown complet	Texte complet du Markdown

L'étape de classification doit obligatoirement envoyer le texte complet du Markdown. Il ne faut pas se limiter à un extrait du début. Si l’on ne regarde que le début de la documentation officielle, on risque de mal classer des documents où les limites apparaissent dans les exemples ou les explications détaillées ultérieures, comme api_mapping et label_prototypes.

Format de sortie du LLM

Le LLM doit renvoyer un seul tableau JSON.

Valeurs autorisées :

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

Exemple :

["docs_chunks"]

["api_mapping", "label_prototypes"]

[]

[] n'est utilisé que lorsqu'il est jugé que ce n'est pas un contenu de documentation officielle utile.

Résumé actuel du prompt

Le cœur du prompt de classification doit être le suivant.

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>

Critères de jugement

Il faut transmettre les limites des trois tables au LLM.

Table	Limite prévue
`docs_chunks`	Corps des explications de la documentation officielle, tutoriels, morceaux de référence de classe
`api_mapping`	Comment les noms de fonctions, de classes et de symboles ont changé de Godot 3 à Godot 4
`label_prototypes`	Comment procéder lorsque la façon d’utiliser une fonction, la composition des arguments ou le modèle d’appel ont été entièrement modifiés

Les limites entre api_mapping et label_prototypes sont particulièrement importantes. Si seul le nom change, il s’agit de api_mapping ; si la composition des arguments ou le mode d’appel change, il s’agit de label_prototypes.

Flux de correction JSON

Si le LLM ne renvoie pas correctement un tableau JSON, on renvoie une demande de correction une fois de plus.

L’essentiel de la demande de correction est le suivant.

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 demande de correction échoue également, le fichier est enregistré comme une erreur de classification.

Possibilité de repli hard‑coding

Actuellement, l'étape de classification n'impose pas la sélection d'une table en utilisant un repli hard‑coding basé sur le nom de fichier, le chemin et les expressions régulières.

Si aucune clé API n'est disponible, aucune classification n'est effectuée. Si la réponse de Qwen n'est pas un tableau JSON valide et que la correction échoue également, aucune table n'est choisie aléatoirement ni enregistrée, et l'erreur est consignée.

Enregistrement du débogage

Les résultats de la classification sont enregistrés dans l'état de session sous la forme suivante.

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

Cet enregistrement est utilisé pour identifier la cause lorsque Qwen renvoie une réponse qui n’est pas du JSON, renvoie [] ou renvoie un nom de table invalide.