CreaRack-SL

Servicio generateHyDE — Generador de Pasajes Hipotéticos

Vista limpiaEditar
Entidadactivecreado Thu Jun 04#biblioteca#retrieval#rag#llm#gemini#cloudflare-workers#service

Resumen

generateHyDE(apiKey: string, question: string): Promise<string>

Genera un pasaje hipotético (2-4 frases) que respondería la pregunta del usuario, como si fuera un fragmento de documentación técnica. Utilizado por HyDE (Hypothetical Document Embeddings) para mejorar el recall del retrieval.

Firma y ubicación

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

Línea: 641

Tipo: async function

export async function generateHyDE(apiKey: string, question: string): Promise<string>

Parámetros

NombreTipoPropósito
apiKeystringAPI key de Google AI Studio (p.ej. env.GOOGLE_AI_API_KEY)
questionstringPregunta del usuario (e.g., “¿Cómo configuro multi-tenancy?”)

Flujo interno

  1. Detección de idioma

    • Llama detectLanguage(question) (función auxiliar) → retorna 'es' o 'en'
    • Selecciona prompt del sistema en el idioma correspondiente

  2. Construcción del prompt

    • ES: “Escribe un breve pasaje hipotético de documentación (2-4 frases)…” → pide términología probable, detalles plausibles, sin disclaimers
    • EN: “Write a short hypothetical documentation passage (2-4 sentences)…” → análogo
    • Concatena pregunta a prompt

  3. Llamada a Gemma

    • URL: ${AI_STUDIO_BASE}/${SYNTHESIS_MODEL}:generateContent?key=${apiKey}
    • Modelo: SYNTHESIS_MODEL (típicamente gemini-1.5-flash o gemini-2.0-flash)
    • Timeout: 15 segundos (HYDE_TIMEOUT_MS)
    • Config generativa:
      • temperature: 1.0 (variación creativa)
      • topP: 0.95, topK: 64 (nucleus sampling)
      • maxOutputTokens: 220 (limita pasaje)
      • responseMimeType: "application/json" + responseSchema — fuerza JSON limpio, descarta scratchpad CoT de Gemma 4

  4. Parseo de respuesta

    • Extrae data.candidates[0].content.parts[0].text (raw JSON)
    • Sanitiza con sanitizeRawJson(raw) (elimina BOM, etc.)
    • Parsea JSON.parse(...) → { passage: string }
    • Retorna .trim() del pasaje
    • Fallback: si JSON falla (formato roto), retorna el texto crudo trimmed

  5. Manejo de errores

    • HTTP no 2xx: lanza Error("HyDE generation failed: HTTP ${status}")
    • JSON parse error: retorna texto crudo (no lanza)
    • Timeout (15s): la promesa se rechaza con AbortError

Salida

Tipo: Promise<string>

Valores típicos:

  • Pasaje de 2-4 frases (100-200 caracteres)
  • Ejemplo: “Para configurar multi-tenancy en una organización, debe crear un esquema de base de datos dedicado, configurar las claves de sesión y validar el isolamiento de datos a través de RLS…”
  • Si falla: cadena vacía "" (jamás null o undefined)

Decisiones de diseño

¿Por qué responseSchema + JSON?

  • Gemma 4 footgun: Tiende a generar scratchpad (CoT) antes de la respuesta real.
  • responseSchema: Fuerza salida JSON estructurada, eliminando el scratchpad automáticamente.
  • Ventaja: El embedding no captura ruido del razonamiento intermedio; solo captura el pasaje final.
  • Análogo: Mismo patrón usado en synthesizeAnswer (s52).

¿Por qué temperature: 1.0?

  • Creatividad moderada (no máxima, no mínima) para generar pasajes “plausibles” pero variados.
  • Si fuera 0.0, el modelo repetiría patrones; si fuera >1.0, alucinaría demasiado.

¿Por qué timeout 15s?

  • HyDE se llama en el path crítico de /ask y oraculo/ask.
  • 15s es un límite defensivo: si Gemma tarda >15s, mejor fallar al embedding normal que bloquear al usuario.

¿Qué tan malvada es una “alucinación”?

  • El pasaje hipotético puede ser incorrecto (p.ej. pasos inválidos, términología falsa).
  • Mitigación: buildQueryVec embebe pregunta + pasaje concatenados — la pregunta ancla el vector.
  • Resultado: Aunque el pasaje sea malo, el vector sigue siendo cercano a respuestas reales sobre el tema.

Casos de uso

ScenarioComportamiento
Pregunta clara + API key válida + Gemma responde rápido✅ Retorna pasaje válido (100-200 chars)
Pregunta ambigua⚠️ Retorna pasaje plausible pero posiblemente incorrecto (mitigado por anclaje de pregunta)
API key inválida / Gemma no disponible❌ Lanza Error → buildQueryVec cae a fallback (embedding normal)
Timeout >15s❌ Rechaza promesa → buildQueryVec cae a fallback
Formato JSON roto⚠️ Retorna texto crudo trimmed (mejor que lanzar)

Dependencias

NombreFuentePropósito
detectLanguage(text)archivo-core.tsDetecta idioma (ES/EN) para prompt del sistema
sanitizeRawJson(raw)HelpersLimpia BOM/caracteres especiales de JSON
AI_STUDIO_BASEConstante envBase URL de Google AI Studio
SYNTHESIS_MODELConst exportNombre del modelo Gemma a usar
Fetch APICloudFlare WorkersHace llamada HTTP a Gemma
AbortSignal.timeout()JS stdImplementa timeout de 15s

Performance

  • Latencia típica: 1-2 segundos (llamada a Gemma, no cached)
  • Tokens input: ~50-100 (prompt + pregunta)
  • Tokens output: máx 220 (limitado en maxOutputTokens)
  • Costo: ~0.001 USD por call (Gemma-2.0-flash) / ~0.0005 USD (Gemini-1.5-flash)
  • Caché: No implementado; cada query genera nuevo pasaje

Véase también

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

Referenciado desde

Inicio
Yo