Schéma et architecture du classificateur RAG de la documentation officielle de Godot

Date de rédaction : 21 juin 2026

Objectif

Organiser l'architecture de référence permettant de connecter l’ensemble de la documentation officielle de Godot via le flux JSONL → PostgreSQL → Retriever → Validator → Qwen 3.6. Ce document n’est pas un guide d’implémentation pour créer les données d’entraînement, mais une spécification de conception définissant comment structurer les fichiers Markdown déjà rassemblés dans outputs/godot_docs_full/pages afin de les transformer en une base de données consultable.

Données d’entrée actuelles

Les résultats de la collecte de la documentation officielle se trouvent sous le répertoire outputs/godot_docs_full du dépôt.

Ligne de base actuelle :

Pipeline complet

1. Le crawler récupère la documentation officielle de Godot sur Internet.
2. Les résultats sont enregistrés sous forme de Markdown page par page.
3. Le Markdown est normalisé et enrichi de métadonnées avant d’être converti en enregistrements JSONL.
4. Les JSONL sont injectés dans PostgreSQL.
5. PostgreSQL stocke séparément les fragments de documents, les mappings d’API et les prototypes d’étiquettes.
6. Lorsqu’un utilisateur demande une analyse du code source de Godot, l’AST Parser structure le code du projet.
7. Le Retriever recherche les preuves dans PostgreSQL en se basant sur la question de l’utilisateur et les résultats de l’analyse AST.
8. Le Validator regroupe la question, les résultats AST et les preuves trouvées, puis les transmet à Qwen 3.6.
9. Qwen 3.6 n’est pas le juge final ; il utilise les preuves validées pour formuler la réponse.
10. Le Validator vérifie la provenance, le format et les motifs interdits de la réponse avant de la renvoyer à l’utilisateur.

Conversion du Markdown vers JSONL

Les fichiers pages/*.md sont les sources lisibles par les humains, mais ils sont trop volumineux pour le RAG. Ainsi, le script de conversion découpe chaque page en sections/membres d’API/exemples, tout en conservant l’URL d’origine et le type de document.

Règles de normalisation communes

Produits JSONL

Schéma de docs_chunks.jsonl

{
  "chunk_id": "godot-stable:classes/class_node.html#description:0001",
  "doc_version": "stable",
  "source_url": "https://docs.godotengine.org/en/stable/classes/class_node.html",
  "source_file": "outputs/godot_docs_full/pages/classes__class_node__....md",
  "source_sha256": "...",
  "doc_type": "class_reference",
  "symbol": "Node",
  "section_path": ["Node", "Description"],
  "heading": "Description",
  "content": "Nodes are Godot's building blocks...",
  "code_blocks": [],
  "language_tags": ["gdscript"],
  "godot_version_tags": ["4.x", "stable"],
  "api_symbols": ["Node", "_ready", "_process", "queue_free"],
  "token_count": 420,
  "metadata": {
    "status": "copied_old",
    "bytes": 12345
  }
}

Champ obligatoire :

Schéma api_mapping.jsonl

{
  "mapping_id": "godot3-to-4:kinematicbody2d-to-characterbody2d",
  "source_api": "KinematicBody2D",
  "target_api": "CharacterBody2D",
  "change_type": "rename_or_replacement",
  "godot_from": "3.x",
  "godot_to": "4.x",
  "confidence": "verified_from_docs",
  "evidence_chunk_ids": [
    "godot-stable:tutorials/migrating/upgrading_to_godot_4.html#..."
  ],
  "match_terms": ["KinematicBody2D", "CharacterBody2D"],
  "notes": "Godot 4 character movement node replacement candidate.",
  "negative_patterns": ["do not suggest KinematicBody2D for Godot 4 projects"]
}

Principes :

Schéma label_prototypes.jsonl

{
  "prototype_id": "label:godot3-api-in-godot4:kinematicbody2d",
  "label": "godot3_api_in_godot4",
  "task_type": "version_classification",
  "input_pattern": "extends KinematicBody2D",
  "expected_finding": "Godot 3 style physics body API detected.",
  "recommended_action": "Use CharacterBody2D or CharacterBody3D depending on project dimension.",
  "evidence_mapping_ids": [
    "godot3-to-4:kinematicbody2d-to-characterbody2d"
  ],
  "evidence_chunk_ids": [],
  "severity": "high",
  "validator_rules": {
    "requires_ast_symbol": "KinematicBody2D",
    "forbidden_answer_terms": ["KinematicBody2D is recommended in Godot 4"]
  }
}

Label candidates:

Ébauche du schéma PostgreSQL

PostgreSQL part du principe d’utiliser pgvector. La recherche par mots‑clés utilise tsvector ou un index trigramme.

docs_chunks

Indexes:

api_mapping

Indexes:

label_prototypes

Indexes:

Entrée/Sortie du parseur AST

Le parseur AST transforme le code source de l’utilisateur en une structure interrogeable avant de le transmettre à un LLM. Les cibles initiales sont .gd, .tscn, project.godot.

Entrée

Sortie du schéma

{
  "project_id": "local-analysis-...",
  "godot_project": {
    "config_version": 5,
    "features": ["4.4", "Forward Plus"]
  },
  "files": [
    {
      "path": "scripts/player.gd",
      "language": "gdscript",
      "extends": "CharacterBody2D",
      "class_name": "Player",
      "symbols": ["CharacterBody2D", "Input", "move_and_slide"],
      "annotations": ["@onready"],
      "version_signals": ["godot4_annotation_syntax"],
      "diagnostics": []
    }
  ],
  "version_evidence": {
    "godot4": ["config_version=5", "@onready"],
    "godot3": []
  }
}

Champ d'extraction initial :

Fonctionnement du Retriever

Le Retriever est une couche qui sélectionne les preuves avant le LLM.

1. Extraire l'intention et la tâche cible à partir de la question de l'utilisateur.
2. Récupérer les symboles API, les signaux de version et les chemins de fichiers depuis le résultat de l'AST Parser.
3. Effectuer d'abord une recherche exacte dans api_mapping.
4. Effectuer simultanément un filtrage des symboles API + recherche par mots‑clés + recherche vectorielle dans docs_chunks.
5. Récupérer les libellés similaires et les règles de validation depuis label_prototypes.
6. Trier les résultats de recherche en bundles de preuves.

Bundle de preuves :

{
  "query_id": "analysis-...",
  "task_type": "version_classification",
  "ast_summary": {},
  "doc_evidence": [],
  "api_mapping_evidence": [],
  "label_evidence": [],
  "retrieval_scores": {
    "exact_api_hits": 2,
    "keyword_hits": 8,
    "vector_hits": 12
  }
}

Séparation des rôles entre Validator et Qwen 3.6

Qwen 3.6 est le modèle qui lit les preuves récupérées et organise la réponse. Le Validator est responsable du label final, de l’adoption des preuves et de la validation des motifs interdits.

Éléments que le Validator doit vérifier :

Ordre d’injection

1. Vérifier outputs/godot_docs_full/summary.json et failed.json.
2. Charger manifest.json et pages/*.md.
3. Créer le rapport de normalisation Markdown.
4. Générer docs_chunks.jsonl.
5. À partir des documents migration/class, créer les candidats api_mapping.jsonl.
6. Générer label_prototypes.jsonl à partir des règles approuvées et des cas représentatifs.
7. Insérer (upsert) dans PostgreSQL uniquement les enregistrements qui ont passé la validation du schéma JSONL.
8. Générer les embeddings et mettre à jour l’index vectoriel.
9. Mettre à jour l’index des mots‑clés et l’index exact.
10. Vérifier les résultats du Retriever avec des questions d’exemple.

Checklist de validation de la qualité

Priorités de mise en œuvre

1. Rédiger le rapport d’analyse de la structure pages/*.md.
2. Écrire le script de conversion docs_chunks.jsonl.
3. Écrire le script de validation du schéma JSONL.
4. Rédiger le DDL PostgreSQL.
5. Injection et validation de la recherche docs_chunks.
6. Génération des candidats api_mapping et rédaction du flux d’approbation manuelle.
7. Création du jeu de labels initial label_prototypes.
8. Extraction des champs minimaux avec l’AST Parser.
9. Exportation du bundle de preuves du Retriever.
10. Connecter la boucle de synthèse des réponses Validator + Qwen 3.6.

Principes fondamentaux

• Le Markdown original de la documentation officielle n’est pas modifié et est conservé.
• Le JSONL est considéré comme un artefact intermédiaire reproductible.
• La base de données doit toujours conserver le chemin d’accès original, l’URL d’origine, le hash et la version du script de conversion.
• Empêcher le LLM d’inventer des labels.
• Le jugement Godot 3/4 repose sur la combinaison du signal AST, du mapping API et des preuves de la documentation officielle.
• Les candidats incertains ne sont pas directement utilisés comme données d’entraînement mais restent à l’état candidate.
• Qwen 3.6 agit comme organisateur de réponses, les critères de jugement étant détenus par le Retriever et le Validator.

Prochaine tâche

L’étape suivante consiste à analyser un échantillon de la structure Markdown dans outputs/godot_docs_full/pages. Étant donné que les références de classe, les migrations et les tutoriels ont des structures différentes, il faut d’abord définir des stratégies de chunking spécifiques à chaque type de document plutôt que d’appliquer une règle de chunking unique.