2026-06-25 Analyse de la source et rétrospective de la classification Markdown

Aujourd'hui, j'ai de nouveau organisé les critères de division du Markdown de la documentation officielle en trois tables JSONL.

Au départ, j'avais envisagé de diviser le Markdown de la documentation officielle de Godot en trois tables : docs_chunks, api_mapping, label_prototypes. Cependant, alors que les rôles de docs_chunks et api_mapping étaient clairement définis, la frontière d’utilisation de label_prototypes était floue.

Au début, les limites entre les trois tables étaient indistinctes. En revoyant le flux, j'ai compris que les trois tables servent toutes à classer le Markdown de la documentation officielle en JSONL et à stocker le résultat.

La conclusion que j'ai tirée est la suivante :

docs_chunks constitue la base de la documentation officielle de Godot 4.
api_mapping est la cible JSONL qui enregistre comment les noms de fonctions, de classes et de symboles ont changé de Godot 3 à Godot 4.
label_prototypes est la cible JSONL qui décrit comment écrire les cas où la façon d’utiliser une fonction, sa composition d’arguments ou son modèle d’appel a été entièrement modifié.

À l’avenir, j’analyserai les projets Godot par unité de système de fichiers. Les fichiers .gd, .tscn, .tres, project.godot, etc., seront découpés en fragments AST/code, et les références JSONL de la documentation officielle nécessaires seront utilisées. Ensuite, j’appellerai Qwen 3.6 à la demande pour déterminer si le fragment provient de Godot 3, de Godot 4, s’il nécessite une migration, ou s’il peut être utilisé comme donnée d’explication de code.

Le résultat de ce jugement sera stocké dans la base de données de scores, et le système de fichiers sera classé par projet en Godot 3 / Godot 4 / mixte / inconnu. Par la suite, les systèmes de fichiers classés serviront de source pour concevoir le SFT et le DPO.

Roadmap associée :

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

Réinitialisation de la classification Markdown

Aujourd'hui, j'ai abandonné les résultats de la classification Markdown → JSONL.

La raison est que, lors de l’étape de classification, seules les 3000 premiers caractères du Markdown étaient transmis au LLM, au lieu du document complet. L’intention et la demande de l’utilisateur étaient de classer l’ensemble de la documentation officielle dès le départ. Cependant, la portée du code généré par le LLM était arbitrairement limitée à la partie initiale, et je ne l’ai pas remarqué à temps. Certaines sections de la documentation ne révèlent pas leur nature avec seulement le début, et notamment les frontières entre api_mapping et label_prototypes exigent de vérifier s’il s’agit d’un changement de nom de fonction/symbole ou d’un changement de mode d’utilisation/arguments/modèle d’appel.

Critères révisés :

La classification Markdown doit recevoir le nom du fichier ainsi que le texte complet du Markdown.
On ne choisit pas de table en se basant uniquement sur un extrait du début.
Les anciens fichiers JSONL et les données insérées dans PostgreSQL sont considérés comme le résultat d’un critère erroné et sont tous supprimés.
Après avoir vidé la base de données et les JSONL, la classification recommence.

Résultat de la réinitialisation :

godot_rag.docs_chunks : 0 entrée
godot_rag.api_mapping : 0 entrée
godot_rag.label_prototypes : 0 entrée
godot_rag.ingest_reports : 0 entrée
Suppression des fichiers JSONL locaux
Redémarrage de l’application Streamlit

Dans ce travail, une erreur similaire s’est reproduite.

Ce n’est pas que l’utilisateur ait mal conçu les choses dès le départ, mais le code et la documentation générés par le LLM ont divergé de l’intention de l’utilisateur, et cette différence n’a pas été détectée à temps. Ce n’est pas simplement un oubli ponctuel ; lors de la clarification des frontières des tables et du flux de données, des oublis similaires se sont répétés. Comme on le dit, les erreurs récurrentes font partie du processus d’apprentissage, il faut donc y prêter davantage d’attention.

En particulier, il y avait un problème de rédiger la documentation comme si les schémas et flux non encore définis étaient déjà fixés, ou de conclure le document sans vérifier d’abord correctement l’implémentation. Même au moment où docs_chunks, api_mapping et label_prototypes devaient être traités au même niveau, une table était décrite comme ayant un flux spécial, ce qui a brisé la cohérence du document.

Dorénavant, la rédaction de la documentation sera presque une procédure obligatoire à chaque étape du travail. Le but de la documentation n’est pas seulement de faire un récapitulatif visuel, mais de vérifier sur quelle base on prend les décisions. Dès qu’un code ou une donnée change, il faut enregistrer le critère qui a conduit à ce changement, afin d’éviter de répéter la même erreur.

Si, cette fois encore, je n’avais pas documenté la structure du code et que j’avais continué, le problème aurait pu être découvert plus tard. En rédigeant le document sur la méthode de classification du LLM, j’ai constaté que le code ne transmettait que les 3000 premiers caractères du Markdown au lieu du document complet, comme le demandait l’utilisateur. J’ai alors pu corriger le code pour transmettre le Markdown entier. Cette expérience confirme que la documentation n’est pas un simple récapitulatif, mais un moyen de vérifier que le comportement réel du code correspond à l’intention de l’utilisateur.

Observation de l’interruption de RunPod et de la reprise de la conversion

Lors de la conversion Markdown → JSONL, le serveur RunPod s’est arrêté de façon inattendue, interrompant également la conversion en cours dans l’application web locale. Après avoir relancé l’application Streamlit, j’ai vérifié si l’état précédent était conservé ou si tout recommençait à zéro.

Les critères d’observation étaient l’état par fichier stocké dans state.json et le « Latest Processing Log » de l’application web. Les preuves clés avant et après le redémarrage sont les suivantes :

Avant le redémarrage, l’état était done 47, deferred 7, converting 1, pending 1515.
Le fichier en cours de traitement était pages/classes__class_astar3d__23ef6ac2.md.
Après le redémarrage, le journal affichait 앱 재시작 후 자동 이어하기를 일시정지함 (pause de la reprise automatique après le redémarrage de l’application).
Ensuite, le journal indiquait 처리 중이던 파일을 pending으로 되돌림 (retour du fichier en cours vers l’état pending), le même fichier pages/classes__class_astar3d__23ef6ac2.md.
Lors de la relance, le journal montrait 기존 분류 재사용 (réutilisation de la classification existante) pour ce fichier, puis il a été terminé avant de passer au suivant.
Les fichiers suivants pages/classes__class_astargrid2d__51463855.md, pages/classes__class_atlastexture__336f837e.md, pages/classes__class_audiobuslayout__a2e0df1f.md ont été traités séquentiellement, augmentant le compteur done.

Ce que cette observation confirme :

Le résultat complet de la conversion n’a pas été réinitialisé.
Le fichier en cours a été remis en sécurité à l’état pending.
Les fichiers déjà terminés n’ont pas été retraités.
Les classifications existantes ont été réutilisées.
La reprise a continué à partir du point d’interruption.

Cependant, lorsqu’un serveur RunPod s’arrête de façon inattendue, le flux de conversion peut rester bloqué ou être interrompu pendant longtemps. Pour les longues tâches de conversion, il est nécessaire de configurer des alertes permettant de détecter rapidement :

L’indisponibilité du serveur RunPod
Un timeout d’API ou des réponses 5xx répétées
La fermeture du processus de l’application Streamlit
Un fichier restant trop longtemps au même stade du tableau
Une pause de la reprise automatique due au redémarrage de l’application