idea_world_labDEV JOURNAL
domingo, 28 de junho de 2026

Alternativas de Busca Retriever – Documentação Desmembrada

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

Este diretório é um conjunto de documentos reorganizados para facilitar a visualização da nota original do ChatGPT sobre alternativas de busca Retriever.

A nota original é mantida intacta. Este README reúne contexto comum, abordagem atual, candidatos de modelo e guia de escolha. Os documentos subordinados contêm apenas as descrições de cada alternativa.

Tabela Comparativa Geral

Essas tabelas não são a escolha final, mas sim observações para avaliar, em 28 de junho, as alternativas de busca em uma única tela. O critério é: “quando o trecho de código é inserido no Retriever, qual candidato JSONL aparece e esse candidato pode ser aceito como evidência direta na fase de validação do Qwen?”

Conclusão em Um Relance

Alternativa Localização Papel esperado Pronto para uso imediato Principais vantagens Principais riscos Avaliação atual
A. PostgreSQL full-text mantido Base atual /api/retrieve Verificar até onde a busca implementada funciona Alta Já está integrado e os logs são visíveis imediatamente Trechos longos de código podem gerar consultas que percam documentos relevantes Mantido como baseline, sem ser definido como método final
B. Apenas BM25 Candidato de busca de primeira fase Encontrar documentos onde strings de código/API aparecem diretamente Média Forte para strings literais como KinematicBody2D, move_and_slide, AnimatedSprite2D Palavras amplas como 2D/3D podem gerar falsos positivos Boa opção para o primeiro PoC
C. Apenas embedding Expansão de recall baseada em significado Encontrar documentos relacionados mesmo que a string não seja idêntica Média Captura sentido de frases, tutoriais e contextos de uso semelhantes Risco alto de uso isolado para avaliação de versão/API Usado como recall auxiliar, não como solução única
D. BM25 + embedding Compromisso realista intermediário Combinar evidências textuais e semânticas Média Une a precisão do BM25 com o recall do embedding Necessita combinação de pontuações, remoção de duplicatas e critério de seleção superior Aproxima-se da solução mínima prática
E. Perfil de consulta Qwen Experimento de apoio à busca Gerar JSON que descreva a intenção de busca a partir do trecho de código Baixa O perfil de consulta gerado por humanos é fácil de ler O LLM pode criar APIs/intenção inexistentes antes da busca Mais adequado como experimento/auxílio que como núcleo da primeira busca
F. BM25 + embedding + reranker + validador Estrutura de candidato final Gera candidatos, reordena e verifica evidência direta Baixa Melhor qualidade e observabilidade Custo, latência e número de etapas elevados Destinado ao candidato final desejado

Comparação dos Resultados da Simulação PoC

Alternativa Trecho de entrada Como os candidatos de busca são gerados Probabilidade de aparecer JSONL relevante Probabilidade de misturar JSONL irrelevante Estado esperado antes da validação Qwen Estado esperado após a validação Qwen
A Texto completo do chunk Gera query longa com plainto_tsquery('simple', chunkText) Baixa ou instável Pode ser baixa, mas se 0 candidatos, nada a observar Nenhum ou poucos candidatos retornados Pode ser descartado antes da verificação de evidência direta
B Texto completo do chunk Rankea documentos por pontuação BM25 por token Alta Média Documentos como Input.is_action_pressed, AnimatedSprite2D, clamp podem aparecer Descarta se a string literal não estiver presente
C Texto completo do chunk Similaridade de embedding code/document Média Alta Documentos amplos sobre “movement”, “2D”, “player” podem aparecer Descarta se o JSONL não contiver a string literal
D Texto completo do chunk Combina candidatos BM25 e embedding Alta Média Candidatos textuais e semânticos aparecem juntos Mantém apenas candidatos com evidência direta
E Texto completo do chunk interpretado pelo Qwen Busca usando o perfil de consulta gerado Média se o perfil estiver correto Alta APIs não listadas no perfil podem aparecer Necessita validar se o perfil corresponde ao código real
F Texto completo do chunk Reranker reorganiza candidatos BM25 + embedding Alta Baixa Muitos candidatos, mas os superiores são filtrados Qwen deixa apenas “sim/não” com evidência direta

Diferenças Evidenciadas na Avaliação Demo

Situação observada Prompt simples inicial Prompt aprimorado com evidência direta Significado para a estrutura de busca
Código Godot 3 + JSONL relacionado Pode gerar “sim” Deve gerar “sim” Passa se a evidência corresponder à string/API real
Código Godot 3 + JSONL não relacionado Palavras amplas de Godot podem gerar “sim” Deve gerar “não” Sem verificação de evidência direta, há risco mesmo com candidatos retornados
Código KinematicBody2D + mapeamento 3D Spatial Pode ser considerado relacionado por “migração Godot” Deve gerar “não” Embedding apenas ou julgamento frouxo do LLM pode gerar falsos positivos
Código yield(...) + protótipo await “Sim” se houver padrão direto “Sim” label_prototypes pode servir como evidência de mudança de padrão de uso
Código AnimatedSprite2D.play() + docs de animação genérica Pode parecer semanticamente relacionado “Não” se o JSONL não contiver a string/padrão Mesmo chunks de docs precisam de verificação de evidência direta na decisão final

Comparação de Como os Candidatos São Retornados

Alternativa Candidatos que sobem bem ao topo Candidatos que tendem a ser perdidos Candidatos que se misturam indevidamente Pontos a observar visualmente
A Documentos que contêm muitos tokens da query em uma única linha Quando tokens relevantes estão distribuídos em vários documentos Quase nenhum se a query for muito restrita Por que 0 resultados? Que token quebrou o match?
B Linhas que contêm nome da API, função ou nó diretamente Documentos descritivos onde a expressão mudou Documentos de outros sistemas que usam o mesmo termo Verificar se match_terms coincide com a string do chunk fonte
C Tutoriais ou explicações semanticamente semelhantes Mapeamento API curto e exato Docs de versões diferentes do Godot ou 2D/3D divergentes Além da pontuação de cosseno, há evidência de string direta?
D Candidatos exatos + semânticos Perde candidatos na combinação de pontuações Candidatos que correspondem levemente a ambas as buscas Identificar se o candidato veio do BM25 ou do embedding
E Candidatos que correspondem à intenção extraída pelo Qwen Evidências reais de código que o Qwen não incluiu no perfil APIs/intenções imaginadas pelo Qwen Cada campo do perfil está realmente presente no chunk?
F Candidatos que o reranker julgou compatíveis com o chunk Casos especiais de Godot desconhecidos pelo modelo de reranker Alta pontuação de reranker, mas sem evidência direta no JSONL Onde o score do reranker diverge da decisão do validador?

Comparação de Falso Positivo / Falso Negativo

Alternativa Exemplo de falso positivo Exemplo de falso negativo Como reduzir
A Raramente, se a consulta for muito ampla, documentos de movimento geral se misturam Quando documentos relacionados são divididos em várias linhas, resulta em 0 ocorrências Alterar o modo de geração da consulta ou adicionar candidatos BM25
B movement, player, 2d fazem com que documentos de movimento diferentes se misturem Se o nome da API aparecer apenas de forma descritiva nos documentos, ele é omitido Separar stopwords/token fracos, ponderar tokens de API diretamente
C Documentos 3D ou de outra versão com significado semelhante se misturam Não captura linhas curtas de renomeação de API Usar BM25 em paralelo e acrescentar validador
D Candidatos que combinam fracamente tanto em BM25 quanto em embedding se misturam Se o critério de fusão estiver errado, um dos candidatos pode ser suprimido Registrar flag de origem da união e log de evidência direta
E Qwen cria migration_intent inexistente, contaminando os candidatos Qwen omite pistas reais de código no perfil Não confiar no perfil antes da busca, usá‑lo apenas como auxílio
F O reranker superestima explicações plausíveis Documentos que não foram obtidos na fase de geração de candidatos Garantir número suficiente de candidatos e colocar a validação Qwen por último

Adequação por Tabela

Alternativa docs_chunks api_mapping label_prototypes Observações
A Instável em documentos longos Pode perder linhas curtas de mapeamento exato Pode perder linhas curtas de padrão Linha de base para entender limitações do método atual
B Boa para busca de API/título/token Boa para busca exata de API fonte/alvo Boa para busca de padrão fonte/alvo Útil observar como primeira escolha em todas as três tabelas
C Boa para recall de documentos descritivos Fraca em linhas curtas como renomeação de API Pode auxiliar quando padrões de uso são semelhantes Mais natural como apoio ao docs_chunks
D Captura todos os candidatos de descrição/strings Captura tanto mapeamento exato quanto candidatos semânticos Amplia candidatos de padrão de uso como um todo Estrutura comum a todas as três tabelas, a mais equilibrada
E Permite busca de documentos descritivos se o perfil da consulta for bom Arriscado se APIs alucidadas forem incluídas Pode gerar protótipos de intenção, mas pode contaminar Mais um experimento de observação/apoio que busca central
F Boa para refinar a justificativa final Boa para refinar a justificativa de migração Boa para refinar a justificativa de mudança de uso Facilita tratar as três tabelas no mesmo pipeline

O que Deve Ser Verificado nos Logs

Alternativa Log antes da busca Log durante a busca Log após a busca Pontos para confirmar a causa da falha
A chunkText bruto, tsquery gerado Número de hits search_tsv @@ query, ts_rank_cd Linhas retornadas, pontuação A consulta ficou muito longa? Que tokens faltam nas linhas?
B chunkText bruto, lista de tokens Frequência de termos, termos correspondidos, pontuação BM25 Top‑k por tabela Tokens fortes e fracos estão sendo diferenciados?
C chunkText bruto, modelo de embedding Distância vetorial/ pontuação de cosseno Top‑k semântico São candidatos que correspondem apenas ao sentido, sem texto?
D Top‑k BM25, top‑k embedding União, mescla de duplicados, fusão de pontuações Lista de candidatos com flags de origem Por que candidatos obtidos por apenas um caminho sobreviveram?
E Chunk bruto enviado ao Qwen JSON de perfil de consulta do Qwen Resultados de busca baseados no perfil O campo do perfil realmente existe na fonte?
F Todos os candidatos BM25/embedding Pontuação e ordem do rerank 예/아니오 do Qwen, motivo de rejeição Por que candidatos aprovados pelo reranker falharam na validação de evidência direta?

Complexidade de Implementação e Custo Operacional

Alternativa Esforço de implementação Alterações no DB Custo de modelo externo Latência Dificuldade de depuração Facilidade de correção após falha
A Baixa Quase nenhuma Nenhum Baixa Baixa Baixa. Contudo, limites de desempenho podem ser estruturais
B Média Necessita escolha de motor/índice BM25 Nenhum ou baixo Baixa Baixa Alta. Ajustes de token/peso são possíveis
C Média Requer coluna/índice de embedding Existe Média Média Média. Ajustes de modelo, dimensão e limiar são necessários
D Média‑alta Precisa de BM25 + vetor Existe Média Média Alta. Possível isolar qual caminho de busca falhou
E Média Armazenamento de perfil opcional Existe Alta Alta Baixa. Reproduzir por que o perfil LLM errou pode ser difícil
F Alta Necessita logs de BM25, vetor e rerank Existe Alta Alta Alta. Logs passo a passo mostram onde corrigir

Comparação de Onde Posicionar o Qwen

Posição Vantagens Riscos Uso mais adequado atualmente
Geração de consulta antes da busca Permite criar intenção de busca sem hard‑code Pode gerar pistas inexistentes e contaminar a busca Apenas para experimentos
Validação direta após candidatos da busca Filtra resultados que realmente correspondem ao código Custo de chamada Prioridade máxima
Geração de resposta final Pode produzir explicações de código/migração Resposta errada se a evidência estiver incorreta Após candidatos JSONL validados
Integração de decisão completa Produz conclusão legível para humanos Pode esconder falhas intermediárias Quando logs são suficientes para revisão

Prioridade de Escolha

Prioridade Opção Motivo Pergunta a ser respondida nesta fase
1 Medir A como linha de base Necessário saber onde a implementação atual quebra Quantas linhas o método atual realmente devolve?
2 Acrescentar B como PoC separado Busca por strings de código/API é a mais explicável KinematicBody2D, yield, move_and_slide encontram a linha correta?
3 Comparar C como recall auxiliar Pode ampliar candidatos descritivos de docs_chunks Quantos candidatos semânticos são rejeitados na validação direta?
4 Gerar candidatos paralelos com D Estrutura mínima realista A qualidade melhora ao combinar candidatos BM25 e embedding?
5 Adicionar reranker/validador com F Verificar qualidade final O Qwen descarta de forma estável JSONL que não tem evidência?
Em espera E LLM antes da busca tem alto risco de contaminação O perfil é criado apenas a partir de strings reais de código?

Lista de Verificação de PoC

Item de Verificação Tela/Log a Ser Verificado Critério de Sucesso
Inserir o mesmo chunkText em várias alternativas Área de entrada de chunk do depurador web A entrada não varia entre as alternativas
Botão de busca por tabela Botões docs_chunks, api_mapping, label_prototypes Diferenças nos candidatos por tabela são exibidas com o mesmo chunk
Verificação de candidatos brutos Payload JSONL retornado Campos correspondem à string real dentro do chunk de origem
Verificação de validação do Qwen Área de depuração prompt + chunk + jsonl Candidatos relevantes mostram “sim”, candidatos irrelevantes mostram “não”
Verificação de motivo de rejeição Log de resultados do validador Candidatos que só correspondem a palavras amplas como Godot, migration, 2D são rejeitados
Coleta de falsos positivos Lista de candidatos rejeitados Pode ser usada posteriormente para melhorar regras de query/token/validador
Salvamento de comparação por alternativa Diário de observação ou JSON de resultados Diferenças de A‑F permanecem para a mesma entrada

Documentos das Alternativas

Premissa Atual

A premissa atual é a seguinte.

1. O zip contém o markdown original, o esquema, o depurador e a documentação de design.  
2. O local já possui a versão convertida de markdown → JSONL → DB.  
3. O que pode ser visto agora são o markdown antes da conversão e o esquema/fluxo de busca do DB.  
4. O PoC deve dividir o markdown dentro do zip em pedaços semelhantes a JSONL chunk e simular os alvos de busca que poderiam ter sido inseridos no DB local.  
5. O necessário não é a estrutura do código, mas rastrear como cada método de busca gera pontuações e por que tem sucesso ou falha quando um chunk é inserido.

JSONL/DB padrão

Os entregáveis baseados no documento são os seguintes.

work/godot_rag/jsonl/docs_chunks.jsonl
work/godot_rag/jsonl/api_mapping.jsonl
work/godot_rag/jsonl/label_prototypes.jsonl
work/godot_rag/jsonl/ingest_report.jsonl

Entende‑se que o banco de dados não insere uma linha inteira de JSONL no payload jsonb, mas sim que os campos do JSONL são expandidos como colunas da tabela.

docs_chunks

chunk_id
doc_version
source_url
source_file
source_sha256
doc_type
symbol
section_path
heading
content
code_blocks
language_tags
godot_version_tags
api_symbols
token_count
metadata
embedding
search_tsv

api_mapping

mapping_id
source_api
target_api
change_type
godot_from
godot_to
confidence
evidence_chunk_ids
match_terms
notes
negative_patterns

label_prototypes

prototype_id
label
task_type
input_pattern
expected_finding
recommended_action
evidence_mapping_ids
evidence_chunk_ids
severity
validator_rules
embedding
search_tsv

Chunk de referência

O chunk usado como referência na comparação de alternativas é o seguinte código Godot.

func _process(delta):
	var velocity = Vector2.ZERO
	if Input.is_action_pressed(&"move_right"):
		velocity.x += 1
	if Input.is_action_pressed(&"move_left"):
		velocity.x -= 1

	if velocity.length() > 0:
		velocity = velocity.normalized() * speed
		$AnimatedSprite2D.play()
	else:
		$AnimatedSprite2D.stop()

	position += velocity * delta
	position = position.clamp(Vector2.ZERO, screen_size)

Token forte:

animatedsprite2d
is_action_pressed
move_left
move_right
normalized
clamp
screen_size
vector2
zero

Token fraco:

func
var
if
else
velocity
position
delta
x
0
1

A entrada de pesquisa continua exatamente como chunkText. Não consideramos essencial, como parte central do design básico, extrair obrigatoriamente o sinal da API do Godot antes da pesquisa e convertê‑lo em uma consulta separada. Caso seja necessário, isso será revisado apenas como um ponto de pontuação auxiliar posteriormente.

Método atual /api/retrieve

O /api/retrieve do projeto atual não utiliza BM25.

O fluxo se assemelha ao seguinte.

chunkText
  -> plainto_tsquery('simple', chunkText)
  -> search_tsv @@ query
  -> ts_rank_cd(...)

PostgreSQL's ts_rank_cd é uma função de classificação de texto completo. Diferente do BM25, que combina frequência de termos, frequência inversa de documentos e normalização do comprimento do campo em um algoritmo de busca estilo BM25, o ts_rank_cd deve ser visto de outra forma.

plainto_tsquery(raw_chunk) extrai tokens do chunk de entrada e cria a consulta. O chunk de referência pode se tornar uma consulta longa como a seguir.

func & process & delta & var & velocity & vector2 & zero
& input & is_action_pressed & move_right & move_left
& length & normalized & speed & animatedsprite2d
& play & stop & position & clamp & screen_size

Esta abordagem pode exigir muitos tokens dentro de uma única linha.

Se o chunk da documentação oficial estiver dividido como a seguir, surgirá um problema.

chunk A:
  Input.is_action_pressed
  velocity.normalized
  AnimatedSprite2D.play/stop

chunk B:
  Descrição do AnimatedSprite2D
  position.clamp
  screen_size

Ambos são relevantes, mas pode não haver todos os tokens simultaneamente em uma única linha.

Na nota original, acredita‑se que uma busca do tipo strict raw AND pode falhar da seguinte maneira.

strict raw AND hits: 0

A abordagem atual pode ser considerada uma linha de base para a PoC, mas é fraca para ser mantida como estratégia de busca final. Na próxima etapa, deve‑se separar e comparar a abordagem atual com o BM25.

Candidatos de modelo

voyage-code-3

Foi mencionado como o candidato de embedding que melhor se adapta ao projeto atual.

Razão:

A consulta não é uma pergunta em linguagem natural, mas um trecho de código GDScript.  
O JSONL de destino da pesquisa também contém blocos de código, nomes de API e descrições de documentos.

Vantagens:

  • É forte em recuperação de código.
  • É vantajoso para processar chunks longos.
  • Adequado para busca de código -> documentos.

Desvantagens:

  • Depende de APIs externas.
  • Tem custo.
  • Não é um modelo especializado para Godot.

Recomendação baseada em memória:

voyage-code-3 1024 float

OpenAI text-embedding-3-large

Embedding genérico de alta qualidade.

Vantagens:

  • É forte em recuperação semântica genérica.
  • É estável na busca por descrições de documentos.
  • É fácil de integrar ao ecossistema OpenAI.

Desvantagens:

  • Não é dedicado exclusivamente à recuperação de código.
  • A dimensionalidade base é grande, o que pode aumentar os custos de armazenamento/índice.
  • Para busca de chunks GDScript → JSONL pode ser menos direta que o voyage-code-3.

Recomendação baseada em memória:

2ª prioridade

Gemini Embedding

Candidato de recuperação semântica universal/multilíngue.

Vantagens:

  • É bom para recuperação baseada em descrição de documentos.
  • Possui opções de redução de dimensionalidade.
  • Pode ter pontos fortes na busca de documentos em múltiplos idiomas.

Desvantagens:

  • Não é uma opção exclusiva para recuperação de código.
  • Prioriza similaridade semântica mais que a exatidão do código da API.
  • O uso isolado pode ser arriscado para julgamentos exatos de migração do Godot.

Jina embeddings v4

Candidato com pontos fortes em recuperação de documentos complexos, multimodais e visualmente ricos.

Vantagens:

  • Abrange um amplo espectro de busca de documentos.
  • É forte em documentos multimodais/combinados.
  • Também é possível considerar a família de adaptadores de código.

Desvantagens:

  • O projeto atual está focado em markdown/código.
  • Busca de imagens/tabelas não é o foco principal.
  • Nesta fase, pode ser uma escolha excessiva.

Recomendação baseada em notas:

Agora, a prioridade é baixa.

rerank-2.5

Foi mencionado como candidato a reranker.

Função:

Compara novamente os candidatos trazidos por BM25 e embedding com o raw chunk.  
Reordena os candidatos com base na pontuação de relevância.

Este projeto espera os seguintes efeitos:

  • Reduzir falsos positivos em movimentos 2D e 3D.
  • Refletir melhor o contexto direto de itens como AnimatedSprite2D, Vector2, screen_size, position.clamp.
  • Organizar os candidatos trazidos por BM25 e embedding como candidatos finais.

Atenção:

  • O reranker não é um validador.
  • A verificação de evidência direta deve ser refeita pelo validador Qwen direct‑evidence.

Resumo das opções

Alternativa Fluxo Vantagem Risco
A Manter full‑text do PostgreSQL Já implementado Pode não encontrar nada em chunks longos, não é BM25
B Apenas BM25 Transparente, forte em strings/API Falsos positivos como movimento 3D
C Apenas embedding Busca semântica possível Precisão de API/versão fraca
D BM25 + embedding Equilíbrio realista Necessita ajuste de combinação de pontuações
E Perfil de consulta Qwen Reduz hard‑coding, permite resumir intenção Alucinação, custo, contaminação antes da busca
F BM25 + embedding + reranker + validador Qualidade prioritária Custo, latência, muitas etapas

Decisão provisória atual

A conclusão da nota original está mais próxima do seguinte.

Mantenha apenas um chunkText como entrada.

A primeira busca será feita com BM25.  
  Razão: é transparente e robusto para busca de strings de código/API.

A segunda busca será feita com embedding voyage-code-3.  
  Razão: a consulta é um chunk de código, portanto um modelo de recuperação de código é adequado.

A terceira ordenação será feita com rerank-2.5.  
  Razão: para elevar ao topo o JSONL que corresponde ao verdadeiro chunk entre os candidatos semelhantes trazidos pelo BM25 e pelo embedding.

A validação final será feita com o validador Qwen direct-evidence.  
  Razão: se não houver evidência direta de string/padrão que corresponda ao chunk dentro do JSONL, ele deve ser descartado.

Resumo em uma linha:

-> BM25 + geração paralela de candidatos de incorporação de código
  -> reordenamento do reranker
  -> verificação direta de evidência pelo Qwen

O que comparar realmente a seguir

  • Quantos registros o método full-text do PostgreSQL retorna no chunk de referência
  • Se o BM25 realmente coloca first_2d_game no topo
  • Quanto de falsos positivos de movimento 3D se misturam no BM25 only
  • Que documentos explicativos adicionais o embedding only traz
  • Como combinar duplicatas e pontuações no BM25 + embedding union
  • Se o reranker reordena corretamente os candidatos 2D/3D
  • Se o validador Qwen direct-evidence descarta JSONL irrelevantes como não na prática