Alternativa B: apenas BM25

Fluxo

raw chunkText
  -> tokenizer
  -> BM25
  -> top JSONL retorno

BM25 que vê

BM25 cria a pontuação aproximadamente a partir dos seguintes elementos.

TF: Quantas vezes a palavra aparece neste documento  
IDF: Quão rara é essa palavra em todo o corpus  
Length normalization: Correção para que documentos longos não tenham vantagem automática

Então as próximas palavras do chunk de referência se tornam importantes.

animatedsprite2d
is_action_pressed
move_left
move_right
normalized
clamp
screen_size
vector2
zero

Por que funciona no chunk de referência

Na simulação da nota original, o documento a seguir aparece acima.

outputs/godot_docs_full/pages/getting_started__first_2d_game__03.coding_the_player__161d377b.md

O token correspondente direto é o seguinte.

animatedsprite2d
is_action_pressed
move_left
move_right
normalized
play
stop
input
speed
length
velocity
vector2
zero

Especialmente, o próximo token é raro no corpus, portanto contribui fortemente para a pontuação.

animatedsprite2d
move_left
move_right
is_action_pressed
screen_size
clamp

Candidato a Falha

No BM25 only, documentos de movimento 3D também podem aparecer.

Isso se deve ao seguinte token comum.

Input.is_action_pressed
move_right
move_left
normalized
speed

Mas o chunk de referência é 2D e a próxima pista é importante.

AnimatedSprite2D
Vector2
position.clamp
screen_size

BM25 é baseado em pontuação de palavras, portanto não compreende perfeitamente o contexto 2D/3D.

Simulação de PoC

Insira o chunk de referência como consulta BM25.

Entrada:

func _process(delta):
  Input.is_action_pressed(...)
  velocity.normalized() * speed
  $AnimatedSprite2D.play()
  position.clamp(Vector2.ZERO, screen_size)

Tokens que recebem pontuação alta no BM25:

animatedsprite2d
is_action_pressed
move_left
move_right
normalized
clamp
screen_size
vector2
zero

Previsão de candidatos:

Classificação	Candidato	Por que aparece	Decisão
1	`first_2d_game / coding_the_player`	`Input.is_action_pressed`, `move_left`, `move_right`, `velocity.normalized`, `AnimatedSprite2D.play/stop` correspondem diretamente	accept
2	`first_2d_game / clamp/screen section`	`position.clamp`, `Vector2.ZERO`, `screen_size`, `AnimatedSprite2D` estão corretos	accept
3	`first_3d_game / player_movement_code`	`Input.is_action_pressed`, `move_left`, `move_right`, `normalized`, `speed` se sobrepõem	false positive

Razão pela qual o candidato em primeiro lugar aparece:

animatedsprite2d:
  Como é um token raro em todo o documento, o IDF é grande

move_left / move_right:
  Aparece diretamente no código de entrada do tutorial

is_action_pressed:
  Corresponde diretamente ao código de processamento de entrada

velocity.normalized:
  Corresponde diretamente ao fluxo de normalização do vetor de movimento

Razão pela qual o candidato de 3º lugar aparece junto:

O documento de movimento 3D também descreve o processamento de entrada e o fluxo de movimento normalizado.  
Portanto, sob a perspectiva do BM25, a sobreposição de tokens da consulta é bastante grande.  
No entanto, isso não corresponde ao núcleo do chunk de referência, que inclui AnimatedSprite2D, Vector2, screen_size e position.clamp.

Logs a serem verificados no PoC

É importante mostrar a contribuição de tokens para cada candidato no PoC do BM25.

Exemplo:

candidate: first_2d_game / coding_the_player
matched_terms:
  animatedsprite2d   high
  is_action_pressed  high
  move_left          high
  move_right         high
  normalized         medium
  play               medium
  stop               medium

candidate: first_3d_game / player_movement_code
matched_terms:
  is_action_pressed  high
  move_left          high
  move_right         high
  normalized         medium
missing_terms:
  animatedsprite2d
  screen_size
  position.clamp

Conclusão visível:

BM25 recupera bem os documentos relevantes.  
Mas também traz códigos de entrada/movimento semelhantes.  
Portanto, na etapa seguinte ao BM25, é necessário um reranker ou validador.

Vantagens

O princípio é transparente.
A depuração é fácil.
Não há custo de modelo.
Pode usar o chunk bruto como está.
É forte na busca exata de strings em código/API.

Desvantagens

É fraco com sinônimos e descrições.
Pode perder se o nome da API não aparecer explicitamente.
Código semelhante, como 3D movement, pode gerar falsos positivos.

Avaliação

Busca de candidatos de primeira fase que deve ser revisada obrigatoriamente  
Mas o uso isolado é insuficiente