2026-06-18 Réflexion sur la réinitialisation du travail RAG de Godot

État d'aujourd'hui

Hier, j'ai bu environ 1 litre de café dans un café, et aujourd'hui mon état était très mauvais. Je n'ai donc pas pu coder correctement. Cependant, même maintenant, je note les idées qui me sont venues et pourquoi j'ai organisé le travail d'hier.

Parties manquantes dans l'architecture actuelle

Les parties manquantes dans l'architecture actuelle de Godot LLM/RAG sont les suivantes. Ces points devront être améliorés ultérieurement.

## Faiblesse de la couche d'analyse statique
- Aucun mécanisme de validation basé sur l'AST/parseur GDScript
- Le graphe de dépendances du projet Godot est limité
- La validation d'exécution/syntaxe est insuffisante
- La taxonomie des étiquettes reste encore grossière
- La distinction entre les productions LLM et les réponses vérifiées (provenance) est faible
- La conception de la prévention des fuites de données et de la déduplication est insuffisante

Particulièrement, il y a des aspects qui ne peuvent pas être résolus uniquement avec le RAG. La détermination du code Godot n’est pas seulement un problème de recherche de documents, il faut également prendre en compte la syntaxe GDScript réelle, les dépendances des scènes/ressources, la structure du projet et les différences entre les API Godot 3/4. Hier, le flux consistait à découper la documentation officielle, à renvoyer le résultat à un LLM et à recevoir des retours. Cette méthode semblait rapide en apparence, mais les critères de validation ont constamment vacillé.

Pourquoi j’ai récapitulé le travail du 17 juin

Le 17 juin, j’ai confié le découpage à un LLM, puis j’ai renvoyé le résultat à GPT pour obtenir des retours. Cependant, quoi qu’on en dise, cette approche ne semblait pas convenir.

J’ai crawlé la documentation officielle afin de m’appuyer sur l’ensemble de la documentation Godot. Mais, au cours du travail, le LLM, avant d’analyser correctement le document, a jugé certaines API comme « MVP », les a considérées comme importantes, a codé en dur certains mots‑clés ou a renforcé excessivement le contexte environnant. Ainsi, au lieu d’un RAG basé sur l’ensemble de la documentation officielle, le système est devenu un moteur de recherche centré sur quelques mots‑clés.

Le problème n’était pas simplement que le résultat ne me plaisait pas. Sans que je vérifie moi‑même, le LLM a créé ses propres critères, a généré des fichiers selon ces critères, puis a évalué les résultats pour prendre la décision suivante. Cela a conduit à des hallucinations, car la structure du document source n’était pas consultée, et plus tard le LLM ne savait plus quel fichier avait été créé selon quel critère.

À plus grande échelle, on a observé que ChatGPT ou Codex réduisaient ou modifiaient librement le périmètre sans que je le leur indique. Je voulais simplement voir la structure basée sur l’ensemble de la documentation officielle, pas « quelques API MVP » à coder en dur. Pourtant, le LLM a, de son côté, décidé « si c’est un MVP, voici ce qui est essentiel », et a produit la prochaine sortie avant même que l’étape précédente ne soit terminée.

Le motif problématique était le suivant.

L'utilisateur souhaite une analyse de la structure basée sur la documentation officielle complète  
-> Le LLM définit arbitrairement la portée du MVP  
-> Il considère certaines API comme essentielles  
-> Il commence par le codage en dur / le renforcement excessif / la création du catalogue  
-> Il crée les livrables de l'étape suivante avant la validation  
-> Le résultat est présenté sous forme de chiffres convaincants  
-> En réalité, la structure originale et les critères d'étiquetage sont contaminés

Ce n’est pas simplement une erreur d’implémentation, mais un problème de méthode de travail. ChatGPT ou Codex ont tendance à supposer qu’une réponse existe déjà même si aucune réponse n’est encore disponible, et à passer à l’étape suivante avant de verrouiller l’étape en cours. Cela donne l’impression d’écouter les instructions, mais en réalité ils réinterprètent le périmètre des consignes, l’ignorent complètement, ou essaient d’abord de créer une « forme finale qui semble bonne ».

Dans ce travail, le point particulièrement dangereux était que le LLM ne distinguait pas correctement la fiabilité des livrables intermédiaires qu’il produisait. Des faits vérifiés dans la documentation officielle, des mots capturés accidentellement par des expressions régulières, des règles approuvées directement par l’utilisateur, et des informations de renforcement supposées par le LLM étaient tous mélangés. Lorsque l’on a demandé au LLM d’évaluer le résultat dans cet état, le flux s’est terminé par le LLM qui rationalise de manière plausible ce qu’il a lui‑même créé.

Pourquoi le livrable de chunking a été vidé

Aujourd’hui, j’ai organisé le fichier lié au chunking RAG que j’avais créé hier.

Les éléments organisés sont les suivants.

v1 docs_chunks.jsonl  
v2 docs_chunks_v2.jsonl  
v3/v3.1 catalog/index/mapping livrable  
Script d'ébauche de regroupement/post-traitement/vérification  
Ébauche initiale RAG chat/index

Au départ, je pensais que seuls les problèmes de v3/v3.1 étaient à considérer, mais en y repensant, il était également nécessaire de revoir les racines de v1 et v2. En fait, il aurait fallu analyser les chunks eux‑mêmes. Par exemple, il fallait d’abord examiner comment la référence de classe Godot est réellement structurée, comment les méthodes/propriétés sont présentées dans la documentation source, et comment le résultat de la conversion Sphinx se dégrade.

Cependant, dans la pratique, la génération du résultat de chunking a précédé l’analyse de la documentation source. En conséquence, v1 ressemblait à un fragment basé sur le nombre de caractères, tandis que v2 était une forme à laquelle on avait ajouté un post‑traitement. En surface, on voyait des chiffres tels que le nombre de chunks, le succès du parsing JSONL, la répartition des doc_type, mais la question réellement importante – « Ce chunk peut‑il être utilisé comme preuve pour distinguer Godot 3/4 ? » – n’a pas été suffisamment vérifiée.

En particulier, il fallait vérifier que des structures comme CharacterBody2D.move_and_slide dans la référence de classe restent stables, que des propriétés comme velocity soient correctement séparées, et comment extraire les relations ancien/nouveau dans la documentation de migration. Si l’on attribue des noms tels que trusted_api_symbols, syntax_symbols, api_mapping sans avoir effectué ces vérifications, on ne fait que créer des données polluées qui semblent plausibles.

Ainsi, aujourd’hui, j’ai vidé les productions de chunking jusqu’à v1/v2. Ce n’est pas un abandon du travail, mais une mise au point afin de ne plus appeler une ligne de base erronée une « ligne de base ».

Conclusion du jour

La conclusion du jour est simple.

Il faut recommencer le chunking.  
Avant cela, il faut d'abord analyser la structure des documents originaux `outputs/godot_docs_full/pages`.  
Il ne faut pas utiliser les livrables intermédiaires générés par le LLM comme base de l'étape suivante sans validation.

Je n’ai même pas vérifié, mais si le LLM prend des décisions de son propre chef, sans même regarder correctement la source, et ajoute en plus des hallucinations, il finit par ne plus savoir ce qu’il a fait. Dans cet état, si l’on continue à créer des fichiers, seuls les fichiers de débogage s’accumulent et on ne sait plus quel est le critère.

À l’avenir, je ne ferai plus confiance à ChatGPT ou à Codex pour « étendre et implémenter de manière autonome dans la bonne direction ». En particulier, pour des tâches où le critère est crucial, comme les jeux de données, les annotateurs ou les détecteurs RAG, les principes suivants sont nécessaires.

Si le LLM définit arbitrairement la portée du MVP, interrompez.  
Si du code dur non approuvé par l'utilisateur est introduit, interrompez.  
Si vous créez des livrables sans analyser la structure d'origine, interrompez.  
Si vous passez à l'étape suivante sans rapport de validation, interrompez.  
Si la provenance des productions du LLM et des réponses validées se mélange, interrompez.

Si on recommence demain, la première tâche n’est pas de créer un nouveau catalogue.
Il faut d’abord analyser godot_docs_full lui‑même.
C’est‑à‑dire, vérifier la structure réelle des Markdown de la documentation officielle présents dans outputs/godot_docs_full/pages, puis reconsidérer, sur la base de cette structure, comment créer les unités de chunks.

La question à se poser maintenant n’est pas « Quel API ajouter en premier ? », mais elle est plus proche de la suivante.

Quel modèle de structure possède la documentation de référence des classes dans **godot_docs_full** ?  
Les listes de méthodes/propriétés/signaux/constantes peuvent‑elles être séparées de manière fiable à partir du Markdown source ?  
Quelle forme ont les tableaux, listes et phrases de la documentation de migration ?  
Les documents tutoriels ne doivent‑ils pas utiliser les mêmes critères de regroupement que la référence des classes ?  
Faut‑il définir des unités de regroupement différentes selon le type de document ?  
Parmi les unités de page, de section et de membre d’API, laquelle doit être prise comme regroupement de base ?  
Quel rapport de validation doit‑on définir avant de procéder au regroupement ?

En fin de compte, la tâche suivante n’est pas de « recréer le RAG », mais d’analyser godot_docs_full et de recommencer la conception des unités de chunks adaptée à la documentation officielle de Godot. Ce n’est qu’ensuite qu’il faudra refaire le chunking.