Markdown -> JSONL LLM Klassifizierungsverfahren

Erstellungsdatum: 25. Juni 2026

Zweck

Im make_md Web‑Konverter wird festgehalten, wie ein LLM entscheidet, ob das offizielle Dokument‑Markdown an docs_chunks, api_mapping oder label_prototypes gesendet wird.

Dieses Dokument speichert keinen Web‑App‑Code oder API‑Schlüssel. Es fasst zusammen, welche Eingaben dem LLM gegeben werden und welche Ausgaben zulässig sind, basierend auf der aktuell laufenden lokalen Implementierung.

Aktueller Ausführungsstatus

Die lokale Web‑UI wird unter folgender Adresse ausgeführt.

http://localhost:8501/

Der aktuelle Ausführungsprozess läuft von /Users/joyeongjin/make_md mit streamlit run app.py --server.port 8501.

Aufrufort der Klassifizierung

Im aktuellen Implementierung übernimmt classify_tables() die Tabellenklassifizierung.

/Users/joyeongjin/make_md/app.py

Klassifizierungsaufrufe werden vor der Transformation ausgeführt.

-> classify_tables()
-> ausgewählte Tabellenliste
-> pro Tabelle call_qwen_api()
-> JSONL-Datensatz erstellen
-> validate_record()
-> speichern

LLM Eingabe

Im Klassifizierungsschritt werden der LLM folgende drei Eingaben übermittelt.

Eingabe	Beschreibung
system message	Erzwingt die Rückgabe nur von JSON. Markdown, Erklärungen und Denktexte sind verboten.
filename	Name der hochgeladenen Markdown-Datei
full markdown	Der gesamte Markdown-Text

Im Klassifizierungsschritt muss der gesamte Markdown-Text gesendet werden. Es darf nur ein Auszug des Anfangs gesendet werden. Wenn man nur den vorderen Teil der offiziellen Dokumentation betrachtet, kann es zu Fehlklassifikationen kommen, weil bei Dokumenten wie api_mapping und label_prototypes die Grenzen erst in späteren Beispielen oder detaillierten Beschreibungen erkennbar sind.

LLM-Ausgabeformat

Die LLM muss genau ein JSON-Array zurückgeben.

Zulässige Werte:

["docs_chunks", "api_mapping", "label_prototypes"]

Beispiel:

["docs_chunks"]

["api_mapping", "label_prototypes"]

[]

[] wird nur verwendet, wenn es nicht als nützlicher offizieller Dokumentationsinhalt angesehen wird.

Aktuelle Prompt‑Zusammenfassung

Der Kern des Klassifizierungs‑Prompts sollte wie folgt sein:

Classify this Markdown into zero or more target tables.
Return exactly one JSON array.
Valid values are:
["docs_chunks", "api_mapping", "label_prototypes"]

Table boundaries:
- docs_chunks: official documentation explanations, tutorials, class reference chunks.
- api_mapping: Godot 3 -> Godot 4 function/class/symbol name changes.
- label_prototypes: usage-pattern migrations where arguments, call shape, or usage style changed, not just the name.

Rules:
- Use [] only if the file is not useful documentation content.
- Use one or more valid table names when conversion is needed.
- Do not include explanations, markdown fences, or any text outside JSON.

FILE: <filename>
FULL MARKDOWN:
<entire markdown text>

Beurteilungskriterien

LLM muss die Grenzen von drei Tabellen gleichzeitig übermitteln.

Tabelle	Beabsichtigte Grenze
`docs_chunks`	Offizielle Dokumentationsbeschreibung, Tutorials, Klassenreferenz‑Chunks
`api_mapping`	Wie sich Funktionsnamen, Klassennamen und Symbolnamen von Godot 3 → Godot 4 geändert haben
`label_prototypes`	Wie man vorgehen muss, wenn sich die Art der Funktionsnutzung, Parameterstruktur oder Aufrufmuster komplett geändert hat

Die Grenzen von api_mapping und label_prototypes sind besonders wichtig. Wenn nur der Name geändert wurde, gehört es zu api_mapping; wenn sich die Parameterstruktur oder die Aufrufweise selbst geändert hat, gehört es zu label_prototypes.

JSON‑Korrekturschleife

Wenn LLM das JSON‑Array nicht korrekt zurückgibt, wird eine weitere Korrekturanfrage gesendet.

Der Kern der Korrekturanfrage ist wie folgt:

Your previous classification response was not valid JSON.
Rewrite it as exactly one JSON array using only these strings:
["docs_chunks", "api_mapping", "label_prototypes"].
Use [] only if this file is not useful documentation content.

Wenn die Korrekturanfrage ebenfalls fehlschlägt, wird die betreffende Datei als Klassifizierungsfehler verzeichnet.

Hardcoding‑Fallback‑Entscheidung

Derzeit wählt die Klassifizierungsstufe keine Tabelle aus, wenn ein Hardcoding‑Fallback basierend auf Dateinamen, Pfaden oder regulären Ausdrücken verwendet wird.

Wenn kein API‑Schlüssel vorhanden ist, wird nicht klassifiziert. Wenn die Qwen‑Antwort kein gültiges JSON‑Array ist und die Korrektur ebenfalls fehlschlägt, wird willkürlich keine Tabelle ausgewählt und gespeichert, sondern als Fehler vermerkt.

Debug‑Aufzeichnung

Das Klassifizierungsergebnis wird im Sitzungsstatus in folgender Form festgehalten.

{
  "file": "example.md",
  "parsed_result": ["docs_chunks"],
  "matched_tables": ["docs_chunks"],
  "raw_response": "<qwen raw response>"
}

Dieser Eintrag wird verwendet, um die Ursache zu ermitteln, wenn Qwen eine Antwort liefert, die kein JSON ist, [] zurückgibt oder einen ungültigen Tabellennamen zurückgibt.