2026-06-25 análise de fonte e retrospectiva da classificação de Markdown

Hoje reorganizei os critérios para dividir o Markdown da documentação oficial em três tabelas JSONL.

Inicialmente, pensei em dividir o Markdown da documentação oficial do Godot em docs_chunks, api_mapping e label_prototypes. Contudo, enquanto docs_chunks e api_mapping têm papéis bem definidos, a fronteira de label_prototypes estava nebulosa.

No início, as fronteiras entre as três tabelas eram confusas. Ao revisar o fluxo novamente, percebi que as três tabelas têm o mesmo objetivo: armazenar o Markdown da documentação oficial convertido em JSONL.

A conclusão organizada é a seguinte:

docs_chunks são a base da documentação oficial do Godot 4.
api_mapping é o alvo JSONL que registra como nomes de funções, classes e símbolos mudaram do Godot 3 para o Godot 4.
label_prototypes é o alvo JSONL que registra como escrever quando o modo de uso da função, a composição de argumentos e o padrão de chamada mudaram completamente.

Daqui em diante, analisaremos projetos Godot por unidade de sistema de arquivos. Arquivos como .gd, .tscn, .tres, project.godot serão divididos em unidades AST/pedaços de código, e usaremos as evidências JSONL da documentação oficial conforme necessário. Em seguida, chamaremos o Qwen 3.6 sob demanda para determinar se o trecho pertence ao Godot 3, Godot 4, se precisa de migração ou se pode ser usado como dado explicativo de código.

Esse julgamento será armazenado no banco de dados de pontuações e, por projeto, classificaremos o sistema de arquivos como Godot 3 / Godot 4 / misto / desconhecido. Posteriormente, usaremos esses sistemas de arquivos classificados como base para projetar SFT e DPO.

Roadmaps relacionados:

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

Inicialização da classificação de Markdown

Hoje descartamos o resultado da classificação Markdown → JSONL.

O motivo foi que, na fase de classificação, apenas os primeiros 3000 caracteres do Markdown eram enviados ao LLM, em vez do documento completo. A intenção e a exigência do usuário eram classificar com base em toda a documentação oficial desde o início. Contudo, o alcance de transmissão do código gerado pelo LLM estava arbitrariamente limitado à parte inicial, e não percebemos isso a tempo. Algumas documentações não revelam sua natureza apenas pelos primeiros trechos, e, especialmente, as fronteiras de api_mapping e label_prototypes exigem observar se a mudança é de nome/símbolo ou de modo de uso/argumentos/padrão de chamada.

Critérios organizados:

A classificação de Markdown deve receber o nome do arquivo e o conteúdo completo do Markdown.
Não se escolhe a tabela apenas com base em um excerpt inicial.
Os JSONL já produzidos e os dados inseridos no PostgreSQL são descartados, pois foram gerados com critérios incorretos.
Esvaziamos o DB e os arquivos JSONL e reiniciamos a classificação.

Resultado da inicialização:

godot_rag.docs_chunks: 0 registros
godot_rag.api_mapping: 0 registros
godot_rag.label_prototypes: 0 registros
godot_rag.ingest_reports: 0 registros
Exclusão dos JSONL locais
Reinício do aplicativo Streamlit

Neste trabalho, o mesmo erro se repetiu.

Não foi o usuário que projetou errado desde o início; o código e a documentação gerados pelo LLM divergiram da intenção do usuário e não percebemos a diferença a tempo. Não foi apenas um deslize isolado, mas uma repetição de omissões ao organizar as fronteiras das tabelas e o fluxo de dados. Como se diz, erros recorrentes são parte da habilidade, e devemos prestar mais atenção a esse ponto.

Em particular, houve o problema de afirmar conclusões documentais sem antes validar a implementação, ou de escrever esquemas e fluxos ainda não definidos como se fossem definitivos. Mesmo quando docs_chunks, api_mapping e label_prototypes deveriam estar no mesmo nível, descrevi apenas uma tabela como se fosse um fluxo especial, quebrando a consistência da documentação.

Daqui em diante, a escrita de documentação será quase sempre um procedimento obrigatório ao avançar nas tarefas. O objetivo da documentação não é apenas organizar para exibição, mas confirmar qual critério está sendo usado para julgamento. Sempre que código ou dados mudarem, registre a origem desse critério para evitar repetir o mesmo erro.

Se ainda continuássemos sem documentar a estrutura atual do código, poderíamos ter descoberto o problema mais tarde. Ao escrever a documentação do método de classificação do LLM, percebemos que o código realmente enviava apenas os primeiros 3000 caracteres, não todo o Markdown, e pudemos corrigir para atender à exigência original. Assim, este caso reforça que a documentação não é apenas um resumo, mas um meio de validar se o comportamento real do código corresponde à intenção do usuário.

Observação da interrupção do RunPod e retomada da conversão

Durante a conversão Markdown → JSONL, o servidor RunPod parou inesperadamente, interrompendo também a conversão em andamento no web‑app local. Depois, reiniciei o aplicativo Streamlit e verifiquei se o estado anterior foi mantido ou se tudo começou do zero.

Os critérios de observação foram o estado por arquivo salvo em state.json e o Latest Processing Log do web‑app. As evidências principais antes e depois da reinicialização foram:

Antes da reinicialização: done 47, deferred 7, converting 1, pending 1515.
O arquivo em processamento era pages/classes__class_astar3d__23ef6ac2.md.
Após reiniciar, o log mostrou 앱 재시작 후 자동 이어하기를 일시정지함.
Em seguida, apareceu o log 처리 중이던 파일을 pending으로 되돌림, novamente referindo‑se ao mesmo pages/classes__class_astar3d__23ef6ac2.md.
Quando retomamos, o log 기존 분류 재사용 apareceu para esse arquivo, que foi concluído antes de passar para o próximo.
Depois, os arquivos pages/classes__class_astargrid2d__51463855.md, pages/classes__class_atlastexture__336f837e.md, pages/classes__class_audiobuslayout__a2e0df1f.md foram processados sequencialmente, aumentando a contagem de done.

A partir dessa observação, confirmamos:

O resultado total da conversão não foi reiniciado.
O arquivo em processamento foi devolvido com segurança para o estado pending.
Arquivos já concluídos não foram reprocessados.
Resultados de classificação existentes foram reutilizados.
Ao reiniciar, a execução continuou a partir do ponto onde parou.

Entretanto, quando o servidor RunPod falha inesperadamente, o fluxo de conversão pode ficar em espera ou interrompido por longos períodos. Em tarefas extensas, é necessário configurar alertas que detectem rapidamente:

Falha de resposta do servidor RunPod
Timeout da API ou respostas 5xx repetidas
Encerramento do processo do aplicativo Streamlit
Arquivo em processamento permanecendo demais tempo na mesma etapa da tabela
Pausa automática de continuação devido à reinicialização do app

Esses sinais devem ser tornados visíveis para que a equipe possa agir prontamente.