Servicio buildQueryVec — Orquestador de Embedding con Fallback

Resumen

buildQueryVec(env, question, opts): Promise<{vec, hyde?}>

Orquesta la construcción del vector de query para retrieval. Si HyDE está activo, genera un pasaje hipotético y embebe pregunta + pasaje concatenados. Si HyDE falla, cae automáticamente al embedding normal de la pregunta. Retorna el vector y (opcionalmente) el pasaje generado para instrumentación.

Firma y ubicación

Archivo: functions/api/mcp/handlers/archivo-core.ts

Línea: 694

Tipo: async function

export async function buildQueryVec(
  env: Env,
  question: string,
  opts: { hyde?: boolean; apiKey?: string },
): Promise<{ vec: number[]; hyde?: string }>

Parámetros

Flujo de ejecución

┌─ buildQueryVec(env, question, { hyde: true, apiKey })
│
├─ if opts.hyde && opts.apiKey && env.AI
│  │
│  ├─ try:
│  │  ├─ hyp = await generateHyDE(apiKey, question)
│  │  ├─ if hyp (no vacío):
│  │  │  ├─ text = "${question}\n\n${hyp}"
│  │  │  ├─ [vec] = await embedTexts(env.AI, [text])
│  │  │  └─ return { vec, hyde: hyp }
│  │  │
│  │  └─ (HyDE vacío: continúa a fallback)
│  │
│  └─ catch:
│     └─ (fallback silencioso a paso siguiente)
│
└─ // Fallback: embedding normal
   ├─ [vec] = await embedTexts(env.AI, [question])
   └─ return { vec }

Paso 1: Tentativa de HyDE

1. Verifica condiciones para activar HyDE:

   • opts.hyde === true (explícitamente activado)
   • opts.apiKey proporcionado (necesario para Gemma)
   • env.AI disponible (binding CloudFlare Workers AI)

2. Si todas se cumplen, entra en bloque try:

   • Llama generateHyDE(opts.apiKey, question) → retorna string (puede ser vacío)
   • Si pasaje no vacío:
     • Concatena: text = "${question}\n\n${hyp}"
     • Embebe text → embedTexts(env.AI, [text]) retorna array de vectores
     • Extrae primer vector: [vec]
     • Retorna { vec, hyde: hyp } con evidencia del pasaje

3. Si generateHyDE lanza excepción (timeout, HTTP error, etc.):

   • Catch silencioso (no lanza)
   • Continúa a fallback

4. Si pasaje está vacío (p.ej. JSON parse falló):

   • Fallback silencioso (no retorna)
   • Continúa a fallback

Paso 2: Fallback a embedding normal

• Si no se tomó HyDE, o HyDE falló:
  • Embebe solo la pregunta: [vec] = await embedTexts(env.AI, [question])
  • Retorna { vec } (sin propiedad hyde)

Salida

Tipo: Promise<{ vec: number[]; hyde?: string }>

Integración en handlers

archivo.ts (línea 172)

const hydeEnabled = args.hyde === true || env.RETRIEVAL_HYDE === '1';
const { vec: queryVec } = await buildQueryVec(env, question, {
  hyde: hydeEnabled,
  apiKey: env.GOOGLE_AI_API_KEY,
});

Lógica:

• MCP arg hyde=true O env var RETRIEVAL_HYDE=1 → activar HyDE
• Extrae vector con destructuring
• Descarta pasaje (no lo usa; opcional en harness)

oraculo/ask.ts (línea 99)

const { vec: queryVec } = await buildQueryVec(env, question, {
  hyde: env.RETRIEVAL_HYDE === '1',
  apiKey: env.GOOGLE_AI_API_KEY,
});

Lógica:

• Solo respeta env var (no acepta arg MCP)
• Oráculo es backend, menos crítico en latencia que Help Widget

bib_eval_retrieval (harness, línea 530)

let qv = baseQv;
if ((v === 'hyde' || v === 'hyde+trim') && env.GOOGLE_AI_API_KEY) {
  const bv = await buildQueryVec(env, q, { hyde: true, apiKey: env.GOOGLE_AI_API_KEY });
  qv = bv.vec;
}

Lógica:

• Para variante hyde o hyde+trim: usa buildQueryVec con HyDE forzado
• Descarta pasaje (pero buildQueryVec lo genera; útil si instrumentación futura)
• Compara vector resultante vs baseQv en retrieval

Decisiones de diseño

¿Por qué concatenación pregunta + pasaje?

Alternativas:

1. Solo pasaje: vector más cercano a docs reales, pero pierde anclaje si alucina
2. Pregunta + pasaje (elegido): pregunta ancla el vector; si pasaje es falso, vector sigue cercano al tema
3. Promedio: complejidad innecesaria

Justificación: robustez a alucinaciones sin perder recall.

¿Por qué try-catch silencioso?

• No lanza en fallback: si HyDE falla (API down, timeout), el query sigue funcionando normalmente.
• Degradation path implícito: usuario no ve degradation, pero query es más lento si HyDE estaba activo.
• Alternativa rechazada: lanzar excepción bloqueaba todo /ask.

¿Cómo se instrumenta HyDE?

• Retorna hyde?: string para que el caller pueda loguear/metrificar si necesita.
• archivo.ts y oraculo/ask.ts no lo usan (por ahora).
• bib_eval_retrieval podría usarlo para logging post-hoc.

¿Por qué dos puntos de entrada (args vs env)?

• archivo.ts (MCP handler): acepta arg hyde=true para granularidad per-call.
  • Útil para testing: ask({q: "...", hyde: true}) sin cambiar env.
• oraculo/ask.ts: solo env var RETRIEVAL_HYDE=1.
  • Oráculo es backend, menos necesidad de control per-call.
  • Si necesitara flexibilidad, se añade arg fácilmente.

Casos de uso

Performance

• HyDE activo, éxito: ~1.5s (Gemma) + ~100ms (embed) = ~1.6s total
• HyDE activo, fallo: ~15s timeout + ~100ms embed = ~15.1s (degradation visible)
• Fallback (HyDE off o fallo): ~100-200ms (embed solo)

Implicación: +1-1.5s sensible en Help Widget; aceptable en Oráculo backend.

Testing

Con HyDE activo (harness)

bib_eval_retrieval({variants: ["baseline", "hyde", "hyde+trim"]})

Compara:

• baseline: buildQueryVec(..., { hyde: false })
• hyde: buildQueryVec(..., { hyde: true })

Métrica: overlap_vs_baseline (% chunks en común) → si ↑, HyDE aporta recall.

Unitario (mock)

const mock_vec = await buildQueryVec({AI, GOOGLE_AI_API_KEY}, "¿Qué es X?", {
  hyde: false,
});
expect(mock_vec.vec.length).toBe(1024); // dim BGE-M3
expect(mock_vec.hyde).toBeUndefined();

Véase también

• [[feature—biblioteca—hyde-optional-retrieval]]
• [[entity—functions—service—generate-hyde]]
• [[concept—biblioteca—embedding-vectors]]
• [[concept—biblioteca—retrieval-augmented-generation]]
• [[runbook—biblioteca—measure-retrieval-quality]]