Godot RAG Klassifikator Lokale PostgreSQL Einrichtung

Erstellungsdatum: 22. Juni 2026

Zweck

Für den offiziellen Godot‑Dokumentations‑RAG‑Klassifikator wird eine lokale PostgreSQL‑Datenbank eingerichtet. Der grundlegende Ablauf ist wie folgt.

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

Das Ziel der aktuellen Phase ist nicht die Erstellung von Trainingsdaten, sondern die Möglichkeit, eine auf offiziellen Dokumenten basierende Beweis‑DB lokal zu reproduzieren. Die Spalte payload der Tabelle wird mit demselben Namen wie das JSONL‑Schema beibehalten, und für den DB‑Betrieb werden nur die minimal notwendigen Spalten wie id, embedding, search_tsv, created_at für Suche/Speicherung verwendet.

Referenz‑Design‑Dokument:

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

Lokale DB-Konfiguration

Docker‑Compose‑Datei:

infra/postgres/docker-compose.yml

Verwendetes Bild:

pgvector/pgvector:pg16

Verbindungsinformationen:

Feld	Wert
Datenbank	`godot_rag`
Benutzer	`godot_rag`
Passwort	`godot_rag_local`
Host	`localhost`
Port	`5432`

Standard‑URL für lokale Entwicklung:

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

Erzeugte Erweiterungen

extension	Zweck
`vector`	Speichert Dokumenten‑Chunks und Label‑Prototyp‑Embedding
`pg_trgm`	Unterstützt fuzzy/partielle Suche nach API‑Namen, Überschriften und Symbolen

Hinweis:

Die Embedding‑Spalte ist ein Vektor‑Typ, dessen Dimension derzeit nicht festgelegt ist.  
Da der HNSW/IVFFlat‑Index von pgvector eine feste Dimension benötigt, wird der eigentliche Vektor‑Index nach Festlegung der Dimension des Embedding‑Modells in einer separaten Migration erstellt.

Vorlage:

infra/postgres/init/004_vector_index_templates.sql

Generiertes Schema

DB‑Schema‑Name:

godot_rag

Tabelle:

Tabelle	Rolle
`godot_rag.docs_chunks`	Offizielle Dokumentationsbeschreibungen, Tutorials, Klassenreferenz‑Chunks
`godot_rag.api_mapping`	Godot 3 → 4 API‑Änderungen, Umbenennungen, Ersetzungen, Deprecation‑Regeln
`godot_rag.label_prototypes`	Prototypen für Klassifizierung/Umwandlung/Ablehnung/Korrekturbeispiele
`godot_rag.ingest_reports`	Warnungen, Überspringungen und Validierungs‑Logs beim JSONL‑Konvertierungs‑ und Einfüge‑Prozess

Tabellendesign

`docs_chunks`

Speichert offizielle Dokumentations‑Chunks. Jede Zeile muss die ursprüngliche URL, den ursprünglichen Dateipfad und den ursprünglichen Markdown‑Hash beibehalten.

Wichtige Spalten:

Spalte	Beschreibung
`chunk_id`	Deterministische ID, die sich bei erneutem Ausführen nicht ändert
`doc_version`	Dokumentationsversion, z. B. `stable`, `4.6`
`source_url`	Original‑URL der offiziellen Godot‑Dokumentation
`source_file`	Pfad zur Markdown‑Datei im Repository
`source_sha256`	Hash des ursprünglichen Markdown
`doc_type`	Dokumenttyp, z. B. `class_reference`, `tutorial`, `migration`
`symbol`	Repräsentatives Symbol der Klasse/API‑Dokumentation
`section_path`	JSON‑Struktur der Überschriften‑Hierarchie
`content`	Volltext, der für Suche und Einbettung verwendet wird
`code_blocks`	Array von Code‑Blöcken, die aus dem Text extrahiert wurden
`api_symbols`	Im Text erkannte Godot‑API‑Symbole
`embedding`	pgvector‑Einbettung
`search_tsv`	tsvector für die Stichwortsuche

`api_mapping`

Speichert die Godot 3/4 Änderungsregeln.

Wichtige Grundsätze:

Wenn es offizielle Dokumentations‑Belege gibt, wird confidence = 'verified_from_docs' gesetzt.
Noch nicht geprüfte automatisch extrahierte Regeln erhalten confidence = 'candidate'.
Regeln, die direkt für Training/Labeling verwendet werden, werden nach menschlicher Prüfung mit confidence = 'approved' versehen oder über separate Genehmigungs‑JSONL verwaltet.

`label_prototypes`

Speichert die Label‑Kriterien und repräsentativen Muster der Klassifikator‑Ausgabe.

Erste Label‑Kandidaten:

Label	Bedeutung
`godot4_valid_api`	Verwendung einer gültigen API nach Godot 4‑Standard
`godot3_api_in_godot4`	Godot 3‑API ist in einem Godot 4‑Projekt gemischt
`deprecated_or_removed_api`	Verwendung einer entfernten/abgeschafften API
`migration_required`	Konvertierung von Godot 3 → 4 erforderlich
`ambiguous_version_signal`	Unzureichende oder widersprüchliche Versionsinformationen
`non_godot_noise`	Daten, die nichts mit Godot zu tun haben (Python/Web/Unity usw.)
`unsafe_or_obfuscated_code`	Obfuskierter, kontrollzeichenhaltiger oder potenziell schädlicher Code

Ausführungsanleitung

DB starten:

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

In der aktuellen lokalen Umgebung wird nicht das docker compose Plugin, sondern der Befehl docker‑compose verwendet.

Gesundheitsprüfung:

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

Zugriff innerhalb des Containers:

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

Tabellenüberprüfung:

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

Erweiterungsprüfung:

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;"

Initialisierung

Wird nur verwendet, wenn die Datenbank vollständig neu erstellt wird. Vorsicht, da das lokale Volume gelöscht wird.

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

JSONL-Einfügepfad geplant

Das Einfügeskript wurde noch nicht erstellt. Erstelle und prüfe die folgenden JSONL-Ausgaben, bevor das Upsert‑Skript hinzugefügt wird.

Datei	Ziel‑Tabelle
`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`

Nächste Aufgaben

Einen Analyse‑Report zur Struktur von outputs/godot_docs_full/pages erstellen.
Die Chunk‑Kriterien pro Dokumenttyp festlegen.
Ein Skript zur Schema‑Validierung von docs_chunks.jsonl schreiben.
Ein JSONL‑Upsert‑Skript schreiben.
Die Qualität der Retriever‑Suche mit Beispiel‑Fragen prüfen.