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.
- 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.
- 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.
- 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
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
- 01
vector_indexes
Qué se puede medir, descubierto del catálogo sin configuración: índice, tabla, método de acceso, operador.
- 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.
- 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).
- 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).
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
Las otras piezas del ecosistema
- pg_agent_gate Agentes de IA sobre PostgreSQL
- pg_phasevec · preview 0.x Memoria vectorial con procedencia
- pg_living_assertions Garantías con fecha
- pg_plan_guard Planes de ejecución vigilados
- pg_promise_guard Garantías del esquema
- pg_grammar_guard Salida estructurada que no inventa nombres
- ygg-agent v0.2.0 · PyPI El loop del agente sobre pg_agent_gate, sin MCP: el modelo escribe SQL y la base decide.