Alternativa D: BM25 + incrustación paralela

Flujo

- BM25 top 50  
- embedding top 50  
- unión de candidatos  
- mezclar puntuaciones  
- devolver JSONL  
- verificar Qwen direct‑evidence

Distribución de roles

Lo que captura BM25:

Input.is_action_pressed
AnimatedSprite2D
position.clamp
screen_size
Vector2.ZERO

Lo que captura el embedding:

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

Qwen direct-evidence validator hace lo siguiente:

Verificar si dentro del JSONL recuperado hay evidencia de cadena/patrón que coincida directamente con el fragmento actual  
Descartar JSONL no relacionado

Ventajas

Compensa las debilidades de la búsqueda por cadena y la búsqueda semántica entre sí.
La calidad del primer candidato mejora incluso sin Qwen.
Se mantiene la condición de fragmento sin procesar.
Se puede comenzar sin el extractor de señales de la API de Godot codificado de forma rígida.

Desventajas

Es necesario ajustar la combinación de puntuaciones.
La escala de la puntuación BM25 y la puntuación vectorial son diferentes.
Si no hay reranker, el ranking puede volverse inestable.
No se puede evitar completamente los falsos positivos.

Resultados esperados en el fragmento de referencia

Candidatos superiores:

first_2d_game / coding_the_player
same page / clamp section

Candidatos que deben reducirse o descartarse en la verificación:

first_3d_game / player_movement_code
unrelated api_mapping
unrelated label_prototypes

Simulación PoC

Buscar el chunk de referencia en dos rutas simultáneamente.

raw chunkText
  -> BM25 top 50
  -> embedding top 50
  -> unión de candidatos
  -> fusión de duplicados
  -> verificación de Qwen direct-evidence

BM25 top candidato ejemplo:

Candidato	Razón por la que BM25 lo capturó
`first_2d_game / coding_the_player`	Coincidencia directa de `Input.is_action_pressed`, `move_left`, `move_right`, `AnimatedSprite2D.play/stop`
`first_2d_game / clamp section`	Coincidencia directa de `position.clamp`, `Vector2.ZERO`, `screen_size`
`first_3d_game / player_movement_code`	Coincidencia de tokens de entrada y movimiento normalizado

embedding top candidato ejemplo:

Candidato	Razón por la que embedding lo capturó
`first_2d_game / coding_the_player`	El significado de movimiento del jugador 2D y animación es cercano
`first_2d_game / clamp explanation`	El significado de limitar al jugador dentro de la pantalla es cercano
`first_3d_game / player_movement_code`	El significado de movimiento del jugador es cercano
`animation docs`	El significado de reproducir/parar animación en estado de movimiento es cercano

Después de la unión de candidatos se ve como sigue.

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

Al pasar a Qwen direct-evidence validator, se juzga según los siguientes criterios.

¿Las cadenas reales / llamadas a API dentro de SOURCE_CODE y los campos source_api, source_pattern, match_terms, required_when_seen_in_code, before_code de JSONL, o el contenido/code_blocks/api_symbols de docs_chunks coinciden directamente?

Registro a verificar en PoC

Esta alternativa es importante en el proceso de unión, por lo que debe mostrar lo siguiente.

1. Lista de candidatos BM25  
2. Lista de candidatos de incrustación  
3. Resultado después de la unión y eliminación de duplicados  
4. Indicar si cada candidato proviene de BM25 o de incrustación  
5. Lista de evidencias de cadena directa  
6. Ejemplo/No del validador Qwen

Conclusión visible:

BM25 sube la evidencia de la API directamente,  
el embedding complementa las candidatas descriptivas.  
Sin embargo, solo con union quedan falsos positivos, por lo que se necesita un validador.

Juicio

Etapa intermedia realista  
Línea mínima recomendada para la práctica

Si resulta incómodo conectar directamente hasta el reranker, se puede comparar primero con esta alternativa.