idea_world_labDEV JOURNAL
domingo, 28 de junio de 2026

Retriever búsqueda alternativa descomposición de documentos

Fecha de creación: 28 de junio de 2026

Este directorio es un conjunto de documentos dividido para facilitar la visualización del Retriever búsqueda alternativa ChatGPT nota original.

Se conserva la nota original tal cual. Este README combina contexto común, método actual, candidatos de modelo y guía de selección. Los documentos secundarios contienen solo la documentación por alternativa.

Tabla comparativa integral

Estas tablas no son la selección final, sino observaciones para juzgar en una sola pantalla las alternativas de búsqueda que deben compararse el 28 de junio. El criterio es: “cuando se inserta el fragmento de código tal cual en el Retriever, ¿qué candidato JSONL aparece y puede ser aceptado como evidencia directa en la fase de verificación de Qwen?”.

Conclusión a primera vista

Alternativa Ubicación Rol esperado Nivel de disponibilidad Ventaja principal Riesgo principal Evaluación actual
A. PostgreSQL full-text mantenido Línea base actual /api/retrieve Ver hasta qué punto funciona la búsqueda implementada Alta Ya está integrado y los logs son visibles de inmediato Si un fragmento de código largo se convierte en query, pueden omitirse documentos relacionados Se mantiene como línea base, sin declararlo como método definitivo
B. Solo BM25 Candidato de búsqueda de primera fase Encontrar documentos donde la cadena de código/API aparece directamente Media Fuerte con cadenas literales como KinematicBody2D, move_and_slide, AnimatedSprite2D Cuando aparecen palabras amplias como 2D/3D pueden producir falsos positivos Buen punto de partida para el primer PoC
C. Solo embedding Expansión de recall basada en significado Encontrar documentos explicativos aunque la cadena no sea idéntica Media Captura significado de frases, tutoriales, contextos de uso similares Riesgo alto si se usa solo para juzgar versión/API Se usa como apoyo de recall, no como única solución
D. BM25 + embedding Compromiso realista intermedio Combinar evidencia literal y semántica Media Une precisión de BM25 con recall de embedding Necesita combinar puntuaciones, eliminar duplicados y definir criterios de candidatos superiores Aproxima la solución mínima viable
E. Perfil de consulta Qwen Experimento de apoyo a la búsqueda Generar un JSON que describa la intención de búsqueda a partir del fragmento de código Baja El perfil de consulta es legible para humanos El LLM puede inventar APIs/intenciones que no existen antes de la búsqueda Mejor como experimento o apoyo, no como núcleo de la primera búsqueda
F. BM25 + embedding + reranker + validador Estructura de candidato final Generar candidatos, reordenarlos y validar evidencia directa Baja Máxima calidad y observabilidad Coste, latencia y número de etapas Se mantiene como objetivo final

Comparación de resultados de simulación PoC

Alternativa Fragmento de entrada Forma en que aparecen los candidatos Probabilidad de que aparezca JSONL relacionado Probabilidad de que se mezcle JSONL no relacionado Estado esperado antes de la verificación Qwen Estado esperado después de la verificación Qwen
A Texto completo del chunk Genera una query larga con plainto_tsquery('simple', chunkText) Baja o inestable Baja, pero si no hay resultados no hay candidatos para observar Puede no haber candidatos o solo algunos retornados Puede omitirse antes de la verificación directa de evidencia
B Texto completo del chunk Clasifica documentos por puntuación BM25 por token Alta Media Pueden aparecer documentos como Input.is_action_pressed, AnimatedSprite2D, clamp Se descarta si la cadena literal no está presente
C Texto completo del chunk Similaridad de embedding código/documento Media Alta Documentos amplios sobre “movement”, “2D”, “player” pueden aparecer Se descarta si el JSONL no contiene la cadena literal
D Texto completo del chunk Fusiona candidatos BM25 y embedding Alta Media Se ven tanto candidatos literales como semánticos Solo quedan los que tienen evidencia directa
E Texto completo del chunk interpretado por Qwen Busca con el perfil de consulta generado por Qwen Media si el perfil coincide Alta APIs no incluidas en el perfil pueden mezclarse Es necesario validar si el perfil realmente corresponde al código
F Texto completo del chunk Reranker reordena candidatos BM25 + embedding Alta Baja Incluso con muchos candidatos, los superiores se ordenan Qwen deja solo “sí/no” con evidencia directa

Diferencias reveladas en la evaluación de demostración

Situación observada Prompt simple inicial Prompt mejorado con evidencia directa Significado para la arquitectura de búsqueda
Código Godot 3 + JSONL relacionado Puede devolver “sí” Debe devolver “sí” Pasa si la evidencia coincide con la cadena/API real
Código Godot 3 + JSONL no relacionado Palabras amplias de Godot pueden producir “sí” Debe devolver “no” Sin verificación directa, los candidatos son riesgosos
Código KinematicBody2D + mapeo 3D Spatial Puede considerarse relacionado bajo la noción amplia de migración Godot Debe devolver “no” Embedding solo o juicios laxos del LLM pueden generar falsos positivos
Código yield(...) + prototipo await Devuelve “sí” si hay patrón directo “sí” label_prototypes puede servir como evidencia de cambio de patrón completo
Código AnimatedSprite2D.play() + docs de animación genérica Puede parecer semánticamente relacionado “no” si el JSONL no contiene la cadena/patrón Los fragmentos de docs también requieren verificación directa de evidencia

Comparación de patrones de retorno de candidatos

Alternativa Candidatos que aparecen frecuentemente en la parte superior Candidatos que se pierden fácilmente Candidatos que se mezclan erróneamente Puntos a revisar visualmente
A Documentos con muchos tokens de la query en una sola fila Cuando los tokens relevantes están repartidos en varios documentos Casi nada si la query es demasiado estricta Por qué 0 resultados, qué token rompió el emparejamiento
B Filas que contienen directamente nombre de API, función o nodo Documentos descriptivos con la misma información pero reformulada Otros documentos de sistemas diferentes que usan la misma palabra Coincidencia entre match_terms y la cadena real del fragmento fuente
C Tutoriales o explicaciones con significado similar Mapeos exactos de API muy cortos Documentos de versiones diferentes de Godot o de 2D/3D Ver si la puntuación de coseno supera a la evidencia literal
D Candidatos exactos + candidatos semánticos Candidatos que pierden puntuación al combinar Candidatos que ambos buscadores califican débilmente Identificar si el candidato proviene de BM25 o de embedding
E Candidatos que coinciden con la intención extraída por Qwen Pistas de código reales que Qwen no incluyó en el perfil Candidatos inventados por Qwen que no existen en el código Verificar que cada campo del perfil exista realmente en el fragmento
F Candidatos que el reranker considera coincidentes con el fragmento Casos especiales de Godot que el modelo reranker desconoce Candidatos con alta puntuación de reranker pero sin evidencia directa en JSONL Puntos donde la puntuación del reranker y la decisión del validador divergen

Comparación de falsos positivos / falsos negativos

Alternativa Ejemplo de falso positivo Ejemplo de falso negativo Forma de reducir
A Rara vez, si la consulta se expande demasiado, se mezclan documentos de movimiento generales Si los documentos relacionados se dividen en varias filas, se obtienen 0 resultados Cambiar la forma de generar la consulta o añadir candidatos BM25
B Por movement, player, 2d se mezclan documentos de movimiento diferentes Si el nombre de la API solo aparece descrito en el documento, se omite Separar stopwords/token débiles, ponderar directamente los tokens de la API
C Se mezclan documentos de 3D/otras versiones con significado similar No se detectan filas de renombrado de API cortas Usar BM25 en paralelo y añadir un validador
D Se mezclan candidatos que coinciden débilmente tanto en BM25 como en embedding Si el criterio de fusión es incorrecto, un candidato queda relegado Guardar una bandera de origen de unión y un registro de evidencia directa
E Qwen genera migration_intent inexistente y contamina los candidatos Qwen omite pistas reales del código en el perfil No confiar en el perfil antes de la búsqueda, usarlo solo como ayuda
F El rerankero sobrevalora explicaciones razonables No se recuperan documentos en la fase de generación de candidatos Asegurar un número suficiente de candidatos y colocar la verificación de Qwen al final

Idoneidad por tabla

Alternativa docs_chunks api_mapping label_prototypes Comentario
A Inestable en documentos extensos Si la fila de mapeo exacto es corta, puede pasarse por alto Si la fila de patrón es corta, puede pasarse por alto Línea base para confirmar las limitaciones del método actual
B Bueno para búsqueda de API/título/token Bueno para búsqueda exacta de API origen/destino Bueno para búsqueda de patrones origen/destino Útil observar como primera opción de búsqueda en las tres tablas
C Bueno para recall de documentos descriptivos Débil en filas cortas como renombrado de API Puede ayudar si el patrón de uso es similar El apoyo de docs_chunks resulta el más natural
D Captura todos los candidatos de descripción/cadena Captura tanto mapeos exactos como candidatos semánticos Amplía los candidatos de patrones completos Estructura común a las tres tablas, la más equilibrada
E Si el perfil de consulta es bueno, permite buscar documentos descriptivos Riesgo si se introducen APIs hallucinated Puede crear intenciones de prototipo, pero con riesgo de contaminación Más un experimento de observación/apoyo que un núcleo de búsqueda
F Bueno para refinar la evidencia final descriptiva Bueno para refinar la evidencia de migración Bueno para refinar la evidencia de cambio de uso Facilita tratar las tres tablas en la misma canalización

Qué observar obligatoriamente en los registros

Alternativa Registro antes de la búsqueda Registro durante la búsqueda Registro después de la búsqueda Puntos para identificar la causa del fallo
A chunkText sin procesar, tsquery generado Número de coincidencias search_tsv @@ query, ts_rank_cd Filas devueltas, puntuación Si la consulta se volvió demasiado larga, qué tokens faltan en la fila
B chunkText sin procesar, lista de tokens Frecuencia de términos, términos coincidentes, puntuación BM25 Top‑k por tabla Si los tokens fuertes y débiles se distinguen
C chunkText sin procesar, modelo de embedding Distancia vectorial/puntuación de coseno Top‑k semántico Si el candidato coincide solo por significado sin cadena textual
D Top‑k BM25, top‑k embedding Unión, fusión de duplicados, puntuación combinada Lista de candidatos con banderas de origen Por qué los candidatos obtenidos solo por una vía sobrevivieron
E Chunk crudo enviado a Qwen Perfil de consulta JSON de Qwen Resultados de búsqueda basados en el perfil Si el campo del perfil realmente existe en la fuente
F Todos los candidatos BM25/embedding Puntuación y orden del rerank 예/아니오 de Qwen, razón de rechazo Por qué los candidatos aprobados por el rerank fallaron en la verificación de evidencia directa

Complejidad de implementación y coste operativo

Alternativa Volumen de implementación Cambios en la BD Coste de modelo externo Latencia Dificultad de depuración Facilidad de corrección al fallar
A Baja Casi nula Ninguno Baja Baja Baja. Sin embargo, el límite de rendimiento puede ser estructural
B Media Necesario elegir motor/índice BM25 Ninguno o bajo Baja Baja Alta. Se pueden ajustar tokens y ponderaciones
C Media Requiere columna/índice de embedding Sí Media Media Media. Necesita ajustar modelo, dimensiones o umbral
D Media‑alta Necesita tanto BM25 como vector Sí Media Media Alta. Permite separar qué ruta de búsqueda falló
E Media Guardar el perfil es opcional Sí Alta Alta Baja. Reproducir por qué el perfil LLM falló puede ser difícil
F Alta Necesita logs de BM25, vector y rerank Sí Alta Alta Alta. Con logs por etapa se identifican los puntos a corregir

Comparación de dónde colocar Qwen

Ubicación Ventaja Riesgo Uso más adecuado actualmente
Generación de consulta antes de la búsqueda Permite crear la intención de búsqueda sin codificación rígida Puede generar pistas falsas y contaminar la búsqueda Solo para experimentación
Verificación directa después de obtener candidatos Filtra resultados que no coinciden con el código real Genera coste de llamadas Prioridad máxima
Generación de respuesta final Puede producir explicaciones o respuestas de migración Si la evidencia es incorrecta, la respuesta también lo será Después de candidatos JSONL verificados
Integración de juicio total Produce una conclusión legible para humanos Puede ocultar fallos intermedios Tras acumular logs suficientes, revisar

Prioridad de selección

Prioridad Opción Razón Pregunta a validar en esta fase
1 Medir respecto a A como línea base Necesitamos saber dónde falla la implementación actual ¿Cuántas filas devuelve realmente el método actual?
2 Añadir B como PoC separado La búsqueda de cadenas de código/API es la más explicable ¿KinematicBody2D, yield, move_and_slide encuentran la fila correcta?
3 Comparar C como recall complementario Amplía los candidatos descriptivos de docs_chunks ¿Con qué frecuencia los candidatos semánticos son descartados en la verificación directa?
4 Generar candidatos en paralelo con D Estructura mínima realista ¿Mejora la calidad al combinar candidatos BM25 y embedding?
5 Añadir rerank/validador con F Verificación de calidad final ¿El rerank de Qwen descarta de forma segura JSONL irrelevantes?
En espera E El LLM antes de la búsqueda tiene alto riesgo de contaminación ¿El perfil se genera únicamente a partir de cadenas de código reales?

Lista de verificación de PoC

Elemento de verificación Pantalla/registro a observar Criterio de éxito
Insertar el mismo chunkText en varias alternativas Área de entrada de chunk del depurador web La entrada no varía entre alternativas
Botón de búsqueda por tabla Botones docs_chunks, api_mapping, label_prototypes Se observa diferencia de candidatos por tabla con el mismo chunk
Verificación de candidatos sin procesar Payload JSONL devuelto Aparece el campo que coincide con la cadena real dentro del chunk fuente
Verificación de Qwen Área de depuración prompt + chunk + jsonl Los candidatos relevantes aparecen como “sí”, los no relevantes como “no”
Verificación de razón de rechazo Registro de resultados del validador Los candidatos que solo coinciden con palabras amplias como Godot, migration, 2D son descartados
Recopilación de falsos positivos Lista de candidatos descartados Puede usarse más adelante para mejorar reglas de consulta/token/validador
Guardado de comparación por alternativa Diario de observaciones o JSON de resultados Se conserva la diferencia A‑F para la misma entrada

Documentos de alternativas

Premisas actuales

Las premisas actuales son las siguientes.

1. Dentro del zip hay el markdown original, el esquema, el depurador y la documentación de diseño.  
2. En el local ya está la conversión markdown → JSONL → DB.  
3. Lo que se puede ver ahora es el markdown antes de la conversión y el esquema/flujo de búsqueda de la DB.  
4. El PoC debe dividir el markdown del zip como fragmentos JSONL y simular los objetivos de búsqueda que podrían haber ingresado en la DB local.  
5. Lo necesario no es la estructura del código, sino rastrear cómo cada método de búsqueda genera puntuaciones y por qué tiene éxito o falla cuando se insertan los fragmentos.

Criterios JSONL/DB

Los entregables basados en el documento son los siguientes.

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

La base de datos no está estructurada para insertar una línea completa de JSONL en payload jsonb, sino que se entiende que los campos de JSONL se despliegan como columnas de la tabla.

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 referencia

El chunk que se utilizó como referencia en la comparación de alternativas es el siguiente código de 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 fuerte!

animatedsprite2d
is_action_pressed
move_left
move_right
normalized
clamp
screen_size
vector2
zero

Token débil:

func
var
if
else
velocity
position
delta
x
0
1

La entrada de búsqueda se mantiene tal cual chunkText. No se considera esencial, como parte del diseño básico, extraer la señal de la API de Godot antes de la búsqueda y convertirla en una consulta separada. Si es necesario, solo se revisará más adelante como un puntaje auxiliar.

Método actual /api/retrieve

El /api/retrieve del proyecto actual no es BM25.

El flujo es similar al siguiente.

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

PostgreSQL ts_rank_cd es una función de ranking de texto completo. A diferencia del propio BM25 de los motores de búsqueda, que combina frecuencia de término, frecuencia inversa de documento y normalización de longitud de campo, aquí debe considerarse de forma distinta.

plainto_tsquery(raw_chunk) extrae tokens del fragmento de entrada y crea una consulta. El fragmento de referencia puede convertirse en una consulta larga como la siguiente.

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 forma puede requerir demasiados tokens dentro de una sola fila.

Si el chunk de la documentación oficial está dividido como sigue, surge un problema.

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

chunk B:
  Descripción de AnimatedSprite2D
  position.clamp
  screen_size

Ambos están relacionados, pero puede que no todos los tokens estén presentes simultáneamente en una sola fila.

En la nota original se considera que una búsqueda de tipo strict raw AND puede fallar de la siguiente manera.

strict raw AND hits: 0

El método actual puede considerarse una línea base para la PoC, pero es débil para mantenerlo como estrategia de búsqueda final. En la siguiente etapa, se debe comparar el método actual con BM25 por separado.

Candidatos de modelo

voyage-code-3

Se mencionó como el candidato de embedding que mejor se adapta al proyecto actual.

Razón:

La consulta no es una pregunta en lenguaje natural, sino un fragmento de código GDScript.  
En el JSONL de búsqueda también están mezclados bloques de código, nombres de API y descripciones de documentación.

Ventajas:

  • Es fuerte en la recuperación de código.
  • Es ventajoso para procesar fragmentos largos.
  • Es adecuado para buscar de código a documentación.

Desventajas:

  • Depende de API externas.
  • Tiene costos.
  • No es un modelo especializado en Godot.

Recomendación basada en notas:

voyage-code-3 1024 float

OpenAI text-embedding-3-large

Candidato de embedding de uso general de alta calidad.

Ventajas:

  • Es fuerte en recuperación semántica de uso general.
  • Es estable en la búsqueda de descripciones de documentos.
  • Es fácil de integrar con el ecosistema de OpenAI.

Desventajas:

  • No está dedicado exclusivamente a la recuperación de código.
  • El tamaño de dimensión base es grande, lo que puede aumentar los costos de almacenamiento/índice.
  • Para búsquedas de fragmentos GDScript → JSONL puede ser menos directo que voyage-code-3.

Recomendación basada en notas:

Segunda prioridad

Gemini Embedding

Candidato de recuperación semántica universal/multilingüe.

Ventajas:

  • Es bueno para la recuperación basada en la descripción de documentos.
  • Ofrece opciones de reducción de dimensionalidad.
  • Puede tener fortalezas en la búsqueda de documentos multilingües.

Desventajas:

  • No es una opción dedicada exclusivamente a la recuperación de código.
  • Se acerca más a la similitud semántica que a la precisión del código de la API.
  • Existe riesgo al usarlo de forma aislada para decisiones exactas de migración a Godot.

Jina embeddings v4

Candidato con fortalezas en la recuperación de documentos complejos, multimodales y visualmente ricos.

Ventajas:

  • Amplio alcance en la búsqueda de documentos.
  • Fuerte en documentos multimodales/combinados.
  • También se pueden considerar adaptadores de código.

Desventajas:

  • El proyecto actual se centra en markdown/código.
  • La recuperación de imágenes/tablas no es el objetivo principal.
  • En esta etapa podría ser una opción excesiva.

Recomendación basada en notas:

Por ahora es de baja prioridad

rerank-2.5

Se mencionó como candidato a reranker.

Rol:

Se comparan nuevamente los candidatos obtenidos por BM25 y embedding con el fragmento bruto.  
Se reordenan los candidatos según la puntuación de relevancia.

Este proyecto espera los siguientes efectos:

  • Reducir los falsos positivos en movimiento 2D y movimiento 3D.
  • Reflejar mejor el contexto directo de elementos como AnimatedSprite2D, Vector2, screen_size, position.clamp.
  • Organizar los candidatos obtenidos por BM25 y embedding como candidatos finales.

Advertencia:

  • El reranker no es un validador.
  • La verificación de evidencia directa debe ser realizada nuevamente por el validador Qwen direct‑evidence.

Resumen de opciones

Alternativa Flujo Ventajas Riesgos
A Mantener full‑text de PostgreSQL Ya implementado Puede no encontrar resultados en chunks largos, no es BM25
B Solo BM25 Transparente, fuerte con cadenas/API Falsos positivos como movimiento 3D
C Solo embedding Búsqueda semántica posible Precisión de API/versión limitada
D BM25 + embedding Equilibrio realista Necesita ajuste de combinación de puntuaciones
E Perfil de consulta Qwen Reduce codificación rígida, permite resumir la intención Alucinaciones, costo, contaminación antes de la búsqueda
F BM25 + embedding + reranker + validador Calidad prioritaria Costo, latencia, muchos pasos

Juicio provisional actual

La conclusión de la nota original se acerca a lo siguiente.

Entrada mantiene solo un chunkText.

1ª búsqueda se realiza con BM25.  
  Razón: es transparente y robusta para la búsqueda de cadenas de código/API.

2ª búsqueda se realiza con el embedding voyage-code-3.  
  Razón: la consulta es un fragmento de código, por lo que un modelo de recuperación de código es el adecuado.

3ª ordenación se realiza con rerank-2.5.  
  Razón: para elevar al principio los JSONL que realmente coinciden con el fragmento entre los candidatos similares obtenidos por BM25 y el embedding.

La validación final se hace con el validador Qwen direct‑evidence.  
  Razón: si dentro del JSONL no hay una cadena/patrón que coincida directamente con el fragmento, debe descartarse.

Resumen de una línea:

raw chunk tal cual entrada
  -> Generación paralela de candidatos con BM25 + incrustación de código
  -> Reordenamiento con reranker
  -> Verificación directa de evidencia con Qwen

Lo que se comparará realmente a continuación

  • Cuántos registros devuelve el método de texto completo de PostgreSQL actual en el chunk de referencia
  • Si BM25 realmente coloca first_2d_game en los primeros puestos
  • Cuánto se mezcla el falso positivo de movimiento 3D en BM25 only
  • Qué documentos descriptivos adicionales trae embedding only
  • Cómo combinar duplicados y puntuaciones en la unión BM25 + embedding
  • Si el reranker reordena correctamente los candidatos 2D/3D
  • Si el validador de evidencia directa Qwen descarta realmente los JSONL no relacionados con no