Alternativa D: BM25 + embedding paralelos

Fluxo

raw chunkText
  -> BM25 top 50
  -> embedding top 50
  -> união de candidatos
  -> misturar pontuações
  -> retornar JSONL
  -> verificação de evidência direta Qwen

Divisão de papéis

O que o BM25 captura:

Input.is_action_pressed
AnimatedSprite2D
position.clamp
screen_size
Vector2.ZERO

O que o embedding captura:

player movement
2D movement tutorial
moving inside screen
animation based on movement

O que o validador de evidência direta Qwen faz:

Verifique se há evidência de string/padrão que corresponde diretamente ao chunk atual dentro do JSONL recuperado  
Descartar JSONL não relacionado

Vantagens

Compensa as fraquezas da busca por string e da busca semântica.
A qualidade do primeiro conjunto de candidatos melhora mesmo sem o Qwen.
Mantém a condição de raw chunk.
Pode ser iniciado sem o extrator de sinais da API Godot codificado manualmente.

Desvantagens

É necessário ajustar a combinação de pontuações.
A escala da pontuação BM25 e da pontuação vetorial são diferentes.
O ranking pode ficar instável se não houver reranker.
Não impede completamente falsos positivos.

Resultados esperados no chunk de referência

Candidatos superiores:

first_2d_game / coding_the_player
same page / clamp section

Candidatos que devem ser reduzidos ou descartados na validação:

first_3d_game / player_movement_code
unrelated api_mapping
unrelated label_prototypes

Simulação de PoC

Pesquise o chunk de referência simultaneamente em dois caminhos.

raw chunkText
  -> BM25 top 50
  -> embedding top 50
  -> união de candidatos
  -> mesclagem de duplicatas
  -> verificação Qwen direct-evidence

BM25 top candidato exemplo:

Candidato	Por que o BM25 capturou
`first_2d_game / coding_the_player`	Correspondência direta de `Input.is_action_pressed`, `move_left`, `move_right`, `AnimatedSprite2D.play/stop`
`first_2d_game / clamp section`	Correspondência direta de `position.clamp`, `Vector2.ZERO`, `screen_size`
`first_3d_game / player_movement_code`	Sobreposição de tratamento de entrada e token de movimento normalizado

embedding top candidato exemplo:

Candidato	Por que o embedding capturou
`first_2d_game / coding_the_player`	Significado de movimento e animação do jogador 2D é próximo
`first_2d_game / clamp explanation`	Significado de limitar o jogador dentro da tela é próximo
`first_3d_game / player_movement_code`	Significado de movimento do jogador é próximo
`animation docs`	Significado de reproduzir/parar animação no estado de movimento é próximo

Após a união dos candidatos, aparece algo como a seguir.

candidate A:
  source: BM25 + embedding
  evidence: Input.is_action_pressed, AnimatedSprite2D.play/stop
  expected: accept

candidate B:
  source: BM25 + embedding
  evidence: position.clamp, Vector2.ZERO, screen_size
  expected: accept

candidate C:
  source: BM25 + embedding
  evidence: Input.is_action_pressed, move_left, move_right, normalized
  missing: AnimatedSprite2D, Vector2, screen_size
  expected: lower or reject

candidate D:
  source: embedding only
  evidence: semantic movement/animation similarity
  direct string match: weak
  expected: validator decision needed

Ao enviar para o validador de evidência direta Qwen, avalia-se com base nos seguintes critérios.

A string/chamada de API real dentro de **SOURCE_CODE** e os campos **source_api**, **source_pattern**, **match_terms**, **required_when_seen_in_code**, **before_code** do JSONL, ou o **content/code_blocks/api_symbols** de **docs_chunks** correspondem diretamente?

Logs a serem verificados no PoC

Esta alternativa é importante no processo de união, portanto deve mostrar o seguinte.

1. Lista de candidatos BM25  
2. Lista de candidatos de embedding  
3. Resultado da remoção de duplicatas após a união  
4. Se cada candidato veio do BM25 ou do embedding  
5. Lista de evidências de strings diretas  
6. Exemplo/Não do validador Qwen

Conclusão visível:

BM25 publica diretamente a base da API,  
e o embedding complementa as opções explicativas.  
No entanto, apenas o union deixa falsos positivos, portanto um validador é necessário.

Julgamento

Etapa intermediária realista  
Linha mínima recomendada para prática

Se for incômodo conectar diretamente ao reranker, você pode começar comparando esta alternativa.