Godot offizielle Dokumentation RAG Klassifikator Schema und Architektur

Erstellungsdatum: 21. Juni 2026

Zweck

Es wird eine Referenzarchitektur festgelegt, um die gesamte Sammlung der Godot‑Dokumentation über den Fluss JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6 zu verbinden. Dieses Dokument ist kein Implementierungsleitfaden zur Erstellung von Trainingsdaten, sondern definiert die Design‑Grundlagen, wie die bereits im Verzeichnis outputs/godot_docs_full/pages gesammelten Markdown‑Dokumente strukturiert und in eine durchsuchbare Referenz‑DB überführt werden sollen.

Aktuelle Eingabedaten

Die gesammelten offiziellen Dokumente befinden sich im Repository unter outputs/godot_docs_full.

Aktueller Stand:

Gesamte Pipeline

1. Der crawler sammelt die offizielle Godot‑Dokumentation aus dem Internet.
2. Die Sammelergebnisse werden pro Seite als Markdown gespeichert.
3. Das Markdown wird normalisiert und mit Metadaten zu JSONL‑Datensätzen konvertiert.
4. Die JSONL‑Datensätze werden in PostgreSQL importiert.
5. PostgreSQL speichert Dokument‑Chunks, API‑Mappings und Label‑Prototypen getrennt.
6. Wenn ein Nutzer eine Analyse des Godot‑Quellcodes anfordert, strukturiert ein AST‑Parser den Projektcode.
7. Der Retriever sucht anhand der Nutzerfrage und der AST‑Analyse in PostgreSQL nach relevanten Belegen.
8. Der Validator bündelt Frage, AST‑Ergebnis und Suchbelege und übergibt sie an Qwen 3.6.
9. Qwen 3.6 fungiert nicht als End‑Entscheider, sondern erstellt die Antwort anhand der verifizierten Belege.
10. Der Validator prüft Beleg‑/Format‑/Verbot‑Muster der Antwort und gibt sie anschließend an den Nutzer zurück.

Umwandlung von Markdown zu JSONL

pages/*.md sind leserfreundliche Originalseiten, aber für RAG zu groß. Daher zerlegt das Umwandlungsskript die Seiten in Abschnitts‑/API‑Member‑/Beispiel‑Einheiten und bewahrt die Original‑URL sowie den Dokumenttyp.

Gemeinsame Normalisierungsregeln

JSONL‑Ausgabe

docs_chunks.jsonl Schema

{
  "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
  }
}

Erforderliches Feld:

api_mapping.jsonl Schema

{
  "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"]
}

Prinzip:

label_prototypes.jsonl Schema

{
  "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‑Vorschläge:

Entwurf des PostgreSQL‑Schemas

PostgreSQL geht davon aus, dass pgvector verwendet wird. Die Stichwortsuche nutzt tsvector oder einen Trigram‑Index.

docs_chunks

Indizes:

api_mapping

Indizes:

label_prototypes

Indizes:

AST Parser Eingabe/Ausgabe

Der AST Parser wandelt den Quellcode des Benutzers in eine durchsuchbare Struktur um, bevor er ihn direkt an das LLM übergibt. Das anfängliche Ziel sind .gd, .tscn, project.godot.

Eingabe

Ausgabeschema

{
  "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": []
  }
}

Initiale Extraktionsfelder:

Retriever‑Verhalten

Der Retriever ist die Schicht, die vor dem LLM Belege auswählt.

1. Absicht und Zielaufgabe aus der Benutzerfrage extrahieren.
2. API‑Symbol, Versionssignal und Dateipfad aus dem AST‑Parser‑Ergebnis übernehmen.
3. Zunächst ein exaktes Lookup in api_mapping durchführen.
4. In docs_chunks gleichzeitig API‑Symbol‑Filter + Schlüsselwortsuche + Vektorsuche ausführen.
5. Ähnliche Labels und Validierungsregeln aus label_prototypes holen.
6. Die Suchergebnisse als Beleg‑Bundle sortieren.

Beleg‑Bundle:

{
  "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
  }
}

Validator und Qwen 3.6 Rollenaufteilung

Qwen 3.6 ist das Modell, das die gefundenen Belege liest und die Antwort zusammenstellt. Die endgültige Kennzeichnung, die Annahme von Belegen und die Prüfung verbotener Muster übernimmt der Validator.

Vom Validator zu prüfende Punkte:

Einfügereihenfolge

1. outputs/godot_docs_full/summary.json und failed.json prüfen.
2. manifest.json und pages/*.md laden.
3. Einen Markdown‑Normalisierungs‑Report erstellen.
4. docs_chunks.jsonl erzeugen.
5. Aus den migration/class‑Dokumenten api_mapping.jsonl‑Kandidaten generieren.
6. Mit genehmigten Regeln und repräsentativen Beispielen label_prototypes.jsonl erzeugen.
7. Nur Datensätze, die die JSONL‑Schema‑Validierung bestehen, per Upsert in PostgreSQL einfügen.
8. Embeddings erzeugen und den Vektor‑Index aktualisieren.
9. Keyword‑Index und Exact‑Index aktualisieren.
10. Die Retriever‑Ergebnisse mit Beispiel‑Fragen prüfen.

Qualitäts‑Checkliste

Implementierungs‑Prioritäten

1. Bericht zur Struktur‑Analyse von pages/*.md erstellen
2. Skript zur Umwandlung in docs_chunks.jsonl schreiben
3. Skript zur JSONL‑Schema‑Validierung schreiben
4. DDL für PostgreSQL erstellen
5. Einfügen von docs_chunks und Such‑Validierung durchführen
6. Kandidaten für api_mapping erzeugen und manuellen Freigabe‑Workflow implementieren
7. Initiales Label‑Set label_prototypes erstellen
8. Minimal‑Felder aus dem AST‑Parser extrahieren
9. Ausgabe‑Bundle der Retriever‑Belege erzeugen
10. Loop zur Zusammenstellung von Validator‑+ Qwen 3.6‑Antworten verbinden

Kernprinzipien

• Das originale Markdown der offiziellen Dokumentation wird nicht verändert, sondern erhalten.
• JSONL dient als reproduzierbares Zwischenergebnis.
• In der Datenbank müssen Originalpfad, Original‑URL, Hash und Version des Transformations‑Scripts gespeichert werden.
• Das LLM darf keine eigenen Labels erfinden.
• Die Entscheidung zwischen Godot 3 und 4 basiert auf AST‑Signal, API‑Mapping und Belegen aus der offiziellen Dokumentation.
• Unsichere Kandidaten werden nicht sofort als Trainingsdaten verwendet, sondern bleiben im Status candidate.
• Qwen 3.6 ist der Antwort‑Zusammenführer; die Bewertungs‑Kriterien liegen bei Retriever und Validator.

Nächste Schritte

Der nächste Schritt besteht darin, die Markdown‑Struktur von outputs/godot_docs_full/pages stichprobenartig zu analysieren. Da class‑Reference, migration‑ und tutorial‑Dokumente unterschiedliche Strukturen aufweisen, soll zunächst für jeden Dokumenttyp eine eigene Chunk‑Strategie definiert werden, anstatt eine einheitliche Regel anzuwenden.