Rétrospective du 22 juin 2026

Aujourd'hui, au lieu d'insérer directement la documentation officielle de Godot en Markdown dans le RAG, j'ai d'abord créé un flux qui la convertit en JSONL structuré pour vérification. Au début, je ne savais pas comment découper le Markdown de la documentation officielle, mais en créant une interface de conversion et en visualisant les résultats par fichier, cela est devenu beaucoup plus simple.

Convertisseur Markdown → JSONL

Lorsque vous téléversez un fichier Markdown de la documentation officielle de Godot, il classe les tables cibles via l'API Qwen et répartit les résultats en JSONL pour docs_chunks, api_mapping et label_prototypes.

Au départ, je pensais simplement lire le Markdown et l'insérer directement dans la base de données, mais cela rendait difficile de savoir quel document allait dans quelle table. J'ai donc d'abord généré du JSONL comme produit intermédiaire, puis j'ai comparé les résultats de la conversion avec le texte original à l'écran.

Les avantages de cette approche sont les suivants :

• Vous pouvez comparer le Markdown original avec le JSONL converti.
• Vous pouvez voir dans quelle table (docs_chunks, api_mapping, label_prototypes) chaque document est placé.
• Vous pouvez filtrer les documents mal classés ou les résultats vides avant de les insérer dans la base de données.
• Vous pouvez régénérer le JSONL et le comparer si vous modifiez les règles de conversion plus tard.

Vérification des résultats de conversion

Le convertisseur affiche le nombre de fichiers JSONL enregistrés et le nombre d’erreurs à l’écran. Dans la vue d’aujourd’hui, les résultats de docs_chunks étaient déjà accumulés, tandis que api_mapping, label_prototypes et les fichiers d’erreur étaient encore vides.

Cet état n’est pas anormal ; les premiers documents sont majoritairement des documents explicatifs, il est donc logique qu’ils aillent dans docs_chunks. L’essentiel est que les résultats ne sont pas directement injectés dans la base de données, mais d’abord sauvegardés en JSONL pour être vérifiés par une personne.

Aperçu du JSONL et affichage sous forme de tableau

Les résultats JSONL peuvent être visualisés à l’écran sous forme de JSON ou de tableau. Par exemple, un enregistrement docs_chunks possède des champs tels que chunk_id, doc_version, source_url, source_file, source_sha256, doc_type, section_path, heading, content, code_blocks, api_symbols, token_count, metadata.

En le voyant ainsi, c’est bien plus pratique que de simplement garder le fichier Markdown. En particulier, voir chunk_id et source_sha256 côte à côte facilite le suivi ultérieur de l’origine de chaque fragment. Dans le RAG, le point le plus crucial est de ne pas perdre la provenance des preuves ; le produit intermédiaire JSONL peut jouer ce rôle.

Journal de conversion

J’ai également consulté le journal de conversion par fichier. On pouvait voir quel fichier avait démarré, comment Qwen l’avait classé, et combien d’enregistrements valides étaient produits.

Dans l’exemple vérifié aujourd’hui, le document about__complying_with_licenses a été classé dans docs_chunks et découpé en plusieurs fragments. À l’inverse, des documents comme 404 n’avaient aucune table cible et ont été ignorés. Un tel journal est indispensable pour retracer les problèmes lorsqu’on traitera les 1 570 documents au total.

Configuration locale de PostgreSQL

Après avoir créé le JSONL, j’ai préparé la base de données locale PostgreSQL afin d’y importer les données. J’ai lancé un conteneur basé sur pgvector/pgvector:pg16 et créé les tables docs_chunks, api_mapping, label_prototypes et ingest_reports.

Ce qui a été particulièrement important aujourd’hui, c’est que le schéma de la base de données ne doit pas diverger des noms de champs du JSONL. Si la base de données ajoute des colonnes arbitrairement, le contrat JSONL devient flou et le convertisseur et l’ingesteur peuvent finir par fonctionner sur des bases différentes. Ainsi, les colonnes de charge utile de la base de données sont alignées sur le schéma JSONL, tandis que les colonnes d’exploitation de la base sont limitées à id, embedding, search_tsv, created_at.

J’ai exécuté la base de données locale, testé des insertions et des recherches avec des exemples de JSONL, et effectué des tests de rollback. Bien que je n’aie pas encore injecté l’ensemble des documents, le chemin de JSONL → PostgreSQL est désormais beaucoup plus clair.

Décision du jour

Le flux que j’ai mis en place aujourd’hui n’est pas le classificateur final du RAG, mais il représente une avancée significative à ce stade.

Auparavant, il était incertain comment gérer le Markdown de la documentation officielle, et passer directement au chunking ou à l’injection en base de données risquait de perdre la structure. Aujourd’hui, en insérant une étape de conversion/validation JSONL, nous disposons d’un livrable intermédiaire vérifiable par l’humain.

En conclusion, la suite logique du processus semble être celle décrite ci‑dessus.

Documentation officielle Godot Markdown  
-> Conversion JSONL  
-> Aperçu/validation JSONL  
-> Injection PostgreSQL  
-> Validation de recherche Retriever  
-> Résumé des réponses Validator/Qwen

Après demain, il faut vérifier quel pourcentage de docs_chunks, api_mapping, label_prototypes apparaît lorsqu’on convertit les 1 570 documents en totalité. En particulier, api_mapping et label_prototypes ne doivent pas être créés librement par Qwen, il faut donc ne pas se fier aveuglément aux résultats générés automatiquement et prévoir une étape d’approbation/validation.

Mesure de la vitesse de traitement

En calculant la vitesse de conversion supplémentaire, il semble qu’il faut environ 42 heures pour convertir les 1 570 fichiers Markdown en JSONL.

Le temps de traitement réel jusqu’à présent était d’environ 1 heure 9 minutes. Pendant ce temps, un total de 43 fichiers a été traité, soit 39 done et 4 deferred. La vitesse moyenne est d’environ 1,6 minute par fichier.

Temps de traitement réel : environ 1 heure 9 minutes  
Fichiers actuellement traités : done 39 + deferred 4 = 43  
Vitesse moyenne : environ 1,6 minute par fichier  
Temps estimé pour la conversion de 1 570 éléments au total : environ 42 heures

Au début, je pensais qu'en pratique c'était environ un par minute, mais selon les journaux réels, cela prend un peu plus de temps. Il pourrait être difficile de terminer la conversion de 1 500 éléments aujourd'hui, il faut donc continuer à enregistrer la vitesse de traitement ainsi que le nombre de fichiers échoués/en attente.

Plan de validation suivant

Il est probable que demain et après-demain ne seront pas disponibles, donc il sera difficile de poursuivre immédiatement. Cependant, le travail à reprendre plus tard est en grande partie organisé.

Tout d'abord, il faut injecter les fichiers JSONL déjà créés pendant la collecte et la conversion dans PostgreSQL local. Jusqu'à présent, le convertisseur que nous avons développé se concentrait sur la division du Markdown en JSONL pour docs_chunks, api_mapping et label_prototypes. L'étape suivante consiste à insérer ces JSONL dans la base de données réelle et à vérifier s'ils sont consultables.

Ensuite, nous prévoyons de valider légèrement le flux de travail décrit dans docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md à l'aide d'un petit script Python.

source code
-> AST Parser
-> Retriever
-> evidence JSONL / evidence bundle
-> appel API Qwen 3.6
-> vérification de la réponse

En d'autres termes, on insère un code source Godot aléatoire dans un script Python et on vérifie si l'AST Parser extrait les symboles et les indicateurs de version. On place ensuite le résultat dans le Retriever afin qu'il récupère les extraits de documentation officielle ou les mappages d'API pertinents depuis PostgreSQL, puis on prévoit de vérifier ponctuellement la réponse obtenue lorsqu'on transmet le bundle JSONL/évidence à l'API Qwen 3.6.

Ce processus n'est pas une automatisation complète, mais ressemble à une petite validation end‑to‑end visant à vérifier que chaque étape s'enchaîne réellement. Il faut notamment vérifier si Qwen répond de mémoire ou s'il répond en se basant sur les preuves fournies par le Retriever.

Réflexions sur la mise en public et le passage en privé d'un dépôt

Récemment, j'ai rendu ce dépôt public une fois, puis je l'ai de nouveau rendu privé. La raison semblait simple. Je ne voulais pas montrer mes compétences.

Je sens que mes compétences actuelles sont encore très médiocres. Cependant, en même temps, j’ai pensé à créer un modèle dédié à Godot, le télécharger sur Hugging Face, et l’utiliser comme point de départ pour développer des vidéos de cours, l’université, un portfolio, la renommée et d’autres domaines. D’une certaine manière, cela ressemble à un rêve trop idéaliste. Néanmoins, si quelqu’un pouvait utiliser mes rétrospectives et mes notes de travail comme tremplin pour grandir, je me suis demandé si je ne pourrais pas moi aussi progresser plus rapidement dans ce processus.

En fait, j’ai encore une envie de ne pas publier. J’ai peur que ce que j’ai créé ne paraisse pas assez profond, et, à l’inverse, je me méfie que la partie où j’ai assemblé plusieurs connaissances, même superficiellement, pour les rendre plus simples, ne soit simplement copiée par quelqu’un. Ce n’est pas tant que le résultat soit une technologie impressionnante, mais plutôt que la trace de toutes mes réflexions et connexions jusqu’à présent se révèle en entier, ce qui me semble lourd à porter.

J’ai également configuré des PR et un pipeline CI/CD, mais le flux que j’imaginais était le suivant : lorsqu’une PR apparaît dans le workflow GitHub, un endpoint LLM local déployé sur Oracle Cloud effectue automatiquement la revue de la PR. Comme Oracle Cloud offre un environnement de 24 Go de VRAM, je pensais pouvoir faire tourner presque tous les modèles locaux et ainsi intégrer le LLM hébergé à l’automatisation de la revue de code. Cependant, j’ai perdu mon compte Oracle Cloud, ce qui rend ce flux difficile à réutiliser pour le moment. RunPod, quant à lui, présente l’inconvénient de devoir être reconfiguré à chaque fois que l’on l’utilise pour la validation des PR. Ainsi, pour l’instant, il semble plus réaliste de se concentrer sur le travail manuel et la documentation, et de remettre à plus tard l’automatisation des revues de PR basées sur le LLM.

Conclusion semble être celle‑ci. En fait, même s’il est très probable que personne ne regarde, j’étais extrêmement prudent·e à l’idée d’être critiqué·e. Mais même si quelqu’un s’inspire de mon travail ou le reprend, je dois l’utiliser comme tremplin pour devenir encore meilleur·e. La décision de publier doit encore être prise avec prudence, mais il ne faut pas arrêter d’enregistrer par peur.