2026-06-17 Revisão da Construção do Detector Godot LLM/RAG

Resumo em uma frase

Hoje redefinimos a direção do modelo de codificação especializado em Godot, passando de um modelo simples de perguntas e respostas para um Agente SWE de nível de repositório, e criamos a primeira implementação do detector RAG baseado em documentação oficial e do pipeline de geração de dados que o antecede.

Grande fluxo do dia

Inicialmente, o objetivo era algo como “criar um chatbot RAG usando a documentação oficial do Godot”. Contudo, à medida que a conversa e o trabalho avançaram, o objetivo ficou mais claro.

Coleta da documentação oficial do Godot  
-> Classificador RAG baseado na documentação oficial  
-> Rotulagem do projeto Godot no GitHub  
-> Geração de dados SFT/DPO  
-> Modelo de codificação Godot 4 baseado em Qwen  
-> Agente SWE em nível de repositório

Então, o ponto principal de hoje não foi criar apenas um chatbot, mas estabelecer uma base de detecção/geração de dados para, futuramente, desenvolver um modelo capaz de ler e corrigir projetos Godot.

1. Julgamento de que um modelo de Q&A simples é insuficiente

A primeira coisa que organizei hoje foi a natureza do objetivo do modelo.

Inicialmente, pensei em criar um conjunto de dados de perguntas e respostas sobre Godot 4 e treinar o modelo para que ele respondesse bem a códigos de Godot 4. Contudo, ao considerar solicitações como “crie um mapa para mim”, percebe‑se que isso não é um simples problema de Q&A.

O fluxo real da solicitação se assemelha mais ao seguinte.

Entendimento da solicitação do usuário
-> Explorar a estrutura do repositório
-> Encontrar scene/script/resource relacionados
-> Verificar o caminho dos assets e o estilo de código existente
-> Determinar a sintaxe/API do Godot 4
-> Modificar o código
-> Executar/testar/validar
-> Gerar patch

Este fluxo não é um problema de gerar uma única resposta, mas sim um problema de agente de engenharia de software. Portanto, hoje redefinimos a direção do modelo sob a perspectiva de SWE-agent trajectory training.

Palavras‑chave principais registradas hoje:

Long-context repository-level software engineering agent training
SWE-agent trajectory training
Godot repo-level patch generation
long-context trajectory dataset

Também organizei os casos de referência.

SWE-agent trajectories
SWE-smith
SWE-Gym
CoderForge-Preview
ACC
RepoBench / CrossCodeEval / RepoCoder
aiXcoder CoLT
godot-dodo
wallstoneai/godot-gdscript-dataset

A conclusão de hoje foi que apenas pequenas instruções de Q&A são insuficientes. O que realmente é necessário é a trajetória de exploração, julgamento, modificação e verificação em nível de projeto Godot.

Memorando relacionado:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md

2. Resumo completo do roadmap do Godot LLM

Em seguida, reorganizamos todo o roadmap de desenvolvimento.

O fluxo principal foi organizado da seguinte forma.

## Dados
- 1ª RAG chatbot
- SFT
- DPO
- Agente SWE

Se dividirmos as etapas em mais detalhes, são as seguintes.

Etapa 0. Preparação  
Etapa 1. Coleta e estruturação de dados  
Etapa 2. Desenvolvimento do chatbot RAG de primeira fase  
Etapa 3. Rotulagem de dados e criação de conjunto de dados  
Etapa 4. Treinamento do modelo  
Etapa 5. Desenvolvimento do agente SWE  
Etapa 6. Melhoria contínua

Esta roadmap destaca que a decisão mais importante é não considerar o chatbot RAG de primeira fase apenas como uma ferramenta de perguntas e respostas. Primeiro, é necessário criar um discriminador RAG que atue como especialista na documentação oficial do Godot e, por meio desse discriminador, rotular/processar os dados do GitHub antes de expandi‑los com SFT/DPO e um Agente SWE.

Em particular, o Agente SWE da Etapa 5 não deve ser apenas um gerador de código simples, mas deve possuir as seguintes capacidades.

Projeto análise
Exploração de arquivos necessários
Modificação de código
Verificação da CLI do Godot ou resultados de execução
Análise da causa da falha
Criação de patch

Roadmap relacionado:

docs/roadmaps/2026-06-17-godot-llm-roadmap.md

3. Projeto da Estrutura de Geração de Dados Baseada em Classificador RAG

Hoje, outra decisão importante foi “não deixar a decisão final da rotulagem nas mãos do LLM”.

Inicialmente, era fácil pensar que o chatbot RAG poderia analisar o código ou a documentação do GitHub e determinar se é Godot 3/4. Contudo, a rotulagem afeta diretamente a qualidade dos dados de treinamento, e confiar em julgamentos improvisados do LLM é arriscado.

Portanto, estruturamos da seguinte forma.

LLM é assistente de geração  
O rótulo é decidido pelo sistema  
O JSONL final é montado/verificado pelo pipeline Python

O que o sistema deve ser responsável por:

Extração de símbolos  
Consulta ao DB de mapeamento da API  
Busca vetorial em documentos oficiais  
Busca por palavras‑chave  
Busca de protótipos de rótulo  
Pontuação de rótulo  
Cálculo de confiança  
Montagem do JSONL final  
Verificação

O que o LLM pode ser responsável:

Gerar rascunho de código corrigido  
Gerar descrição  
Gerar perguntas/respostas SFT  
Gerar respostas ruins DPO  
Gerar rascunho de patch  
Assistência na verificação/explicação de problemas

Também organizei os conjuntos de dados de destino em 8 tipos.

version_classification
api_mapping
migration_fix
instruction_sft
dpo_preference
repo_explorer
patch_generation
metadata_verification

Esta proposição se tornou o critério de design do código de pós‑processamento RAG criado hoje. Em particular, a razão para separar api_mapping, symbol_catalog, keyword_index e search_text também decorre daqui.

Memorando relacionado:

docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md

4. Fluxo MVP do discriminador RAG para o modelo Qwen 3.6

O fluxo MVP entre o discriminador RAG do Godot e o modelo de codificação Qwen 3.6 foi organizado separadamente.

Fluxo organizado:

godot_docs_full.zip Preparar documento original  
-> Chunking inicial baseado em chunk_docs.py  
-> Pós-processamento exclusivo para Godot  
-> Construir infraestrutura de busca local  
-> Coletar e estruturar dados do GitHub  
-> Executar o classificador RAG  
-> Gerar conjunto de dados de treinamento  
-> Qwen 3.6 SFT/DPO

Aqui, a infraestrutura de busca local não se refere apenas a um único vetorDB.

Configurações necessárias:

Vector DB
Keyword Index
Reranker
API Mapping DB
Label Prototype DB

Além disso, os dados do GitHub devem ser inseridos como uma estrutura de repositório, não apenas fragmentos de código simples.

Entrada necessária:

.gd
.tscn
.tres
project.godot
README
repo tree
metadata

Reorganizei também o objetivo do primeiro SFT.

Prioridade Godot 4  
Saída padrão do GDScript  
Rejeição da API do Godot 3  
Explicação dos motivos da conversão Godot 3 → 4

Posteriormente, o DPO deve definir de forma mais clara os critérios para respostas boas e respostas ruins.

Resposta ruim: Resposta com API do Godot 3 misturada  
Resposta boa: Resposta com código puro do Godot 4 e fundamentada

Notas relacionadas:

docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md

5. v1 documentação oficial em chunking

Depois de organizar o design, criamos um formato que pode ser inserido no RAG a partir dos dados da documentação oficial.

O primeiro artefato produzido é o seguinte arquivo.

work/godot_rag/chunks/docs_chunks.jsonl

Dividimos os 1.570 documentos oficiais em Markdown por cabeçalhos e comprimento, criando 9.741 fragmentos.

Resultado:

Input pages: 1,570
Output chunks: 9,741
Max chunk chars: 2,800
Overlap chars: 350

Pontos positivos da v1:

• Todo o documento oficial foi convertido em chunks JSONL.
• O parsing de JSONL foi estável.
• Tipos básicos de documentos como class_reference, tutorial, migration foram classificados.

Problemas da v1:

• Restaram muitos trechos residuais do Sphinx.
• Havia chunks de ruído muito curtos.
• A estrutura de heading, section, método/propriedade não estava suficientemente preservada.
• A referência de classes não foi dividida de forma granular por API.

A v1 foi a fase de “coleta da documentação oficial e chunking básico”. Serviu como ponto de partida para o MVP de busca, mas foi insuficiente para o classificador de rótulos.

6. Pós-processamento v2

Em seguida, criamos postprocess_chunks.py e geramos os chunks v2.

Arquivo:

work/godot_rag/postprocess_chunks.py
work/godot_rag/chunks/docs_chunks_v2.jsonl

O que foi processado na v2:

Remover chunk 404  
Remover chunk de ruído curto  
Remover texto residual do Sphinx  
Extrair símbolos  
Extrair class_name  
Aprimorar section/member_type/member_name  
Exibir chunks relacionados à migração

Resultado:

Input chunks: 9,741
Output chunks: 8,778
Dropped 404 chunks: 3
Dropped short/noise chunks: 960
Migration-related chunks: 695

v2 está em um estado que pode ser usado como MVP de busca RAG baseado em documentação oficial. No entanto, ainda é insuficiente para ser considerado o verificador final de rótulos. Em particular, mudanças de sintaxe/API como move_and_slide, velocity, @export, await não estavam separadas como critérios de verificação independentes.

7. Direção incorreta do v3 e retrocesso

O v3 inicialmente pensado era criar um chunk api_focus codificando algumas APIs principais.

Exemplo:

KinematicBody2D
CharacterBody2D
move_and_slide
@export
await

Esta abordagem pode parecer que aumenta rapidamente o desempenho da pesquisa. No entanto, na prática, era perigosa.

Problema:

• O mecanismo de busca pode se sobreajustar à API escolhida por uma pessoa.
• APIs fora da lista ficam enfraquecidas.
• Algumas APIs representativas podem parecer representar toda a API do Godot.
• APIs ausentes podem levar a erros de rotulagem posteriormente.

Por isso, a versão v3 anterior foi revertida. Essa decisão foi importante. A curto prazo pode parecer uma perda, mas, considerando a qualidade final do classificador, focar em chunks codificados manualmente era uma direção equivocada.

8. Redesenho da v3 baseado em catálogo

Depois da reversão, a direção foi alterada.

Novos princípios:

Não perde nenhum chunk v2.  
Não cria arbitrariamente novos chunks de foco.  
Extrai automaticamente symbol/catalog/index/mapping de toda a documentação oficial.  
Anexa informações de reforço de busca como metadata.

Código adicionado:

work/godot_rag/build_symbol_catalog.py
work/godot_rag/build_keyword_index.py
work/godot_rag/build_api_mapping.py
work/godot_rag/make_chunks_v3.py
work/godot_rag/validate_rag_artifacts.py
work/godot_rag/retrieval_smoke_test.py

Saída gerada:

work/godot_rag/catalog/symbol_catalog.jsonl
work/godot_rag/catalog/keyword_index.json
work/godot_rag/catalog/api_mapping.jsonl
work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl
work/godot_rag/validation/validation_report.json
work/godot_rag/validation/retrieval_smoke_test.json

O arquivo completo docs_chunks_v3.jsonl tem cerca de 189 MB, o que poderia exceder o limite de um único arquivo no GitHub. Portanto, no repositório foram enviados arquivos divididos, preservados linha a linha, e, se necessário, eles podem ser recombinados localmente.

cat work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl \
  > work/godot_rag/chunks/docs_chunks_v3.jsonl

9. Verificação de consistência v3

No v3, o que mais se valorizou foi a prevenção de omissões. Se até mesmo um único chunk do v2 estiver faltando, a base documental oficial pode desaparecer posteriormente.

Por isso, criamos o validate_rag_artifacts.py.

Critérios de validação:

v2 chunk_id set == v3 chunk_id set
no missing or extra v3 chunks
catalog/index/mapping references point to existing chunks
search_text is present
no old hardcoded api_focus fields remain

Resultado da verificação:

status: pass
v2 chunks: 8,778
v3 chunks: 8,778
v2 unique chunk_id: 8,778
v3 unique chunk_id: 8,778
symbol catalog entries: 134,922
keyword index keys: 192,257
api mapping records: 144
v3 chunks with api mappings: 1,900
v3 migration-related chunks: 2,392

Além disso, também foi realizado um teste smoke baseado em lexical/palavra‑chave antes da etapa de embedding.

Consulta representativa:

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Resultado passou em todos os 5 casos.

10. O maior risco descoberto hoje

A principal percepção de hoje foi que “coisas que são extraídas em grande quantidade” e “coisas em que se confia e se escreve no rótulo” são diferentes.

Se extrair amplamente em toda a documentação oficial, o recall melhora. Porém, se tratar todos esses resultados com o mesmo nível de confiança, o índice de palavras‑chave fica contaminado.

Por exemplo, o que segue tem alta probabilidade de ser um API real ou um elemento de sintaxe.

CharacterBody2D
move_and_slide
FileAccess
@export
await

Por outro lado, é provável que o seguinte seja uma palavra comum do documento ou uma coluna de tabela.

Returns
See
Tip
MIT
Software
Type

Na prática, ao verificar o smoke test, descobri um problema em que colunas de tabelas comuns, como Type -> EditorSceneFormatImporterFBX2GLTF, podem ser capturadas como candidatos de mapeamento de API. Corrigimos isso excluindo Type dos candidatos de mapeamento.

A conclusão obtida aqui é clara.

**Amplamente extrair é necessário.**  
**Mas não se deve usar tudo que foi amplamente extraído como fato confiável.**

11. v3.1 Estrutura de separação de confiabilidade reformulada

Depois de identificar o risco acima, concluiu‑se que não era adequado usar o v3 diretamente no detector final de rótulos. Portanto, no v3.1 o catálogo não foi agrupado em um único bloco, mas foi separado por confiabilidade e por finalidade.

Estrutura recém‑definida no v3.1:

trusted_api_symbols
syntax_symbols
migration_mappings
mentioned_symbols
candidate_terms
rejected_terms
retrieval_keys
search_text

Também dividimos claramente o significado de cada campo.

*(Nenhum fragmento de Markdown foi fornecido para tradução.)*

Código adicionado:

work/godot_rag/build_v31_artifacts.py
work/godot_rag/validate_v31_artifacts.py

Entregável v3.1 gerado:

work/godot_rag/chunks/docs_chunks_v3_1.jsonl
work/godot_rag/chunks/docs_chunks_v3_1.summary.json
work/godot_rag/catalog_v3_1/trusted_api_catalog.jsonl
work/godot_rag/catalog_v3_1/syntax_catalog.jsonl
work/godot_rag/catalog_v3_1/api_mapping.jsonl
work/godot_rag/catalog_v3_1/mention_index.json
work/godot_rag/catalog_v3_1/keyword_index.json
work/godot_rag/catalog_v3_1/v3_1.summary.json
work/godot_rag/validation_v3_1/validation_report.json
work/godot_rag/validation_v3_1/retrieval_smoke_test.json

v3.1 resultado:

Source v2 chunks: 8,778
Output v3.1 chunks: 8,778
Trusted API catalog entries: 26,318
Syntax catalog entries: 68
API mapping records: 144
Mention index keys: 10,292
Keyword keys: 71,543
Validation status: pass
Retrieval smoke tests: 5 / 5 passed

Parte importante que também foi corrigida

No processo de criação da versão v3.1, confiar diretamente no class_name dos metadados da v2 podia fazer com que valores incorretos como Tutorials, All e String fossem inseridos no catálogo confiável. Por isso, o nome canônico da classe foi reconstruído a partir da URL de origem e do caminho de referência da classe. Após essa correção, problemas de capitalização como Characterbody2d foram ajustados para CharacterBody2D.

Outra verificação crucial foi a de move_and_slide. No método de extração amplo, havia risco de criar entradas falsas confiáveis, como ProjectSettings.move_and_slide. Na v3.1, limitamos a promoção a confiável apenas aos membros confirmados na seção estruturada da referência da classe. Como resultado, a entrada confiável move_and_slide permaneceu apenas nas classes reais do Godot, conforme mostrado a seguir.

CharacterBody2D.move_and_slide
CharacterBody3D.move_and_slide

Ou seja, o que foi feito no v3.1 hoje não foi apenas aumentar os campos, mas mudar para uma “estrutura que usa amplamente na pesquisa, mas usa apenas evidências estreitas e confiáveis na decisão de rótulos”.

12. Verificação de consistência do v3.1

No v3.1, a omissão era particularmente perigosa. Isso porque, se qualquer um dos 8.778 blocos do v2 fosse deixado de fora, a evidência da documentação oficial poderia desaparecer.

Critérios de verificação:

v2 chunk_id set == v3.1 chunk_id set  
v3.1 unique chunk_id count == 8,778  
manter a distribuição de doc_type  
remover campos mistos legados  
verificar integridade de referência do catálogo trusted/syntax/migration  
verificar existência de search_text

Resultado da verificação:

status: pass
errors: 0
warnings: 0
v2 chunks: 8,778
v3.1 chunks: 8,778

Executei novamente o teste de fumaça de pesquisa.

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Resultado passou em todos os 5 casos. O significado desta etapa não é “o rotulador final foi concluído”, mas sim que a estrutura v3.1 está suficientemente íntegra para avançar, ao menos, para um índice MVP de vetores/palavras‑chave.

13. Atualização no GitHub e organização dos registros

Hoje, além de criar os artefatos de código e dados, também organizei a atualização no GitHub.

Tarefas realizadas:

Configuração remota  
Divisão de arquivos v3 de grande tamanho  
Push da branch de trabalho  
Mesclar histórico local com main remoto  
Push do main  
Organização do diretório de documentos

docs_chunks_v3.jsonl tem cerca de 189 MB, então carregá‑lo inteiro poderia exceder o limite de tamanho de arquivo único do GitHub. Por isso ele foi dividido em docs_chunks_v3.part-000.jsonl, docs_chunks_v3.part-001.jsonl e docs_chunks_v3.part-002.jsonl.

Além disso, inicialmente as retrospectivas foram criadas na raiz retrospectives/, mas isso não correspondia à estrutura existente do repositório. Assim, a estrutura da documentação foi reorganizada da seguinte forma.

docs/research-notes/   Notas de design
docs/roadmaps/         Roteiro completo
docs/retrospectives/   Retrospectivas por data
work/godot_rag/        Código RAG e entregáveis
outputs/godot_docs_full/ Resultado da coleta de documentos oficiais

Além disso, criamos docs/README.md para organizar a função de diretório de documentação.

14. Organização de autor/e‑mail do Git

Como registrado no README de hoje, também resolvemos o problema de refletir o “grass” do GitHub.

Problemas verificados:

Os e‑mails de author/committer do histórico main estão misturados  
E‑mail do localhost  
E‑mail do Naver  
E‑mail noreply do GitHub

Direção processada:

Alterar a configuração global do Git para yyeongjin <appsky1888@gmail.com>  
Unificar autor/commitante no histórico do main  
Aplicar ao remoto  
Preservar branch de backup antes da reescrita

Branch de backup:

backup/before-author-email-rewrite-2026-06-17

Esta tarefa não está diretamente ligada ao próprio RAG, mas foi uma das importantes atividades de organização de hoje. Foi um trabalho de base para que os registros e commits subsequentes fossem refletidos corretamente no perfil do GitHub.

15. Documentos criados/organizados hoje

Principais documentos criados ou organizados hoje:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md
docs/roadmaps/2026-06-17-godot-llm-roadmap.md
docs/retrospectives/2026-06-17-godot-rag-judge.md
docs/README.md

Também adicionei a seção de diário de desenvolvimento de 17 de junho e a preparação de dados RAG ao README.

16. Conclusão Atual

O estado atual pode ser resumido assim.

Direção:
Não deve ser o modelo Godot Q&A, mas sim o Godot SWE Agent.

Dados:
O RAG da documentação oficial deve atuar como um discriminador para a geração de dados de treinamento.

Rótulo:
Deve ser decidido por um pipeline Python, não por LLM.

RAG:
v2 é um conjunto de blocos básico e seguro.  
v3 é um produto de catálogo intermediário extraído amplamente.  
v3.1 é o produto RAG recomendado atualmente, com separação de confiabilidade aplicada.

Risco:
Não se deve usar todos os símbolos extraídos com o mesmo nível de confiança.

Hoje o trabalho não consistiu apenas em criar alguns arquivos, mas foi um dia em que tivemos que mudar de direção várias vezes para evitar caminhos enganosos. Em particular, foram importantes as decisões de reverter o chunk de API hard‑coded focus, de identificar o risco de ruído no broad v3 e de separar trusted/syntax/migration/mention/candidate/rejected no v3.1.

17. Próximas tarefas

A próxima tarefa não é rotular código no GitHub.

Primeiros passos:

1. Gerar embeddings a partir de search_text em docs_chunks_v3_1.jsonl
2. Testar recuperação híbrida combinando busca vetorial + busca por palavra‑chave
3. Projetar pipeline Python para determinar rótulos com base em trusted_api_symbols, syntax_symbols e migration_mappings
4. Definir o formato de entrada dos dados de estruturação do repositório GitHub
5. Projetar fluxo de decisão em nível de repositório que analise .gd, .tscn, .tres, project.godot e README em conjunto
6. Conectar o resultado do classificador RAG a um pipeline que gera um dataset JSONL de 8 tipos
7. Quando o endpoint remoto de LLM estiver pronto, integrar para auxiliar na geração de código/modificações, explicações e candidatos SFT/DPO
8. Expandir posteriormente com aprendizado de trajetória SFT/DPO baseado em Qwen e agente SWE

A lição final de hoje é esta.

É mais importante separar com que confiabilidade usar o conhecimento acumulado do que simplesmente coletar muitos documentos.