Volver a la wiki

Tool MCP bib_eval_retrieval: harness A/B del retrieval

Resumen

Tool MCP reproducible para validar y calibrar el retrieval sin redeploy. Compara variantes (baseline = chunks enteros vs trim = recortado a frases relevantes) sobre un set de preguntas reales o custom, produciendo métricas cuantificables: tokens en contexto, reducción %, scores y solapamiento de chunks.

Rol: Harness A/B del ArcRift cherry-pick #1 (sentence-trimming).

Invocación

bib_eval_retrieval(
  questions?: string[],             // preguntas a evaluar (opt)
  variants?: ('baseline' | 'trim')[],  // variantes (default ['baseline', 'trim'])
  top_k?: number,                   // chunks (default 5, max 20)
  trim_threshold?: number,          // coseno mínimo (default 0.38)
  trim_window?: number,             // contexto ±N frases (default 1)
  synthesize?: boolean,             // sintetizar respuestas (default false, lento/caro)
  source_type?: string,             // filtro: tipo de fuente
  app?: string                      // filtro: app Django
)

Parámetros detallados

questions (opcional)

Array de preguntas a evaluar.

Comportamiento:

Recomendación: usar preguntas golden (casos típicos, edge cases) para reproducibilidad. Ej:

{
  "questions": [
    "¿Qué es multi-tenancy?",
    "¿Cómo se configura RLS?",
    "¿Cuál es el flow de autenticación?"
  ]
}

variants (opcional, default ['baseline', 'trim'])

Variantes del retrieval a comparar.

Ejemplo: variants: ['baseline', 'trim'] → correr ambas, comparar.

top_k (opcional, default 5)

Número de chunks a recuperar por pregunta. Max 20 (para evitar overload).

trim_threshold (opcional, default 0.38)

Coseno mínimo (0.0–1.0) para conservar una frase en la variante trim.

Uso para calibración:

bib_eval_retrieval(
  questions: ["¿Multi-tenancy?"],
  trim_threshold: 0.42
)
// Ejecutar múltiples runs con thresholds distintos
// para hallar el óptimo (máx reducción, mín overlap loss)

trim_window (opcional, default 1)

Frases de contexto ±N alrededor de las frases relevantes.

synthesize (opcional, default false)

Si true: sintetizar la respuesta con Gemma/Oraculo por variante. Mucho más lento y caro (llama al LLM).

source_type, app (opcionales)

Filtros de búsqueda:

Ejemplo: evaluar solo chunks de la app core:

bib_eval_retrieval(
  questions: [...],
  app: "core"
)

Salida

JSON con estructura:

{
  "summary": {
    "questions": 3,
    "top_k": 5,
    "trim_threshold": 0.38,
    "trim_window": 1,
    "avg_tokens_baseline": 156,
    "avg_tokens_trim": 89,
    "token_reduction_pct": 43,
    "avg_overlap_vs_baseline": 0.92
  },
  "results": [
    {
      "question": "¿Qué es multi-tenancy? (primer 100 chars)",
      "variants": {
        "baseline": {
          "chunk_ids": [123, 456, 789],
          "top_score": 0.845,
          "tokens": 180,
          "tokens_before": 200
        },
        "trim": {
          "chunk_ids": [123, 456],
          "top_score": 0.845,
          "tokens": 95,
          "tokens_before": 200,
          "overlap_vs_baseline": 0.67,
          "answer": "Multi-tenancy es ... [truncado a 600 chars si synthesize=true]"
        }
      }
    },
    // ... más resultados
  ]
}

summary

Agregación sobre todas las preguntas evaluadas:

results

Array de resultados por pregunta:

Workflow de calibración

1. Línea base

bib_eval_retrieval(
  top_k: 5,
  trim_threshold: 0.38,  // default
  trim_window: 1
)
// Salida: avg_tokens_baseline=156, avg_tokens_trim=89, token_reduction_pct=43, overlap=0.92
// Interpretación: 43% menos tokens, perdemos <10% de chunks

2. Ajustar threshold

bib_eval_retrieval(
  top_k: 5,
  trim_threshold: 0.40,  // más estricto
  trim_window: 1
)
// Salida: avg_tokens_trim=75, token_reduction_pct=52, overlap=0.88
// Interpretación: más reducción, pero 12% chunks perdidos
bib_eval_retrieval(
  top_k: 5,
  trim_threshold: 0.35,  // más permisivo
  trim_window: 1
)
// Salida: avg_tokens_trim=110, token_reduction_pct=30, overlap=0.95
// Interpretación: menos reducción, pero casi sin perder chunks

Decisión: elegir threshold que balancee reducción y overlap. Ej, 0.40 con overlap 0.88 es aceptable si el beneficio de tokens es importante.

3. Validar con synthesis

Una vez calibrado threshold, opcionalmente sintetizar para validar que las respuestas siguen siendo correctas:

bib_eval_retrieval(
  questions: ["¿Multi-tenancy?", "¿RLS?"],
  trim_threshold: 0.40,
  synthesize: true
)
// Verifica que `answer` en `variants.trim` sigue siendo precisa

4. Desplegar

Una vez validado, actualizar en el entorno:

RETRIEVAL_TRIM=1
RETRIEVAL_TRIM_THRESHOLD=0.40
# redeploy

Implementación

Handler: functions/api/mcp/handlers/archivo.ts:467–574.

Lógica:

  1. Validar env AI + DB.
  2. Si no hay questions, cargar desde oraculo_queries.
  3. Para cada pregunta:
    • Embeddings de la query.
    • Por cada variante: retrieve() con parámetros correspondientes.
    • Registrar métricas (chunk_ids, tokens, scores).
    • Opcionalmente sintetizar.
  4. Agregar en summary.
  5. Retornar JSON.

Tool registration: functions/api/mcp/tools.ts:999–1015.

Véase también

Subir