22 de junho de 2026 – Retrospectiva

Hoje criei um fluxo que, em vez de inserir diretamente a documentação oficial do Godot em Markdown no RAG, primeiro a converte para JSONL estruturado e a verifica. No início eu não sabia bem como dividir o Markdown da documentação oficial, mas ao criar uma interface de conversão e visualizar os resultados por arquivo, tudo ficou muito mais fácil.

Conversor Markdown → JSONL

Ao fazer upload de um arquivo Markdown da documentação oficial do Godot, a API Qwen classifica a tabela de destino e divide o resultado em JSONL para docs_chunks, api_mapping e label_prototypes.

Inicialmente eu pensei em ler o Markdown e inseri‑lo direto no banco de dados, mas assim seria difícil ver para qual tabela cada documento foi destinado. Por isso passei a gerar primeiro o JSONL como artefato intermediário e a comparar o resultado da conversão com o texto original na tela.

As vantagens desse método são:

• É possível comparar o Markdown original com o JSONL convertido.
• Você pode ver em qual das tabelas (docs_chunks, api_mapping, label_prototypes) cada documento será inserido.
• Documentos mal classificados ou resultados vazios podem ser filtrados antes de entrar no banco de dados.
• Se as regras de conversão mudarem, basta gerar o JSONL novamente e comparar.

Verificação dos resultados da conversão

O conversor exibe na tela a quantidade de arquivos JSONL gerados e o número de erros. Na visualização de hoje, os resultados de docs_chunks já estavam acumulados, enquanto api_mapping, label_prototypes e os arquivos de erro ainda estavam vazios.

Isso não é tanto um problema, mas sim um reflexo de que os documentos iniciais são, em sua maioria, guias explicativos, o que naturalmente os direciona para docs_chunks. O ponto importante é que o resultado não vai direto para o banco de dados; ele é salvo primeiro como JSONL e pode ser revisado por uma pessoa.

Pré‑visualização do JSONL e visualização em forma de tabela

Permiti que o JSONL fosse visualizado tanto em formato JSON quanto em forma de tabela. Por exemplo, um registro de docs_chunks possui campos como chunk_id, doc_version, source_url, source_file, source_sha256, doc_type, section_path, heading, content, code_blocks, api_symbols, token_count, metadata.

Vendo assim, fica muito melhor do que simplesmente manter o arquivo Markdown. Especialmente porque chunk_id e source_sha256 aparecem juntos, facilitando o rastreamento de qual trecho veio de qual origem. No RAG, o mais importante é não perder a fonte da evidência, e esse artefato intermediário em JSONL pode cumprir esse papel.

Log da conversão

Também verifiquei o log de conversão por arquivo. É possível ver qual arquivo foi iniciado, para qual tabela o Qwen o classificou e quantos registros válidos foram gerados.

No exemplo de hoje, o documento about__complying_with_licenses foi classificado como docs_chunks e convertido em vários trechos. Por outro lado, documentos como 404 não têm tabela de destino e foram ignorados. Esse tipo de log é essencial para rastrear onde ocorreram problemas ao processar os 1.570 documentos.

Configuração local do PostgreSQL

Depois de gerar o JSONL, organizei o banco de dados local PostgreSQL para receber os dados. Levantei um contêiner baseado em pgvector/pgvector:pg16 e criei as tabelas docs_chunks, api_mapping, label_prototypes e ingest_reports.

Um ponto que observei hoje foi que o esquema do banco não pode divergir dos nomes de campo do JSONL. Se o banco acrescentar campos arbitrariamente, o contrato do JSONL se enfraquece e, mais tarde, o conversor e o inseridor podem operar com bases diferentes. Por isso, as colunas de payload do banco foram alinhadas ao esquema do JSONL, e as colunas de operação do banco foram reduzidas ao mínimo: id, embedding, search_tsv, created_at.

Executei o banco localmente, fiz inserts e buscas de amostras de JSONL e testei rollbacks. Ainda não carreguei todos os documentos no banco, mas o caminho de JSONL → PostgreSQL está muito mais claro.

Decisão de hoje

O fluxo criado hoje não é o próprio classificador final de RAG, mas já representa um avanço significativo.

Antes, era incerto como lidar com o Markdown da documentação oficial, e passar direto para chunking ou inserção no banco corria o risco de perder a estrutura. Hoje inseri uma etapa de conversão/validação em JSONL, gerando um artefato intermediário que pode ser revisado por humanos.

Em resumo, o caminho futuro parece estar bem definido a partir daqui.

Godot documentação oficial em Markdown  
-> Conversão para JSONL  
-> Visualização/validação de JSONL  
-> Injeção de PostgreSQL  
-> Validação de busca do Retriever  
-> Organização de respostas do Validator/Qwen

A partir de amanhã, ao converter todos os 1.570 documentos até o fim, será necessário verificar qual proporção de docs_chunks, api_mapping e label_prototypes será obtida. Em especial, api_mapping e label_prototypes não podem ser criados livremente pelo Qwen; portanto, não se deve confiar cegamente nos resultados gerados automaticamente, devendo haver uma etapa de aprovação/validação separada.

Medição da velocidade de processamento

Além disso, ao calcular a velocidade de conversão, estima‑se que a conversão de todos os 1.570 arquivos Markdown para JSONL levará cerca de 42 horas.

O tempo real de processamento até agora foi de aproximadamente 1 hora e 9 minutos. Nesse período, foram processados 43 arquivos no total, combinando 39 arquivos done e 4 arquivos deferred. A velocidade média foi de cerca de 1,6 minutos por arquivo.

Tempo real de processamento: cerca de 1 hora e 9 minutos  
Arquivos processados atualmente: done 39 + deferred 4 = 43  
Velocidade média: cerca de 1,6 minutos por arquivo  
Tempo estimado total para converter 1.570 itens: cerca de 42 horas

No início, eu achava que levaria cerca de 1 item por minuto, mas ao calcular com base nos logs reais, leva um pouco mais de tempo. Pode ser difícil concluir a conversão completa de 1.500 itens ainda hoje, portanto, é necessário continuar registrando a velocidade de processamento e a quantidade de arquivos falhados/pendentes enquanto avança.

Próximo plano de validação

É provável que não haja tempo amanhã e depois de amanhã, então não será possível continuar o trabalho imediatamente. Ainda assim, as tarefas que deverão ser retomadas mais tarde já foram parcialmente organizadas.

Primeiro, é preciso inserir os arquivos JSONL já gerados durante a coleta e a conversão no PostgreSQL local. Até agora, o conversor criado focou em dividir o Markdown em JSONL para docs_chunks, api_mapping e label_prototypes; a próxima etapa é colocar esses JSONL no banco de dados real e verificar se eles estão em um estado pesquisável.

Em seguida, será feita uma pequena validação do fluxo de trabalho escrito em docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md usando um script Python.

source code
-> AST Parser
-> Retriever
-> evidence JSONL / evidence bundle
-> Qwen 3.6 chamada da API
-> verificação da resposta

Então, insiro um código-fonte arbitrário do Godot em um script Python e verifico se o AST Parser extrai os símbolos e os sinais de versão. Coloco o resultado no Retriever para que ele busque trechos da documentação oficial ou mapeamentos de API no PostgreSQL, e, ao enviar o bundle JSONL/evidence retornado para a API do Qwen 3.6, pretendo observar as respostas intermediárias.

Esse processo não é uma automação completa, mas sim uma pequena validação end‑to‑end para confirmar se cada etapa realmente se conecta. Em especial, preciso checar se o Qwen responde a partir da memória ou se baseia nas evidências fornecidas pelo Retriever.

Pensamentos sobre tornar o repositório público e depois privado

Recentemente deixei este repositório público uma vez e depois o tornei privado novamente. O motivo parece ter sido simples: eu não queria exibir minhas habilidades.

Sinto que minhas habilidades ainda são bastante limitadas. Ao mesmo tempo, tive a ideia de criar um modelo exclusivo para Godot, enviá‑lo ao Hugging Face e usar isso como ponto de partida para expandir para vídeos de aula, universidades, portfólio, reputação e outras áreas. Pode parecer um sonho impossível. Contudo, se alguém usar minhas reflexões e registros de trabalho como base para crescer, talvez eu também possa evoluir mais rapidamente nesse processo.

Na verdade, ainda sinto resistência em tornar tudo público. Tenho medo de que o que eu criei pareça superficial, e, por outro lado, temo que alguém possa copiar as conexões superficiais que fiz entre diversos conhecimentos e apresentá‑las como próprias. Não é tanto que o resultado seja uma tecnologia extraordinária, mas sim que todo o rastro de minhas reflexões e ligações apareça de forma completa, o que me deixa desconfortável.

Configurei PRs e pipelines CI/CD, mas o fluxo que imaginei inicialmente era: quando um PR fosse aberto no GitHub workflow, um endpoint local de LLM hospedado na Oracle Cloud faria a revisão automática. Como a Oracle Cloud oferece um ambiente com 24 GB de VRAM, pensei que seria possível rodar praticamente qualquer modelo local e integrar a revisão automática de código. Contudo, perdi a conta da Oracle Cloud, então esse fluxo ficará indisponível por enquanto. O RunPod também tem suas limitações para validação de PRs, pois exige reconfiguração a cada uso. Por isso, por enquanto, focarei em tarefas manuais e documentação, deixando a automação de revisão de PR baseada em LLM para um momento futuro.

A conclusão parece ser esta: embora seja provável que ninguém veja, eu estava excessivamente preocupado com a possibilidade de ser copiado. Mas, mesmo que alguém se inspire ou reutilize meu trabalho, isso pode servir como trampolim para que eu também evolua. A decisão de tornar o projeto público ainda deve ser tomada com cautela, mas não devo deixar de registrar nada por medo.