2026-06-25 Quellanalyse und Rückblick zur Markdown‑Klassifizierung

Heute habe ich die Kriterien, nach denen offizielle Dokumentations‑Markdowns in drei JSONL‑Tabellen aufgeteilt werden, erneut strukturiert.

Anfangs dachte ich daran, die offizielle Godot‑Dokumentation‑Markdown in die drei Tabellen docs_chunks, api_mapping und label_prototypes zu unterteilen. Während die Rollen von docs_chunks und api_mapping klar waren, war die Grenze für label_prototypes unklar.

Zunächst waren die Grenzen zwischen den drei Tabellen verschwommen. Beim erneuten Durchsehen des Flussdiagramms habe ich selbst festgelegt, dass alle drei Tabellen dasselbe Ziel haben: die offizielle Dokumentations‑Markdown in JSONL zu klassifizieren und zu speichern.

Das Ergebnis meiner Überlegungen lautet:

docs_chunks ist die Quelle der offiziellen Godot 4‑Dokumentation.
api_mapping ist die JSONL‑Ziel‑Tabelle, in der gespeichert wird, wie Funktions‑, Klassen‑ und Symbolnamen von Godot 3 zu Godot 4 geändert wurden.
label_prototypes ist die JSONL‑Ziel‑Tabelle, in der festgehalten wird, wie man vorgehen muss, wenn sich die Art der Funktionsnutzung, Parameter‑Zusammensetzung oder Aufruf‑Muster komplett geändert haben.

Künftig werden wir Godot‑Projekte dateisystembasiert analysieren. .gd, .tscn, .tres, project.godot usw. werden in AST‑/Code‑Snippet‑Einheiten zerlegt und die erforderlichen offiziellen Dokumentations‑JSONL‑Belege verwendet. Anschließend wird Qwen 3.6 on‑demand aufgerufen, um zu bestimmen, ob das jeweilige Snippet zu Godot 3, Godot 4, einer Migration nötig ist oder als Code‑Erklärungs‑Daten genutzt werden kann.

Dieses Ergebnis wird in einer Score‑DB gespeichert und das Dateisystem projektweise in Godot 3 / Godot 4 / gemischt / unbekannt klassifiziert. Auf Basis der klassifizierten Dateisysteme werden wir dann Quellen für SFT‑ und DPO‑Design erstellen.

Zugehörige Roadmaps:

docs/roadmaps/2026-06-25-source-analysis-scoring-architecture.md
docs/roadmaps/2026-06-25-markdown-jsonl-llm-classification.md

Initialisierung der Markdown‑Klassifizierung

Heute habe ich das Ergebnis der Markdown → JSONL‑Klassifizierung verworfen.

Der Grund: In der Klassifizierungsphase wurden nicht das gesamte Markdown, sondern nur die ersten 3000 Zeichen an das LLM übermittelt. Die Absicht und Anforderung des Nutzers war von Anfang an, das komplette Dokument zu betrachten. Das LLM‑generierte Code‑Snippet beschränkte jedoch die Übertragungsreichweite willkürlich auf den Anfang, und das wurde nicht rechtzeitig bemerkt. Offizielle Dokumente zeigen ihren Charakter häufig nicht bereits im Anfangsteil, besonders bei api_mapping und label_prototypes muss man prüfen, ob es sich um Namens‑/Symboländerungen oder um Änderungen in Nutzung, Parametern bzw. Aufrufmustern handelt.

Festgelegte Kriterien:

Bei der Markdown‑Klassifizierung werden Dateiname und der gesamte Markdown‑Inhalt übermittelt.
Es wird nicht nur anhand eines kurzen Excerpts am Anfang entschieden.
Vorhandene JSONL‑Ausgaben und in PostgreSQL gespeicherte Daten gelten als Ergebnis einer falschen Basis und werden vollständig verworfen.
Nach dem Leeren von DB und JSONL wird die Klassifizierung neu gestartet.

Ergebnis der Initialisierung:

godot_rag.docs_chunks: 0 Einträge
godot_rag.api_mapping: 0 Einträge
godot_rag.label_prototypes: 0 Einträge
godot_rag.ingest_reports: 0 Einträge
Lokale JSONL‑Ausgaben gelöscht
Streamlit‑App neu gestartet

In dieser Runde trat ein ähnlicher Fehler erneut auf.

Es war nicht von Anfang an ein Fehlentwurf des Nutzers, sondern das vom LLM erzeugte Code‑ und Dokumentations‑Material wich der Nutzer‑Intention ab, und dieser Unterschied wurde nicht rechtzeitig erkannt. Es ging nicht nur um ein einmaliges Versehen, sondern um wiederholte Auslassungen bei der Klärung von Tabellen‑Grenzen und Daten‑Flüssen. Wie man sagt, wiederholte Fehler sind ein Teil der Kompetenz – hier muss man besonders aufmerksam sein.

Insbesondere wurde das Dokument zu früh als fertig betrachtet, ohne die Implementierung exakt zu prüfen, und nicht festgelegte Schemata und Abläufe wurden fälschlicherweise als endgültig beschrieben. Selbst wenn docs_chunks, api_mapping und label_prototypes auf derselben Ebene stehen sollten, wurde eine Tabelle als spezieller Ablauf dargestellt, wodurch die Dokumentenkonsistenz leidet.

Künftig wird das Schreiben von Dokumentation fast zu einem obligatorischen Schritt bei jeder Aufgabe. Der Zweck der Dokumentation ist nicht nur ein „Show‑off“, sondern ein Nachweis, nach welchen Kriterien gerade entschieden wird. Sobald Code oder Daten sich ändern, muss festgehalten werden, aus welchem Grund die Änderung resultierte, um Wiederholungen zu vermeiden.

Wäre die aktuelle Code‑Struktur nicht dokumentiert worden, hätte man das Problem erst später bemerkt. Beim Schreiben der LLM‑Klassifizierungs‑Dokumentation stellte man fest, dass der Code tatsächlich nur die ersten 3000 Zeichen übermittelt, nicht das gesamte Markdown. Daraufhin konnte man den Code anpassen, sodass das komplette Dokument übermittelt wird. Dieser Vorfall bestätigt erneut, dass Dokumentation nicht nur eine Auflistung, sondern ein Prüf‑ und Validierungsprozess ist, um sicherzustellen, dass das tatsächliche Verhalten des Codes mit der Nutzer‑Intention übereinstimmt.

Beobachtungen zum RunPod‑Stopp und zur Wiederaufnahme der Konvertierung

Während der Markdown → JSONL‑Konvertierung stoppte der RunPod‑Server unerwartet, wodurch die laufende Umwandlung in der lokalen Web‑App unterbrochen wurde. Nach einem Neustart der Streamlit‑App wurde geprüft, ob der vorherige Zustand erhalten blieb oder ein kompletter Neustart erfolgte.

Die Beobachtungskriterien waren die in state.json gespeicherten Dateistatus sowie das „Latest Processing Log“ der Web‑App. Die wichtigsten Beweise vor und nach dem Neustart waren:

Vor dem Neustart: done 47, deferred 7, converting 1, pending 1515.
Die gerade verarbeitete Datei war pages/classes__class_astar3d__23ef6ac2.md.
Nach dem Neustart erschien im Log: „App‑Neustart – automatisches Fortsetzen pausiert“.
Daraufhin folgte ein Log‑Eintrag „Zurücksetzen der verarbeiteten Datei auf pending“, wieder für pages/classes__class_astar3d__23ef6ac2.md.
Beim erneuten Start erschien ein Log‑Eintrag „Vorhandene Klassifizierung wiederverwenden“ für dieselbe Datei, die danach abgeschlossen und zur nächsten Datei übergegangen wurde.
Anschließend wurden nacheinander pages/classes__class_astargrid2d__51463855.md, pages/classes__class_atlastexture__336f837e.md, pages/classes__class_audiobuslayout__a2e0df1f.md verarbeitet, wobei der done‑Zähler stieg.

Aus diesen Beobachtungen lässt sich schließen:

Das Gesamtergebnis der Konvertierung wurde nicht zurückgesetzt.
Die gerade verarbeitete Datei wurde sicher auf pending zurückgesetzt.
Bereits abgeschlossene Dateien wurden nicht erneut verarbeitet.
Vorhandene Klassifizierungsergebnisse wurden wiederverwendet.
Beim Neustart wurde ab dem letzten Unterbrechungspunkt fortgesetzt.

Allerdings kann ein unerwarteter RunPod‑Stopp dazu führen, dass der Konvertierungs‑Flow lange wartet oder abbricht. Bei langen Konvertierungen sind Benachrichtigungen über den Server‑Status, API‑Fehler und lokale App‑Neustarts nötig. Nur das Beobachten des Web‑App‑Bildschirms reicht nicht aus, um zu unterscheiden, ob der Server abgestürzt ist, auf eine API‑Antwort wartet oder die lokale App beendet wurde.

Wenn dieser Ablauf weiter verwendet wird, sollten mindestens folgende Zustände deutlich sichtbar gemacht werden:

RunPod‑Server nicht erreichbar
API‑Timeout oder wiederholte 5xx‑Antworten
Streamlit‑App‑Prozess beendet
Datei verbleibt zu lange im selben Tabellen‑Schritt
Automatisches Fortsetzen wurde durch App‑Neustart pausiert