Esquema e Arquitetura do Classificador RAG da Documentação Oficial do Godot

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

Propósito

Organizar a arquitetura de referência para conectar a coleta completa da documentação oficial do Godot ao fluxo JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6. Este documento não é um guia de implementação para gerar dados de treinamento, mas sim um critério de design que define como estruturar a documentação Markdown já reunida em outputs/godot_docs_full/pages e transformá‑la em um banco de dados de evidências pesquisável.

Dados de entrada atuais

Os resultados da coleta da documentação oficial estão localizados em outputs/godot_docs_full no repositório.

Linha de base atual:

Pipeline completa

1. O crawler coleta a documentação oficial do Godot da internet.
2. Os resultados são armazenados como Markdown por página.
3. O Markdown é normalizado e enriquecido com metadados, sendo convertido em registros JSONL.
4. Os JSONL são inseridos no PostgreSQL.
5. O PostgreSQL armazena separadamente chunks de documentos, mapeamento de API e protótipos de rótulos.
6. Quando o usuário solicita análise do código‑fonte do Godot, o AST Parser estrutura o código do projeto.
7. O Retriever busca evidências no PostgreSQL com base na pergunta do usuário e nos resultados da análise AST.
8. O Validator agrupa a pergunta, o resultado AST e as evidências encontradas e os envia ao Qwen 3.6.
9. O Qwen 3.6 não atua como julgador final; ele elabora a resposta usando as evidências validadas.
10. O Validator verifica a evidência, o formato e padrões proibidos da resposta antes de devolvê‑la ao usuário.

Conversão de Markdown para JSONL

pages/*.md são as páginas originais legíveis por humanos, mas são unidades muito grandes para RAG. Portanto, o script de conversão divide as páginas em seções/membros de API/exemplos, preservando a URL original e o tipo de documento.

Regras comuns de normalização

Saídas JSONL

Esquema de docs_chunks.jsonl

{
  "chunk_id": "godot-stable:classes/class_node.html#description:0001",
  "doc_version": "stable",
  "source_url": "https://docs.godotengine.org/en/stable/classes/class_node.html",
  "source_file": "outputs/godot_docs_full/pages/classes__class_node__....md",
  "source_sha256": "...",
  "doc_type": "class_reference",
  "symbol": "Node",
  "section_path": ["Node", "Description"],
  "heading": "Description",
  "content": "Nodes are Godot's building blocks...",
  "code_blocks": [],
  "language_tags": ["gdscript"],
  "godot_version_tags": ["4.x", "stable"],
  "api_symbols": ["Node", "_ready", "_process", "queue_free"],
  "token_count": 420,
  "metadata": {
    "status": "copied_old",
    "bytes": 12345
  }
}

Obrigatório campos:

Esquema api_mapping.jsonl

{
  "mapping_id": "godot3-to-4:kinematicbody2d-to-characterbody2d",
  "source_api": "KinematicBody2D",
  "target_api": "CharacterBody2D",
  "change_type": "rename_or_replacement",
  "godot_from": "3.x",
  "godot_to": "4.x",
  "confidence": "verified_from_docs",
  "evidence_chunk_ids": [
    "godot-stable:tutorials/migrating/upgrading_to_godot_4.html#..."
  ],
  "match_terms": ["KinematicBody2D", "CharacterBody2D"],
  "notes": "Godot 4 character movement node replacement candidate.",
  "negative_patterns": ["do not suggest KinematicBody2D for Godot 4 projects"]
}

Princípios:

Esquema label_prototypes.jsonl

{
  "prototype_id": "label:godot3-api-in-godot4:kinematicbody2d",
  "label": "godot3_api_in_godot4",
  "task_type": "version_classification",
  "input_pattern": "extends KinematicBody2D",
  "expected_finding": "Godot 3 style physics body API detected.",
  "recommended_action": "Use CharacterBody2D or CharacterBody3D depending on project dimension.",
  "evidence_mapping_ids": [
    "godot3-to-4:kinematicbody2d-to-characterbody2d"
  ],
  "evidence_chunk_ids": [],
  "severity": "high",
  "validator_rules": {
    "requires_ast_symbol": "KinematicBody2D",
    "forbidden_answer_terms": ["KinematicBody2D is recommended in Godot 4"]
  }
}

Candidatos de rótulo:

Rascunho de esquema PostgreSQL

O PostgreSQL assume, por padrão, o uso de pgvector. A busca por palavras‑chave utiliza tsvector ou índice trigram.

docs_chunks

Índices:

api_mapping

Índices:

label_prototypes

Índices:

Entrada/Saída do AST Parser

O AST Parser converte o código‑fonte do usuário em uma estrutura pesquisável antes de enviá‑lo ao LLM. O alvo inicial são arquivos .gd, .tscn e project.godot.

Entrada

Saída do esquema

{
  "project_id": "local-analysis-...",
  "godot_project": {
    "config_version": 5,
    "features": ["4.4", "Forward Plus"]
  },
  "files": [
    {
      "path": "scripts/player.gd",
      "language": "gdscript",
      "extends": "CharacterBody2D",
      "class_name": "Player",
      "symbols": ["CharacterBody2D", "Input", "move_and_slide"],
      "annotations": ["@onready"],
      "version_signals": ["godot4_annotation_syntax"],
      "diagnostics": []
    }
  ],
  "version_evidence": {
    "godot4": ["config_version=5", "@onready"],
    "godot3": []
  }
}

Inicial Campos de Extração:

Funcionamento do Retriever

O Retriever é a camada que seleciona evidências antes do LLM.

1. Extrai a intenção e a tarefa alvo a partir da pergunta do usuário.
2. Obtém símbolos de API, sinais de versão e caminhos de arquivos a partir do resultado do AST Parser.
3. Executa primeiro uma busca exata em api_mapping.
4. Realiza simultaneamente filtragem de símbolos de API + busca por palavras‑chave + busca vetorial em docs_chunks.
5. Obtém rótulos semelhantes e regras de validação de label_prototypes.
6. Ordena os resultados da busca como pacotes de evidência.

Pacote de evidência:

{
  "query_id": "analysis-...",
  "task_type": "version_classification",
  "ast_summary": {},
  "doc_evidence": [],
  "api_mapping_evidence": [],
  "label_evidence": [],
  "retrieval_scores": {
    "exact_api_hits": 2,
    "keyword_hits": 8,
    "vector_hits": 12
  }
}

Separação de papéis entre Validator e Qwen 3.6

Qwen 3.6 é o modelo que lê as evidências encontradas e organiza a resposta. A rotulagem final, a adoção de evidências e a validação de padrões proibidos são responsabilidade do Validator.

Itens que o Validator deve conferir:

Ordem de injeção

1. Verifique outputs/godot_docs_full/summary.json e failed.json.
2. Carregue manifest.json e pages/*.md.
3. Gere o relatório de normalização de Markdown.
4. Crie docs_chunks.jsonl.
5. Na documentação migration/class, gere candidatos para api_mapping.jsonl.
6. Crie label_prototypes.jsonl a partir de regras aprovadas e casos representativos.
7. Apenas registros que passam na validação de esquema JSONL são upsertados no PostgreSQL.
8. Gere embeddings e atualize o índice vetorial.
9. Atualize o índice de palavras‑chave e o índice exato.
10. Valide os resultados do Retriever com perguntas de amostra.

Checklist de verificação de qualidade

Prioridades de implementação

1. Elaborar relatório de análise da estrutura de pages/*.md
2. Escrever script de conversão para docs_chunks.jsonl
3. Criar script de validação de esquema JSONL
4. Redigir DDL do PostgreSQL
5. Injetar docs_chunks e validar busca
6. Gerar candidatos de api_mapping e definir fluxo de aprovação manual
7. Criar conjunto inicial de etiquetas em label_prototypes
8. Extrair campos mínimos com o AST Parser
9. Emitir bundle de evidências do Retriever
10. Conectar loop de organização de respostas Validator + Qwen 3.6

Princípios fundamentais

• O Markdown original da documentação oficial não deve ser alterado, apenas preservado.
• JSONL é tratado como artefato intermediário reproduzível.
• O banco de dados deve registrar caminho original, URL original, hash e versão do script de conversão.
• Impedir que o LLM invente etiquetas.
• Decisões Godot 3/4 são baseadas em sinal AST, mapeamento de API e evidências da documentação oficial.
• Candidatos incertos não são usados diretamente como dados de treinamento; permanecem no estado candidate.
• Qwen 3.6 atua como organizador de respostas; os critérios de decisão são definidos pelo Retriever e Validator.

Próximas tarefas

A próxima etapa é analisar amostras da estrutura de Markdown em outputs/godot_docs_full/pages. Como as referências de classe, migração e tutoriais possuem estruturas diferentes, é necessário definir estratégias de chunking específicas por tipo de documento, em vez de aplicar uma única regra universal.