HyDE opcional en el retrieval de la biblioteca

Descripción

HyDE (Hypothetical Document Embeddings) es una técnica de generación para mejorar el recall del retrieval semántico. En vez de embeber la pregunta cruda del usuario (corta, fraseo variado), se genera un pasaje hipotético que la respondería (parecido a la prosa de la documentación) y se embebe ese pasaje junto con la pregunta original, anclando el vector resultante.

Beneficio: el vector cae más cerca de chunks relevantes en el espacio BGE-M3 → mayor recall.
Costo: +1 llamada a Gemma (~1-2s latencia) por query.
Estado: OFF por defecto. El harness bib_eval_retrieval permite A/B testing con variantes hyde y hyde+trim.

Implementación

Funciones principales

generateHyDE(apiKey, question): Promise<string> (archivo-core.ts)

• Detecta idioma (ES/EN) de la pregunta
• Envía prompt a Gemma (responseSchema fuerza JSON limpio, descarta scratchpad CoT de Gemma 4)
• Genera pasaje 2-4 frases, concreto, con terminología plausible
• Timeout: 15s; fallback a pregunta cruda si falla

buildQueryVec(env, question, opts): Promise<{ vec, hyde? }> (archivo-core.ts)

• Orquesta el flujo completo de embedding
• Si hyde: true, genera hipótesis y embebe pregunta\n\n${pasaje}
• Si HyDE falla, fallback a embedding normal de pregunta
• Devuelve vector + pasaje generado (útil para harness)

Puntos de integración

1. MCP Handler bib_ask (archivo.ts)

   • Parámetro hyde: boolean en args
   • Env var RETRIEVAL_HYDE=1 (default OFF)
   • Usa buildQueryVec en lugar de embedTexts directo

2. API Endpoint Oraculo.ask (api/oraculo/ask.ts)

   • Env var RETRIEVAL_HYDE=1 para activar
   • Mismo flujo: buildQueryVec + searchChunks

3. Harness bib_eval_retrieval (archivo.ts)

   • Nuevas variantes: hyde, hyde+trim
   • Compara overlap vs baseline (proxy de cambio de recall)
   • Mide tokens para calcular latencia real

Configuración

Env var: RETRIEVAL_HYDE

• undefined o "0" → OFF (default)
• "1" → ON (activa HyDE en retrieval)

Parámetro MCP (bib_ask):

• hyde: true → sobrescribe env var, activa para esa query

Parámetro harness (bib_eval_retrieval):

• variants: ['hyde', 'hyde+trim'] → incluye en el A/B test

Validación pendiente

Según el commit body: “Verificado: tsc —noEmit verde. Pendiente medir recall vs latencia con el harness tras deploy.”

El próximo paso es:

1. Deployr a staging
2. Correr bib_eval_retrieval con variants=['baseline', 'trim', 'hyde', 'hyde+trim'] sobre 15+ queries reales
3. Comparar overlap (¿Hyde trae chunks nuevos relevantes?) vs tokens (¿latencia aceptable?)
4. Si recall sube >5% y latencia <2.5s, considerar activar por defecto

Relación con ArcRift

Este commit es cherry-pick #1 (PR2) de un proyecto más amplio ArcRift. Contiene solo la pieza de generación + embedding HyDE. Otros cherry-picks posteriores pueden incluir:

• Sintaxis extendida de bib_ask (p.ej. ranking reorderador)
• Integración con modelos locales (Ollama)
• Persistencia de variantes A/B en telemetría

Véase también

• [[entity—functions—service—generate-hyde]]
• [[entity—functions—service—build-query-vec]]
• [[concept—biblioteca—arquitectura-supercontexto]]