Alternativa C: incorporação apenas

Fluxo

raw chunkText
  -> vetor de embedding
  -> docs_chunks/api_mapping/label_prototypes embedding e busca por cosseno
  -> retornar top JSONL

Por que a incorporação é necessária

BM25 é forte em correspondência de strings exatas, mas pode ficar fraco quando a descrição e a representação do código são diferentes.

Por exemplo, o chunk contém o seguinte código.

position = position.clamp(Vector2.ZERO, screen_size)

O documento pode estar descrito da seguinte forma.

prevent the player from leaving the screen
clamping a value means restricting it to a given range

Neste caso, o embedding pode capturar conexões semânticas.

Sucesso esperado no chunk de referência

O embedding tem a possibilidade de encontrar o próximo tópico.

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

Falhas esperadas no chunk de referência

O embedding pode atribuir pontuações altas também a candidatos com significado semelhante.

Falso positivo esperado:

3D player movement
scripting player input
vector math
animation player docs

Ou seja, se o significado de “player movement” for semelhante, a diferença entre 2D/3D pode ficar turva.

Simulação PoC

Converte o chunk de referência em um vetor de embedding.

Significado da entrada:

2D player movement
keyboard input
velocity normalization
animation while moving
keep player inside screen

candidatos com maior probabilidade de serem encontrados pelo embedding:

| first_3d_game / player_movement_code | movimento do jogador, entrada, direção normalizada têm significado próximo | false positive | | Vector math / movement tutorial | velocidade, vetor, normalizado têm significado próximo | maybe | | Animation player docs | reproduzir/parar animação têm significado próximo | maybe |

Problemas notáveis no embedding only:

Em vez de verificar se a string corresponde exatamente, verifica-se se o significado está próximo.  
Portanto, critérios que precisam ser divididos com precisão, como 2D/3D, Godot3/Godot4, ou se há migração, podem ficar nebulosos.

Por exemplo, os documentos de chunk de referência e de movimento 3D compartilham o mesmo significado.

keyboard input
movement direction
normalized velocity
player movement

Mas o chunk de referência tem a seguinte pista direta.

AnimatedSprite2D
Vector2.ZERO
position.clamp
screen_size

embedding only pode não ser capaz de explicar esta pista direta tão transparentemente quanto o BM25.

Logs a serem verificados no PoC

No PoC de embedding, deve mostrar o seguinte.

1. consulta chunkText  
2. Resumo do título/conteúdo do documento candidato  
3. similaridade cosseno  
4. Lista de strings que correspondem diretamente  
5. Exibir candidatos sem correspondência direta, mas com significado próximo

Conclusão visível:

embedding complementa documentos descritivos que o BM25 deixou de fora.  
No entanto, é fraco na avaliação de evidências diretas, portanto não deve ser usado isoladamente.

Vantagens

• Mesmo que a expressão seja diferente, encontra.
• É forte em conteúdo explicativo de documentos.
• É fácil inserir o chunk bruto como está.
• Pode servir como fallback quando o BM25 retorna 0 resultados.

Desvantagens

• O julgamento da API exata é fraco.
• Pode misturar diferenças entre as versões Godot 3/Godot 4.
• Pode misturar contextos 2D/3D.
• É difícil explicar por que esse resultado foi obtido.
• No api_mapping há um grande risco de falsos positivos.

Julgamento

Uso exclusivo proibido  
Usado para complementar candidatos BM25