Godot RAG classificateur configuration PostgreSQL locale

Date de rédaction : 22 juin 2026

Objectif

Configurer une base de données PostgreSQL locale pour le classificateur RAG de la documentation officielle de Godot. Le flux de base est le suivant.

JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6

L'objectif de l'étape actuelle n'est pas de créer des données d'entraînement, mais de rendre possible la reproduction locale d'une base de données de références basée sur la documentation officielle. Conservez la colonne payload de la table avec le même nom que le schéma JSONL, et ne conservez que les colonnes dérivées nécessaires à la recherche/stockage, telles que id, embedding, search_tsv, created_at.

Document de conception de référence :

docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md

Configuration de la base de données locale

Fichier Docker Compose :

infra/postgres/docker-compose.yml

Image utilisée :

pgvector/pgvector:pg16

Informations de connexion :

Élément	Valeur
base de données	`godot_rag`
utilisateur	`godot_rag`
mot de passe	`godot_rag_local`
hôte	`localhost`
port	`5432`

URL de base pour le développement local :

postgresql://godot_rag:godot_rag_local@localhost:5432/godot_rag

Extensions générées

extension	Objectif
`vector`	Stockage des embeddings des morceaux de document et du prototype d'étiquette
`pg_trgm`	Assistance à la recherche floue/partielle du nom d'API, des titres et des symboles

Attention:

Les colonnes d'« embedding » sont de type vecteur dont la dimension n'est pas encore fixée.  
Comme les index HNSW/IVFFlat de pgvector nécessitent une dimension fixe,  
l'index vectoriel réel est créé après que la dimension du modèle d'« embedding » soit déterminée, via une migration séparée.

Modèle :

infra/postgres/init/004_vector_index_templates.sql

Schéma généré

Nom du schéma DB:

godot_rag

Tableau :

Tableau	Rôle
`godot_rag.docs_chunks`	Description des documents officiels, tutoriels, fragments de référence de classe
`godot_rag.api_mapping`	Règles de changement, renommage, remplacement, dépréciation de l'API Godot 3 → 4
`godot_rag.label_prototypes`	Prototypes d'exemples de classification / transformation / refus / modification
`godot_rag.ingest_reports`	Journaux d'avertissement, d'ignorance et de validation du processus de conversion / ingestion JSONL

Conception du tableau

`docs_chunks`

Stocke les fragments des documents officiels. Chaque ligne doit conserver l'URL d'origine, le chemin du fichier d'origine et le hachage du Markdown d'origine.

Colonnes principales :

Colonne	Description
`chunk_id`	ID déterministe qui ne change pas lors d'une réexécution
`doc_version`	Version du document, par ex. `stable`, `4.6`
`source_url`	URL d'origine de la documentation officielle de Godot
`source_file`	Chemin du Markdown dans le dépôt
`source_sha256`	Hachage du Markdown d'origine
`doc_type`	Type de document, par ex. `class_reference`, `tutorial`, `migration`
`symbol`	Symbole représentatif du document de classe/API
`section_path`	Hiérarchie des titres au format JSON
`content`	Corps du texte destiné à la recherche et à l'embedding
`code_blocks`	Tableau des blocs de code extraits du texte
`api_symbols`	Symboles d'API Godot détectés dans le texte
`embedding`	Embedding pgvector
`search_tsv`	tsvector pour la recherche par mots-clés

`api_mapping`

Stocke les règles de changement de Godot 3/4.

Principes importants :

Si la règle est basée sur la documentation officielle, définir confidence = 'verified_from_docs'.
Les règles d'extraction automatique non encore révisées sont définies comme confidence = 'candidate'.
Les règles utilisées directement pour l'apprentissage/étiquetage sont gérées après révision humaine avec confidence = 'approved' ou via un JSONL d'approbation séparé.

`label_prototypes`

Stocke les critères d'étiquetage et les modèles représentatifs des sorties du classificateur.

Premiers candidats d'étiquettes :

Étiquette	Signification
`godot4_valid_api`	Utilisation d'une API valide selon Godot 4
`godot3_api_in_godot4`	Mélange d'API Godot 3 dans un projet Godot 4
`deprecated_or_removed_api`	Utilisation d'une API supprimée ou dépréciée
`migration_required`	Nécessité de migration de Godot 3 → 4
`ambiguous_version_signal`	Manque de preuves ou conflit pour déterminer la version
`non_godot_noise`	Données non liées à Godot (Python/Web/Unity, etc.)
`unsafe_or_obfuscated_code`	Code obfusqué, caractères de contrôle, code suspect de malveillance

Méthode d'exécution

DB démarrage :

docker-compose -f infra/postgres/docker-compose.yml up -d

Dans l'environnement local actuel, on utilise la commande docker-compose plutôt que le plugin docker compose.

Vérification de santé :

docker inspect --format='{{json .State.Health.Status}}' godot-rag-postgres

Connexion depuis l'intérieur du conteneur :

docker exec -it godot-rag-postgres psql -U godot_rag -d godot_rag

Vérifier le tableau:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "\\dt godot_rag.*"

Vérification de l'extension:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "select extname from pg_extension where extname in ('vector', 'pg_trgm') order by extname;"

Initialisation

À n'utiliser que lors de la création complète d'une nouvelle base de données. Faites attention car le volume local sera supprimé.

docker-compose -f infra/postgres/docker-compose.yml down -v
docker-compose -f infra/postgres/docker-compose.yml up -d

Chemin d’injection JSONL prévu

Le script d’injection n’a pas encore été créé. Créez le fichier JSONL ci‑dessous, validez‑le, puis ajoutez le script upsert.

Fichier	Table cible
`work/godot_rag/jsonl/docs_chunks.jsonl`	`godot_rag.docs_chunks`
`work/godot_rag/jsonl/api_mapping.jsonl`	`godot_rag.api_mapping`
`work/godot_rag/jsonl/label_prototypes.jsonl`	`godot_rag.label_prototypes`
`work/godot_rag/jsonl/ingest_report.jsonl`	`godot_rag.ingest_reports`

Prochaines tâches

Créer un rapport d’analyse de la structure outputs/godot_docs_full/pages.
Définir les critères de découpage par type de document.
Rédiger le script de validation du schéma docs_chunks.jsonl.
Rédiger le script upsert JSONL.
Vérifier la qualité de recherche du Retriever avec des questions d’exemple.