Ir al contenido
← Ecosistema

Recall de índices vectoriales

pg_recall_guard v0.2.10

Un índice ANN degradado no falla: devuelve vecinos plausibles y no menciona los que dejó fuera.

Mide el recall de cualquier índice vectorial contra la verdad exacta, registra el número que aceptaste como bueno y avisa cuando deriva. Sin error, sin log y sin alerta, te enterarías cuando un usuario dijera que la búsqueda "se siente peor".

Instalar

CREATE EXTENSION pg_recall_guard;

En simple

Mide si tu buscador inteligente sigue encontrando lo que debería, y avisa cuando empieza a fallar sin que nadie lo note.

  1. La situación

    Tu asistente busca documentos "parecidos" a lo que se le pregunta: la búsqueda semántica que usan los sistemas de IA.

  2. Sin esta pieza

    Con el tiempo, el índice que hace esa búsqueda se degrada: devuelve resultados plausibles, pero se le escapan los mejores. No hay ningún error que ver.

  3. Con esta pieza

    Tu equipo aprueba un número ("encuentra el 98 % de lo que debe") y una medición programada lo vuelve a calcular. Cuando baja, el monitoreo lo dice: bien, degradado, crítico.

Por qué importa si decides

  • Calidad de búsqueda con un número, no con una sensación
  • Sirve con cualquier índice vectorial, el de hoy y el que se instale mañana
  • Madurez declarada: medido en un conjunto de datos, todavía sin carga de producción
Para el equipo técnico

El problema

Cuatro de los diez vecinos buenos faltan y nadie lo dice

La degradación de un índice aproximado es gradual y silenciosa: el único momento en que se atrapa es cuando algo se molesta en mirar.

Funciona con cualquier índice vectorial porque nunca nombra uno: los descubre por pg_amop (métodos que responden un ORDER BY sobre un operador de distancia). Hoy hnsw e ivfflat (pgvector), diskann (pgvectorscale), gist y spgist; mañana lo que venga, sin cambiar nada acá.

Cómo funciona

Aprobar una línea base, medir en un cron, leer un veredicto

  1. 01

    vector_indexes

    Qué se puede medir, descubierto del catálogo sin configuración: índice, tabla, método de acceso, operador.

  2. 02

    approve(index, p_k, p_sample_size)

    Registra lo que consideras bueno. Las consultas de muestra se toman de filas de la propia tabla.

  3. 03

    check()

    Una fila por línea base con verdict: ok (dentro de 0,02 de la base), degraded (0,02 a 0,10 por debajo), critical (más de 0,10), o COULD NOT MEASURE con el error (índice borrado, el planner eligió otro).

  4. 04

    Construido para no halagarse a sí mismo

    El lado indexado debe usar ESE índice (si el planner elige otro, la función lo dice); la verdad exacta no debe usarlo; se piden k+1 vecinos y se descarta el ctid de origen (un vector siempre se encuentra a sí mismo: con k=10 el recall nunca bajaría de 0,1); los empates se juzgan por distancia; una fila es su tabla y su ctid (particiones).

SQL

Uso

Cada función corre con search_path = pg_catalog, pg_temp y la línea base nombra su índice con esquema: check() mide el mismo índice desde tu sesión, desde pg_cron o desde una sesión sin ese esquema en el path; una tabla temporal no puede suplantarlo (test/pg_temp.sh, rojo en 0.2.3 y verde desde 0.2.4).

psql · pg_recall_guardsql
CREATE EXTENSION pg_recall_guard;

-- ¿Qué se puede medir? Descubierto del catálogo.
SELECT index_name, table_name, access_method, operator
  FROM recall_guard.vector_indexes;

-- Registrar lo que consideras bueno.
SELECT recall_guard.approve('items_hnsw', p_k => 10, p_sample_size => 100);

-- Después, desde pg_cron o tu monitoreo:
SELECT * FROM recall_guard.check();
--     index_name     | baseline | current |  drift  | verdict
-- -------------------+----------+---------+---------+---------
--  public.items_hnsw |   0.9800 |  0.8100 | -0.1700 | critical

Lo que garantiza

Lo que garantiza

  • Un 1.0000 tranquilizador que no significa nada queda descartado por construcción: el índice medido es el aprobado y la verdad no lo usa.
  • Medir un índice no corre nada que haya escrito el dueño de su tabla (0.2.6): el vector muestreado se castea al tipo base, no al dominio con sus CHECK.
  • Matriz 10 a 19 verde con make installcheck en contenedores oficiales (medido 2026-09-16).
  • Mide el índice bajo los ajustes con que se aprobó: approve() guarda los ajustes de búsqueda (hnsw.*, ivfflat.*, diskann.*) y check() mide con ellos, así que ningún rol hace pasar un índice degradado con un SET.
  • Es neutral: no pertenece a ningún índice, así que puede vigilarlos a todos.

Lo que no hace

Madurez, dicha antes de que confíes

  • check() corre un seq scan exacto por consulta muestreada: no es gratis ni para cada petición. Es para un cron, sobre una muestra, como ANALYZE. Parte con p_sample_size => 30.
  • Las cifras de rendimiento vienen de una máquina y un dataset (38.352 vectores, 768 dimensiones) sobre hnsw y diskann. Otras dimensiones y parámetros, no probados.
  • Nadie lo ha corrido contra una carga de producción todavía; el 0.1.0 era testing y nadie podía encontrarlo. Trata los números de recall como confiables y la cobertura como estrecha.
  • La estrategia de muestreo (vectores de la propia tabla) es un proxy razonable del tráfico real, no el tráfico real: capturar consultas reales necesita un hook del executor en C, que esto no tiene.
  • Desde 0.2.9 los veredictos están en inglés (antes en español): un monitor que filtraba por "degradado" o "critico" debe actualizarse.
  • check() mide el índice, no la configuración de la aplicación: si alguien baja ivfflat.probes para toda la aplicación, esto no lo ve.
  • Una línea base va por nombre: un índice borrado y creado de nuevo con el mismo nombre la hereda. Vuelve a aprobar después de un cambio así.

Para la empresa

Para la empresa

Es la medición que falta en todo sistema de búsqueda semántica en producción: un número aprobado, un cron que lo re-mide y un veredicto que el monitoreo entiende.

  • Independiente del índice: sirve con pgvector hoy y con lo que se instale mañana
  • Veredictos con umbrales fijos (0,02 / 0,10) que no se mueven solos
  • Reportes de otros datasets son lo más útil que se puede enviar al proyecto

Esta pieza no viene en la imagen Enterprise 0.3.1, que trae pg_agent_gate, pg_living_assertions, pg_promise_guard y pg_grammar_guard. Se instala aparte desde PGXN.

Ficha técnica

Versión
0.2.10 en PGXN; no viene en la imagen pública 0.3.6 (medido 13-11-2026)
PostgreSQL
10 a 19 verdes (installcheck, 2026-09-16); rendimiento medido en 18.6 y 19beta2
Depende de
tsm_system_rows (contrib); funciona con pgvector, pgvectorscale y cualquier índice con operadores de distancia
Licencia
Apache-2.0
Edición Enterprise
No viene en la imagen Enterprise 0.3.1
Pruébala Hablar