Markdown -> JSONL LLM 分類方式

作成日: 2026年 6月 25日

目的

make_md ウェブ変換器で公式ドキュメント Markdown を docs_chunks、api_mapping、label_prototypes のどの JSONL 対象に送るかを LLM に判定させる方法を記録する。

この文書はウェブアプリのコードや API キーを保存しない。現在動作中のローカル実装を基準に、LLM にどの入力を与え、どの出力のみを許可するかを整理する。

現在の実行状態

ローカル Web UI は次のアドレスで実行する。

http://localhost:8501/

現在の実行プロセスは /Users/joyeongjin/make_md で streamlit run app.py --server.port 8501 として起動しています。

分類呼び出し位置

現在の実装ではテーブル分類は classify_tables() が担当しています。

/Users/joyeongjin/make_md/app.py

分類呼び出しは変換より先に実行されます。

-> classify_tables()
-> 選択されたテーブル一覧
-> テーブル別 call_qwen_api()
-> JSONL レコード生成
-> validate_record()
-> 保存

LLM 入力

分類段階で LLM に渡す入力は次の三つです。

分類段階では必ず Markdown 全文を送信しなければなりません。冒頭の抜粋だけを送ってはいけません。公式ドキュメントの冒頭だけを見て分類すると、api_mapping や label_prototypes のように後半の例や詳細説明で境界が明らかになる文書を誤分類する可能性があるためです。

LLM 出力形式

LLM は必ず JSON 配列をひとつだけ返す必要があります。

許容値:

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

例:

["docs_chunks"]

["api_mapping", "label_prototypes"]

[]

[]は有用な公式文書の内容でないと判断した場合にのみ使用する。

現在のプロンプト要約

分類プロンプトの核心は次のようである。

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>

判別基準

LLMには3つのテーブルの境界を同時に伝える必要があります。

api_mapping と label_prototypes の境界は特に重要です。名前だけが変わった場合は api_mapping、引数構成や呼び出し方式自体が変わった場合は label_prototypes です。

JSON 補正フロー

LLM が JSON 配列を正しく返さない場合は、補正リクエストをもう一度送ります。

補正リクエストの要点は次のとおりです。

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.

保正要求にも失敗した場合、そのファイルは classification error として記録される。

ハードコーディング fallback の有無

現在の分類段階はファイル名、パス、正規表現ベースのハードコーディング fallback によりテーブルを強制的に選択しない。

API キーがない場合は分類しない。Qwen の応答が有効な JSON 配列でなく、保正にも失敗した場合、任意にテーブルを選んで保存せずにエラーとして残す。

デバッグ記録

分類結果はセッション状態に次の形で記録される。

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

この記録は、Qwen が JSON ではない応答をしたり、[] を返したり、無効なテーブル名を返したときに原因を確認するために使用されます。