2026-06-17 Réflexion sur la construction d'un détecteur LLM/RAG pour Godot

Résumé en une phrase

Aujourd'hui, nous avons redéfini la direction du modèle de codage spécialisé pour Godot, passant d'un simple modèle Q&A à un agent SWE de niveau dépôt, et nous avons créé la première implémentation du détecteur RAG basé sur la documentation officielle ainsi que le pipeline de génération de données nécessaires en amont.

Le fil conducteur de la journée

Au départ, l'objectif était « créer un chatbot RAG à partir de la documentation officielle de Godot ». Cependant, au fil des discussions et du travail, l'objectif est devenu plus clair.

Godot Collecte de la documentation officielle  
-> Détecteur RAG basé sur la documentation officielle  
-> Étiquetage du projet Godot sur GitHub  
-> Génération de données SFT/DPO  
-> Modèle de codage Godot 4 basé sur Qwen  
-> Agent SWE au niveau du dépôt

En d'autres termes, l'essentiel d'aujourd'hui n'était pas de créer un seul chatbot, mais d'établir une base de détection/génération de données pour créer un modèle capable de lire et de corriger réellement un projet Godot ultérieurement.

1. Jugement que le modèle Q&A simple est insuffisant

Ce que j'ai d'abord organisé aujourd'hui était la nature de l'objectif du modèle.

Auparavant, nous envisagions de créer un jeu de données de questions / réponses sur Godot 4 et d’entraîner le modèle afin qu’il fournisse de bonnes réponses de code Godot 4. Cependant, en pensant à une requête comme « crée une carte », il ne s’agit pas d’un simple problème de Q & A.

Le flux réel de la requête ressemble davantage à ce qui suit.

Compréhension de la demande de l'utilisateur  
-> Exploration de la structure du dépôt  
-> Recherche du scene/script/ressource associé  
-> Vérification du chemin des assets et du style de code existant  
-> Détermination de la syntaxe/API de Godot 4  
-> Modification du code  
-> Exécution/test/validation  
-> Création du patch

Ce flux n'est pas un problème de génération d'une seule réponse, mais un problème d'agent en génie logiciel. Ainsi, aujourd'hui, nous avons redéfini la direction du modèle du point de vue de SWE-agent trajectory training.

Mots‑clés principaux enregistrés aujourd'hui :

Long-context repository-level software engineering agent training
SWE-agent trajectory training
Godot repo-level patch generation
long-context trajectory dataset

J'ai également organisé les cas de référence.

SWE-agent trajectories
SWE-smith
SWE-Gym
CoderForge-Preview
ACC
RepoBench / CrossCodeEval / RepoCoder
aiXcoder CoLT
godot-dodo
wallstoneai/godot-gdscript-dataset

La conclusion d'aujourd'hui était que de simples Q&A d'instructions sont insuffisantes. Ce qui est finalement nécessaire, c'est le parcours d'exploration, de jugement, de modification et de validation au niveau d'un projet Godot.

Notes associées:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md

2. Résumé de la feuille de route complète de Godot LLM

Ensuite, nous avons réorganisé la feuille de route complète du développement.

Le grand flux a été résumée comme suit.

Données
-> Chatbot RAG de première phase
-> SFT
-> DPO
-> Agent SWE

Si l’on divise les étapes plus en détail, on obtient ce qui suit.

Stage 0. Phase de préparation  
Stage 1. Collecte et structuration des données  
Stage 2. Développement du chatbot RAG de première génération  
Stage 3. Étiquetage des données et création du jeu de données  
Stage 4. Entraînement du modèle  
Stage 5. Développement de l'agent SWE  
Stage 6. Amélioration continue

Dans cette feuille de route, le jugement le plus important est de ne pas considérer le chatbot RAG de première génération comme un simple outil de questions‑réponses. Il faut d’abord créer un classificateur RAG qui agit comme un expert de la documentation officielle de Godot, puis, à l’aide de ce classificateur, étiqueter et transformer les données GitHub avant de les étendre avec SFT/DPO et l’Agent SWE.

En particulier, l’Agent SWE de la Phase 5 ne doit pas être un simple générateur de code, mais doit posséder les capacités suivantes.

Analyse du projet  
Recherche des fichiers nécessaires  
Modification du code  
Vérification du CLI Godot ou du résultat d'exécution  
Analyse des causes d'échec  
Création du patch

Roadmap associée :

docs/roadmaps/2026-06-17-godot-llm-roadmap.md

3. Conception d’une structure de génération de données basée sur le classificateur RAG

Aujourd’hui, une autre décision importante était de « ne pas confier la décision finale du label au LLM ».

Au départ, il était facile de penser que le chatbot RAG pouvait, en regardant le code ou la documentation GitHub, déterminer si le projet utilisait Godot 3 ou Godot 4. Cependant, l’étiquetage influence directement la qualité des données d’entraînement, il est donc risqué de le laisser aux jugements improvisés du LLM.

Nous avons donc structuré l’architecture comme suit.

LLM est une assistance à la génération  
Les étiquettes sont déterminées par le système  
Le JSONL final est assemblé/vérifié par le pipeline Python

Ce que le système doit prendre en charge :

Extraction de symboles  
Consultation de la base de données de mappage API  
Recherche de vecteurs dans la documentation officielle  
Recherche par mot‑clé  
Recherche de prototype d’étiquette  
Scoring d’étiquette  
Calcul de la confiance  
Assemblage final du JSONL  
Validation

Ce que le LLM peut prendre en charge :

Générer un brouillon de code de modification  
Générer une explication  
Générer des questions/réponses SFT  
Générer une mauvaise réponse DPO  
Générer un brouillon de patch  
Assistance à la validation/explication des problèmes

Nous avons également organisé le jeu de données cible en 8 catégories.

version_classification
api_mapping
migration_fix
instruction_sft
dpo_preference
repo_explorer
patch_generation
metadata_verification

Cette règle est devenue le critère de conception du code de post‑traitement RAG que nous avons créé aujourd’hui. C’est également ici que l’on explique pourquoi nous avons séparé api_mapping, symbol_catalog, keyword_index et search_text.

Mémos associés :

docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md

4. Flux MVP du classificateur RAG vers le modèle Qwen 3.6

Le flux MVP entre le classificateur RAG de Godot et le modèle de codage Qwen 3.6 a été documenté séparément.

Flux documenté :

- godot_docs_full.zip Préparation du document original  
- → Chunking initial basé sur chunk_docs.py  
- → Post-traitement dédié à Godot  
- → Mise en place d'une infrastructure de recherche locale  
- → Collecte et structuration des données GitHub  
- → Exécution du classificateur RAG  
- → Création du jeu de données d'entraînement  
- → Qwen 3.6 SFT/DPO

Ici, l'infrastructure de recherche locale ne signifie pas seulement une base de données vectorielle.

Configuration requise:

Vector DB
Keyword Index
Reranker
API Mapping DB
Label Prototype DB

De plus, les données GitHub doivent être intégrées non pas comme de simples extraits de code, mais sous forme de structure au niveau du dépôt.

Entrées requises:

.gd
.tscn
.tres
project.godot
README
repo tree
metadata

J’ai de nouveau organisé l’objectif du premier SFT.

Première réflexion sur Godot 4  
Sortie de base GDScript  
Rejet de l’API Godot 3  
Explication des raisons de la conversion de Godot 3 → 4

Après cela, le DPO devra définir plus clairement les critères de réponses bonnes et mauvaises.

Mauvaise réponse : réponse contenant l'API Godot 3  
Bonne réponse : réponse avec du code pur Godot 4 et des justifications

Note liée :

docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md

5. v1 Découpage de la documentation officielle

Après avoir organisé la conception, nous avons créé un format permettant d'intégrer les données réelles de la documentation officielle dans le RAG.

Le premier livrable créé est le fichier suivant.

work/godot_rag/chunks/docs_chunks.jsonl

Nous avons divisé les 1 570 documents Markdown officiels en fonction des titres et de la longueur, créant ainsi 9 741 fragments.

Résultat :

Input pages: 1,570
Output chunks: 9,741
Max chunk chars: 2,800
Overlap chars: 350

Points positifs de v1 :

J’ai créé des morceaux JSONL de la documentation officielle.
L’analyse JSONL était stable.
Des types de documents de base tels que class_reference, tutorial, migration ont été classés.

Problème de v1 :

Il reste beaucoup de texte résiduel de Sphinx.
Il y avait des morceaux de bruit trop courts.
La structure heading, section, méthode/propriété n’était pas suffisamment préservée.
La référence de classe n’était pas séparée de manière précise par unité d’API.

v1 était l'étape « collecte de la documentation officielle et succès du chunking de base ». C'était le point de départ du MVP de recherche, mais cela ne suffisait pas pour le classificateur d'étiquettes.

6. Post‑traitement v2

Ensuite, nous avons créé postprocess_chunks.py et généré les chunks v2.

Fichier:

work/godot_rag/postprocess_chunks.py
work/godot_rag/chunks/docs_chunks_v2.jsonl

Ce qui a été traité dans v2 :

Suppression du chunk 404  
Suppression des petits chunks de bruit  
Suppression des textes résiduels Sphinx  
Extraction des symboles  
Extraction du nom de classe  
Renforcement de section/type_de_membre/nom_de_membre  
Affichage des chunks liés à la migration

Résultat:

Input chunks: 9,741
Output chunks: 8,778
Dropped 404 chunks: 3
Dropped short/noise chunks: 960
Migration-related chunks: 695

v2 est devenu utilisable comme MVP de recherche RAG basé sur la documentation officielle. Cependant, il était encore insuffisant pour être considéré comme le classificateur final. En particulier, les changements de syntaxe/API tels que move_and_slide, velocity, @export, await n’étaient pas séparés comme critères de jugement indépendants.

7. Direction v3 incorrecte et retour en arrière

Le v3 initialement envisagé consistait à coder en dur certaines API essentielles pour créer des morceaux api_focus.

Exemple:

KinematicBody2D
CharacterBody2D
move_and_slide
@export
await

Cette méthode peut sembler augmenter rapidement les performances de recherche. Mais en réalité, c’était risqué.

Problèmes :

Le moteur de recherche peut être sur‑ajusté aux API choisies par l’utilisateur.
Les API hors de la liste deviennent plus faibles.
Certaines API représentatives peuvent donner l’impression de représenter l’ensemble de l’API Godot.
Les API omises peuvent conduire plus tard à des erreurs d’étiquetage.

Ainsi, la version v3 précédente a été restaurée. Cette décision était importante. À court terme, cela peut sembler une perte, mais en considérant la qualité finale du classificateur, le focus « hard‑coded » sur les chunks était une mauvaise direction.

8. Redesign de v3 basé sur le catalogue

Après la restauration, nous avons changé d’orientation.

Nouveaux principes :

Ne perdez aucun chunk v2.  
Ne créez pas de nouveau chunk focus de manière aléatoire.  
Extrayez automatiquement symbol/catalog/index/mapping de toute la documentation officielle.  
Attachez les informations de renforcement de recherche en tant que métadonnées.

Code ajouté :

work/godot_rag/build_symbol_catalog.py
work/godot_rag/build_keyword_index.py
work/godot_rag/build_api_mapping.py
work/godot_rag/make_chunks_v3.py
work/godot_rag/validate_rag_artifacts.py
work/godot_rag/retrieval_smoke_test.py

Produit généré :

work/godot_rag/catalog/symbol_catalog.jsonl
work/godot_rag/catalog/keyword_index.json
work/godot_rag/catalog/api_mapping.jsonl
work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl
work/godot_rag/validation/validation_report.json
work/godot_rag/validation/retrieval_smoke_test.json

Le fichier complet docs_chunks_v3.jsonl fait environ 189 Mo, ce qui pouvait dépasser la limite de fichier unique de GitHub. Ainsi, nous avons placé dans le dépôt les fichiers découpés, conservés ligne par ligne, et les recombiner localement si nécessaire.

cat work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl \
  > work/godot_rag/chunks/docs_chunks_v3.jsonl

9. v3 validation de la cohérence

Ce qui était le plus important dans v3 était la prévention des omissions. Si un seul chunk de v2 était manquant, les références aux documents officiels pouvaient disparaître plus tard.

C’est pourquoi nous avons créé validate_rag_artifacts.py.

Critères de validation:

v2 chunk_id set == v3 chunk_id set
no missing or extra v3 chunks
catalog/index/mapping references point to existing chunks
search_text is present
no old hardcoded api_focus fields remain

Résultat de la vérification:

status: pass
v2 chunks: 8,778
v3 chunks: 8,778
v2 unique chunk_id: 8,778
v3 unique chunk_id: 8,778
symbol catalog entries: 134,922
keyword index keys: 192,257
api mapping records: 144
v3 chunks with api mappings: 1,900
v3 migration-related chunks: 2,392

De plus, une smoke test basée sur le lexical/mots‑clés a également été effectuée avant l’étape d’embedding.

Requête représentative :

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Résultat a passé les 5 tests.

10. Le plus grand risque découvert aujourd'hui

L'insight la plus importante aujourd'hui était que « ce que l'on extrait beaucoup » et « ce que l'on fait confiance et écrit sur l'étiquette » sont différents.

Lorsque l'on extrait largement sur l'ensemble de la documentation officielle, le rappel s'améliore. Mais si l'on traite tous les résultats avec le même niveau de confiance, l'index des mots‑clés devient contaminé.

Par exemple, ce qui suit est très probablement un élément d'API ou de syntaxe réel.

CharacterBody2D
move_and_slide
FileAccess
@export
await

En revanche, il est probable que ce qui suit soit un mot général du document ou une colonne de tableau.

Returns
See
Tip
MIT
Software
Type

En fait, lors de la vérification du smoke test, nous avons découvert un problème où une colonne de tableau ordinaire comme Type -> EditorSceneFormatImporterFBX2GLTF pouvait être prise comme candidate de mappage d’API. Ce problème a été corrigé en excluant Type des candidats de mappage.

La conclusion tirée ici est claire.

Il est nécessaire d'extraire largement.  
Cependant, il ne faut pas utiliser tout ce qui a été extrait largement comme fait fiable.

11. v3.1 Structure de séparation de la fiabilité réorganisée

Après avoir identifié le risque ci‑above, nous avons conclu qu’il ne fallait pas utiliser v3 tel quel dans le classificateur final d’étiquettes. Ainsi, dans v3.1, le catalogue n’est plus regroupé en un seul bloc, mais séparé par fiabilité et par usage.

Nouvelle structure introduite dans v3.1 :

trusted_api_symbols
syntax_symbols
migration_mappings
mentioned_symbols
candidate_terms
rejected_terms
retrieval_keys
search_text

Nous avons également clairement séparé la signification de chaque champ.

trusted_api_symbols: class reference structure directement vérifiée, class/method/property/signal/constant  

syntax_symbols: éléments de syntaxe vérifiés dans la documentation de la syntaxe GDScript et la documentation de migration  

migration_mappings: mappage de changement de Godot 3 → 4, relation old → new liée à des chunks de référence  

mentioned_symbols: symboles mentionnés dans tutorial/body mais déjà présents dans le catalogue trusted/syntax  

candidate_terms: mots candidats pour aider la recherche recall  

rejected_terms: mots généraux qui ne doivent pas être utilisés comme étiquettes, tels que Returns, See, Tip, MIT, Software

Code ajouté :

work/godot_rag/build_v31_artifacts.py
work/godot_rag/validate_v31_artifacts.py

Produit v3.1 généré :

work/godot_rag/chunks/docs_chunks_v3_1.jsonl
work/godot_rag/chunks/docs_chunks_v3_1.summary.json
work/godot_rag/catalog_v3_1/trusted_api_catalog.jsonl
work/godot_rag/catalog_v3_1/syntax_catalog.jsonl
work/godot_rag/catalog_v3_1/api_mapping.jsonl
work/godot_rag/catalog_v3_1/mention_index.json
work/godot_rag/catalog_v3_1/keyword_index.json
work/godot_rag/catalog_v3_1/v3_1.summary.json
work/godot_rag/validation_v3_1/validation_report.json
work/godot_rag/validation_v3_1/retrieval_smoke_test.json

Résultat v3.1 :

Source v2 chunks: 8,778
Output v3.1 chunks: 8,778
Trusted API catalog entries: 26,318
Syntax catalog entries: 68
API mapping records: 144
Mention index keys: 10,292
Keyword keys: 71,543
Validation status: pass
Retrieval smoke tests: 5 / 5 passed

Partie importante corrigée

Lors du processus de création de la version v3.1, si l’on se fie aux métadonnées v2 pour le champ class_name, des valeurs incorrectes telles que Tutorials, All ou String pouvaient être ajoutées au catalogue de confiance. Nous avons donc reconstruit le canonical class name à partir de l’URL source et du chemin de référence de classe. Après cette correction, les problèmes de casse comme Characterbody2d ont été immédiatement rectifiés en CharacterBody2D.

Une autre vérification cruciale concernait move_and_slide. Avec la méthode d’extraction large, il existait un risque d’ajouter des entrées de confiance falsifiées comme ProjectSettings.move_and_slide. Dans v3.1, nous avons limité la promotion en confiance uniquement aux membres confirmés dans la section structurée des références de classe. En fin de compte, l’entrée de confiance move_and_slide ne subsiste plus que pour la classe réelle de Godot, comme indiqué ci‑dessous.

CharacterBody2D.move_and_slide
CharacterBody3D.move_and_slide

En d'autres termes, ce que nous avons fait aujourd'hui dans la v3.1 n'est pas simplement d'ajouter des champs, mais de le transformer en une « structure qui utilise largement la recherche mais, pour la décision d'étiquette, n'utilise que des bases étroites et fiables ».

12. Validation de la cohérence de la v3.1

Dans la v3.1, les omissions étaient particulièrement dangereuses. En effet, si même un seul des 8 778 morceaux de la v2 était manquant, la base documentaire officielle pouvait disparaître.

Critères de validation:

v2 chunk_id set == v3.1 chunk_id set  
v3.1 unique chunk_id count == 8,778

doc_type répartition maintenue  
legacy suppression du champ mixte  
trusted/syntax/migration vérification de l'intégrité de référence du catalogue

Vérification de l'existence de `search_text`

Résultat de la vérification:

status: pass
errors: 0
warnings: 0
v2 chunks: 8,778
v3.1 chunks: 8,778

J'ai relancé le test de fumée de recherche.

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Le résultat a passé les cinq tests. Cette étape ne signifie pas que « le label final est terminé », mais que la structure v3.1 est suffisamment fiable pour passer au moins à un index vectoriel/mot‑clé MVP.

13. Intégration sur GitHub et organisation des enregistrements

Aujourd’hui, nous avons non seulement créé le code et les livrables de données, mais aussi organisé leur intégration sur GitHub.

Travaux effectués :

configuration du remote  
Division de fichiers volumineux v3  
Push de la branche de travail  
Fusion de l'historique local avec le main distant  
push du main  
Nettoyage du répertoire de documentation

docs_chunks_v3.jsonl fait environ 189 Mo, donc le télécharger tel quel aurait pu dépasser la limite de fichier unique de GitHub. Ainsi, il a été découpé en docs_chunks_v3.part-000.jsonl, docs_chunks_v3.part-001.jsonl, docs_chunks_v3.part-002.jsonl.

De plus, au départ les rétrospectives étaient placées à la racine retrospectives/, mais cela ne correspondait pas à la structure du dépôt existant. Nous avons donc réorganisé la structure des documents comme suit.

docs/research-notes/   Mémo de conception  
docs/roadmaps/         Feuille de route complète  
docs/retrospectives/   Rétrospectives par date  
work/godot_rag/        Code RAG et livrables  
outputs/godot_docs_full/ Résultats du crawling de la documentation officielle

Ajout d’un fichier docs/README.md pour organiser également le rôle du répertoire de documentation.

14. Nettoyage de l’auteur/email Git

Comme indiqué dans le README d’aujourd’hui, le problème de la mise à jour du tableau d’activité GitHub a également été résolu.

Problèmes constatés :

main l’historique contient des e‑mails d’auteur/committer mélangés  
e‑mail de l’hôte local  
e‑mail Naver  
e‑mail GitHub noreply

Direction traitée :

Modifier la configuration Git globale en yyeongjin <appsky1888@gmail.com>  
Unifier l'auteur/committer de l'historique main  
Appliquer au dépôt distant  
Conserver la branche de sauvegarde avant la réécriture

Branche de sauvegarde :

backup/before-author-email-rewrite-2026-06-17

Cette tâche n’est pas directement liée à RAG lui‑même, mais c’était l’une des importantes opérations de consolidation d’aujourd’hui. Elle a servi à préparer le terrain afin que les enregistrements et les commits soient correctement reflétés sur le profil GitHub.

15. Documents créés / organisés aujourd’hui

Principaux documents créés ou organisés aujourd’hui :

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md
docs/roadmaps/2026-06-17-godot-llm-roadmap.md
docs/retrospectives/2026-06-17-godot-rag-judge.md
docs/README.md

J’ai ajouté la section du journal de développement du 17 juin et la préparation des données RAG dans le README.

16. Conclusion actuelle

On peut résumer l’état actuel comme suit.

**Direction :**  
Le modèle Q&A de Godot n’est pas approprié, il faut passer à l’Agent SWE de Godot.

**Données :**  
Le RAG de la documentation officielle doit jouer le rôle de discriminateur pour la génération de données d’entraînement.

**Étiquette :**  
Ce n’est pas le LLM qui décide, mais le pipeline Python.

**RAG :**  
- v2 est un jeu de fragments de base sûr.  
- v3 est un livrable de catalogue intermédiaire largement extrait.  
- v3.1 est le livrable RAG recommandé actuellement, incluant la séparation de la confiance.

**Risque :**  
Il ne faut pas utiliser tous les symboles extraits avec le même niveau de confiance.

Aujourd'hui, le travail n'a pas seulement consisté à créer quelques fichiers, mais aussi à corriger plusieurs fois une direction qui pouvait facilement être erronée. En particulier, les décisions de revenir sur le chunk d'API hard‑coded focus, de détecter le risque de bruit dans broad v3, et de séparer trusted/syntax/migration/mention/candidate/rejected dans v3.1 étaient cruciales.

17. Prochaines tâches

La prochaine tâche n'est pas immédiatement l'étiquetage du code sur GitHub.

Ce qui doit être fait en premier :

Générer des embeddings basés sur le search_text de docs_chunks_v3_1.jsonl
Tester la récupération hybride combinant recherche vectorielle + recherche par mots‑clés
Concevoir un pipeline Python pour déterminer les étiquettes à partir de trusted_api_symbols, syntax_symbols, migration_mappings
Définir le format d'entrée des données de structuration du dépôt GitHub
Concevoir le flux de décision au niveau du dépôt en examinant conjointement .gd, .tscn, .tres, project.godot, README
Connecter le résultat du classificateur RAG à un pipeline de création d'un jeu de données JSONL de 8 types
Une fois le point de terminaison LLM distant prêt, le relier pour assister à la génération de code/modifications, d'explications, de candidats SFT/DPO
Étendre ensuite avec l'apprentissage de trajectoires d'agents SWE basées sur Qwen pour SFT/DPO

La leçon finale d'aujourd'hui est la suivante.

Collecter de nombreux documents est moins important que séparer le niveau de confiance avec lequel on utilise les connaissances rassemblées.