Markdown -> JSONL LLM método de classificação

Data de criação: 25 de junho de 2026

Propósito

Registra o método usado para que o LLM decida, no conversor web make_md, se o Markdown da documentação oficial deve ser enviado para docs_chunks, api_mapping ou label_prototypes.

Este documento não armazena código de aplicativo web ou chaves de API. Baseia‑se na implementação local em execução atualmente e resume quais entradas são fornecidas ao LLM e quais saídas são permitidas.

Estado de execução atual

A UI web local é executada no seguinte endereço.

http://localhost:8501/

A execução atual do processo está em /Users/joyeongjin/make_md com streamlit run app.py --server.port 8501.

Local de chamada da classificação

Na implementação atual, a classificação de tabelas é responsabilidade de classify_tables().

/Users/joyeongjin/make_md/app.py

A chamada de classificação é executada antes da conversão.

Markdown file
-> classify_tables()
-> lista de tabelas selecionadas
-> call_qwen_api() por tabela
-> gerar registro JSONL
-> validate_record()
-> salvar

Entrada para LLM

Na fase de classificação, a entrada enviada ao LLM consiste em três itens:

Entrada	Descrição
mensagem do sistema	Força a devolução apenas de JSON. Markdown, explicações e textos de raciocínio são proibidos.
nome do arquivo	Nome do arquivo Markdown enviado
markdown completo	Todo o conteúdo do Markdown

A fase de classificação deve enviar o markdown completo. Não basta enviar apenas um trecho inicial. Se a classificação for feita apenas com a parte inicial da documentação oficial, documentos que apresentam limites apenas em exemplos ou descrições detalhadas posteriores, como api_mapping e label_prototypes, podem ser classificados incorretamente.

Formato de saída do LLM

O LLM deve retornar apenas um único array JSON.

Valores permitidos:

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

Exemplo:

["docs_chunks"]

["api_mapping", "label_prototypes"]

[]

[] é usado apenas quando se determina que não é conteúdo útil de documentação oficial.

Resumo do Prompt Atual

O núcleo do prompt de classificação deve ser o seguinte.

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>

Critérios de Determinação

É necessário transmitir ao LLM os limites de três tabelas simultaneamente.

Tabela	Limite Pretendido
`docs_chunks`	Trechos de texto de documentação oficial, tutoriais, referência de classes
`api_mapping`	Como nomes de funções, classes e símbolos mudaram do Godot 3 para o Godot 4
`label_prototypes`	Como proceder quando o modo de uso da função, a composição de argumentos ou o padrão de chamada mudaram completamente

Os limites de api_mapping e label_prototypes são particularmente importantes. Quando apenas o nome mudou, trata‑se de api_mapping; quando a composição dos argumentos ou o modo de chamada mudou, trata‑se de label_prototypes.

Fluxo de Correção de JSON

Se o LLM não retornar um array JSON corretamente, envia‑se mais uma solicitação de correção.

O ponto central da solicitação de correção é o seguinte.

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.

Se a correção falhar, o arquivo será registrado como erro de classificação.

Verificar fallback de hard‑coding

A fase atual de classificação não força a seleção de tabelas por meio de fallback de hard‑coding baseado em nome de arquivo, caminho ou expressões regulares.

Se não houver chave de API, a classificação não será feita. Caso a resposta do Qwen não seja um array JSON válido e a correção também falhe, a tabela não será escolhida arbitrariamente para salvamento e o erro será registrado.

Registro de depuração

O resultado da classificação é registrado no estado da sessão no seguinte formato.

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

Este registro é usado para identificar a causa quando o Qwen responde sem JSON, retorna [] ou devolve um nome de tabela inválido.