Configurando PostgreSQL Local para o Classificador RAG do Godot

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

Objetivo

Configurar um banco de dados PostgreSQL local para o classificador RAG da documentação oficial do Godot. O fluxo padrão é o seguinte.

JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6

O objetivo da fase atual não é gerar dados de treinamento, mas tornar possível reproduzir localmente um banco de dados de evidências baseado em documentação oficial. Mantenha a coluna payload da tabela com o mesmo nome do esquema JSONL e, para colunas derivadas de operação do banco, inclua apenas as colunas mínimas necessárias para busca/armazenamento, como id, embedding, search_tsv, created_at.

Documento de design de referência:

docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md

Configuração do DB local

Arquivo Docker Compose:

infra/postgres/docker-compose.yml

Imagem usada:

pgvector/pgvector:pg16

Informações de conexão:

Item	Valor
database	`godot_rag`
user	`godot_rag`
password	`godot_rag_local`
host	`localhost`
port	`5432`

URL base para desenvolvimento local:

postgresql://godot_rag:godot_rag_local@localhost:5432/godot_rag

Extensões geradas

extension	Objetivo
`vector`	Armazenamento de embeddings de chunks de documentos e protótipos de rótulos
`pg_trgm`	Assistência para busca fuzzy/parcial de nomes de API, headings e símbolos

Atenção:

A coluna embedding é do tipo vector que não fixa a dimensão atual.  
Como os índices HNSW/IVFFlat do pgvector requerem dimensão fixa,  
o índice vector real é criado em uma migração separada após a dimensão do modelo de embedding ser definida.

Modelo:

infra/postgres/init/004_vector_index_templates.sql

Esquema Gerado

Nome do esquema DB:

godot_rag

Tabela:

Tabela	Função
`godot_rag.docs_chunks`	Trechos de documentação oficial, tutoriais, referência de classes
`godot_rag.api_mapping`	Regras de mudança, renomeação, substituição, descontinuação da API Godot 3 → 4
`godot_rag.label_prototypes`	Protótipos de exemplos de classificação/transformação/rejeição/edição
`godot_rag.ingest_reports`	Avisos, pulos e logs de validação do processo de conversão/inserção JSONL

Design da Tabela

`docs_chunks`

Armazena trechos da documentação oficial. Cada linha deve preservar a URL original, o caminho do arquivo original e o hash do Markdown original.

Principais colunas:

Coluna	Descrição
`chunk_id`	ID determinístico que não muda em reexecuções
`doc_version`	Versão da documentação, como `stable`, `4.6`, etc.
`source_url`	URL original da documentação oficial do Godot
`source_file`	Caminho do Markdown no repositório
`source_sha256`	Hash SHA‑256 do Markdown original
`doc_type`	Tipo de documento, como `class_reference`, `tutorial`, `migration`, etc.
`symbol`	Símbolo representativo da classe/API
`section_path`	Hierarquia de títulos em JSON
`content`	Texto principal para busca e incorporação
`code_blocks`	Array de blocos de código extraídos do texto
`api_symbols`	Símbolos da API Godot detectados no texto
`embedding`	Incorporação pgvector
`search_tsv`	tsvector para busca por palavras‑chave

`api_mapping`

Armazena as regras de mudança Godot 3/4.

Princípios importantes:

Se houver base na documentação oficial, defina confidence = 'verified_from_docs'.
Regras de extração automática ainda não revisadas recebem confidence = 'candidate'.
Regras usadas diretamente para treinamento/rotulagem devem ser revisadas por uma pessoa e então marcadas como confidence = 'approved' ou gerenciadas via JSONL de aprovação separado.

`label_prototypes`

Armazena os critérios de rótulo e padrões representativos da saída do classificador.

Rótulos iniciais candidatos:

Rótulo	Significado
`godot4_valid_api`	Uso de API válida segundo o Godot 4
`godot3_api_in_godot4`	API do Godot 3 misturada em projeto Godot 4
`deprecated_or_removed_api`	Uso de API removida ou descontinuada
`migration_required`	Necessidade de migração de Godot 3 → 4
`ambiguous_version_signal`	Falta de evidência ou conflito para determinar a versão
`non_godot_noise`	Dados não relacionados ao Godot (Python/Web/Unity, etc.)
`unsafe_or_obfuscated_code`	Código ofuscado, caracteres de controle, suspeita de malware

Como Executar

Iniciar o DB:

docker-compose -f infra/postgres/docker-compose.yml up -d

No ambiente local atual, usa‑se o comando docker-compose em vez do plugin docker compose.

Checagem de saúde:

docker inspect --format='{{json .State.Health.Status}}' godot-rag-postgres

Conectar dentro do contêiner:

docker exec -it godot-rag-postgres psql -U godot_rag -d godot_rag

Verificar tabela:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "\\dt godot_rag.*"

Verificação de expansão:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "select extname from pg_extension where extname in ('vector', 'pg_trgm') order by extname;"

Inicialização

Use apenas quando for recriar o banco de dados completamente. Tenha cuidado, pois o volume local será excluído.

docker-compose -f infra/postgres/docker-compose.yml down -v
docker-compose -f infra/postgres/docker-compose.yml up -d

Caminho de injeção JSONL planejado

Ainda não criamos o script de injeção. Primeiro, gere e valide a saída JSONL abaixo e, em seguida, anexe o script upsert.

Arquivo	Tabela de destino
`work/godot_rag/jsonl/docs_chunks.jsonl`	`godot_rag.docs_chunks`
`work/godot_rag/jsonl/api_mapping.jsonl`	`godot_rag.api_mapping`
`work/godot_rag/jsonl/label_prototypes.jsonl`	`godot_rag.label_prototypes`
`work/godot_rag/jsonl/ingest_report.jsonl`	`godot_rag.ingest_reports`

Próximas tarefas

Criar um relatório de análise da estrutura outputs/godot_docs_full/pages.
Definir os critérios de chunking por tipo de documento.
Escrever o script de validação de esquema para docs_chunks.jsonl.
Escrever o script de upsert JSONL.
Verificar a qualidade da busca do Retriever com perguntas de exemplo.