Markdown -> JSONL LLM способ классификации

Дата создания: 25 июня 2026 г.

Цель

make_md веб‑конвертер записывает способ, с помощью которого LLM определяет, какой из JSONL‑файлов docs_chunks, api_mapping, label_prototypes следует отправить официальную документацию Markdown.

Этот документ не сохраняет код веб‑приложения или API‑ключи. На основе текущей работающей локальной реализации описывается, какие входные данные можно передать LLM и какой вывод разрешён.

Текущее состояние выполнения

Локальный веб‑интерфейс запускается по следующему адресу.

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()
-> сохранить

(Нет доступного фрагмента Markdown для перевода.)

В этапе классификации LLM получает следующие три входных данных.

Ввод	Описание
system message	Принудительно возвращать только JSON. Запрещены Markdown, описания, текст размышлений.
filename	Имя загруженного Markdown‑файла
full markdown	Полный текст Markdown

Этап классификации обязан отправлять весь текст Markdown. Нельзя отправлять только начальный отрывок. Если классифицировать, глядя только на начало официальной документации, можно ошибочно отнести документы, где границы проявляются в примерах или подробных описаниях в конце, такие как api_mapping и label_prototypes.

Формат вывода LLM

LLM обязан вернуть только один массив JSON.

Допустимые значения:

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

Нет предоставленного фрагмента Markdown.

["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 необходимо передать границы трех таблиц одновременно.

Таблица	Предполагаемая граница
`docs_chunks`	Текст официальной документации, учебные материалы, фрагменты справочника по классам
`api_mapping`	Как изменились имена функций, классов и символов при переходе с Godot 3 на Godot 4
`label_prototypes`	Как следует использовать функции, когда полностью изменились способ передачи аргументов и паттерн вызова

Границы 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.

Корректировка запроса также не удалась — файл будет записан как ошибка классификации.

Наличие жёстко закодированного fallback

Текущий этап классификации использует жёстко закодированный fallback на основе имени файла, пути и регулярных выражений и не принудительно выбирает таблицу.

Если отсутствует API‑ключ, классификация не выполняется. Если ответ Qwen не является действительным JSON‑массивом и корректировка также не удалась, таблица не будет выбрана произвольно и сохранена, а ошибка будет зафиксирована.

Запись отладки

Результат классификации записывается в состояние сессии в следующем виде.

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

Эта запись используется для выяснения причины, когда Qwen отвечает не в формате JSON, возвращает [] или возвращает недопустимое имя таблицы.