Crear una pila de monitorización de bases de datos vectoriales con Prometheus y Grafana

VectorAI DB ofrece una interfaz nativa /metrics punto final en formato Prometheus/OpenMetrics en el puerto 6573. Este tutorial integra ese punto final en una pila de Docker Compose con Prometheus y Grafana, crea un panel de control de cuatro paneles que puedes importar directamente y configura ocho reglas de alerta según la documentación de monitorización de VectorAI DB. Antes de proceder a la configuración, a continuación te explicamos qué es lo que realmente miden esas métricas.

Qué mide la supervisión de bases de datos de Vector

La supervisión de bases de datos vectoriales consiste en vigilar una serie de indicadores clave para garantizar que la base de datos funcione según lo previsto. Entre estos indicadores se incluyen la latencia de las consultas, el uso de memoria, el uso de la CPU, el estado de los índices y la calidad de recuperación. Cada uno de ellos se corresponde con una métrica específica de tu instancia de VectorAI DB.

La latencia de la consulta es el tiempo que tarda la búsqueda de los k vecinos más cercanos en devolver resultados. Dado que la búsqueda vectorial se basa en la similitud y no en coincidencias exactas, es el primer dato que tiene en cuenta tu SLA. VectorAI DB realiza un seguimiento de este dato a través de actian_vectorai_rest_responses_duration_seconds (p95/p99 por punto final). En situaciones de presión de memoria o durante la reconstrucción de un índice, la latencia puede dispararse muy por encima del nivel de referencia normal, pasando en ocasiones de unos 20 ms a 500 ms.

El actian_vectorai_memory_resident_bytes Esta métrica muestra cuánta memoria RAM consumen los índices de tus vectores. Otra métrica clave es actian_vectorai_process_major_page_faults_total. Un aumento constante en este valor indica que hay presión sobre la memoria y puede ser señal de que el sistema operativo está recuperando páginas del almacenamiento en disco, lo que suele aumentar la latencia de las consultas.

actian_vectorai_process_threads muestra el número de subprocesos durante los cálculos de similitud. Un aumento del número de subprocesos bajo carga refleja la demanda del procesador, y al combinarlo con las métricas de la CPU a nivel del sistema procedentes del exportador de nodos de Prometheus, se obtiene una visión completa de la situación.

El índice de estado te permite conocer lo que ocurre en segundo plano. El actian_vectorai_collection_running_optimizations y actian_vectorai_rebuild_running Las métricas indican cuándo se están llevando a cabo las reconstrucciones. actian_vectorai_rebuild_failed_total registra cualquier fallo, y actian_vectorai_rebuild_duration_seconds muestra cuánto tiempo tardan las reconstrucciones.

VectorAI DB no muestra el «recall» —el porcentaje de vecinos más cercanos correctos devueltos— como métrica en tiempo real. Valídalo fuera de línea con un conjunto de prueba etiquetado y utiliza, en su lugar, la latencia y la tasa de error.

Lo que vas a crear

Poner VectorAI DB en producción implica poder mostrar cómo se comporta el sistema bajo carga, cómo detectar un estado de degradación y cómo recibirías una alerta antes de que se produzca un incidente. La monitorización es especialmente importante para las cargas de trabajo de generación aumentada por recuperación (RAG) que utilizan modelos de lenguaje a gran escala, ya que los picos de latencia o los fallos en los índices pueden degradar la calidad de la respuesta de la IA. Una configuración de monitorización adecuada te avisa de cuándo aumenta la latencia, cuándo se acumula presión en la memoria y cuándo fallan las reconstrucciones de índices, antes de que nada de esto llegue a los usuarios.

VectorAI DB ofrece un /metrics punto final en el puerto 6573 en formato Prometheus/OpenMetrics, por lo que no necesitas exportadores ni agentes adicionales para la aplicación metrics. El exportador de nodos opcional de Prometheus recoge datos sobre la CPU y la memoria a nivel de host si necesitas una visibilidad de todo el sistema que vaya más allá de lo que ofrece directamente VectorAI DB.

En este tutorial, conectarás ese punto final a una pila de Docker Compose con VectorAI DB, Prometheus y Grafana. Crearás un panel de control de cuatro paneles que podrás importar de inmediato y configurarás ocho reglas de alerta siguiendo la documentación de monitorización de VectorAI DB.

Al final, tendrás un panel de control y unas reglas de alerta configuradas que se ejecutarán en tu propia instancia.

Qué datos revela el punto final de métricas sobre el rendimiento de las bases de datos vectoriales

VectorAI DB ofrece sus métricas en GET /metrics en el puerto de la API REST (por defecto, el 6573) en formato Prometheus/OpenMetrics. Este punto final no requiere autenticación, por lo que, si lo expones a una red pública, debes protegerlo con un cortafuegos o un proxy inverso y controles de acceso.

Todas las métricas comienzan con el actian_vectorai_ prefijo. En la tabla siguiente se enumeran las principales métricas en seis categorías, indicando su tipo y lo que revelan sobre el estado del sistema y el uso de los recursos.

Configurar la pila

Requisitos previos

Antes de empezar, instala lo siguiente:

• • Docker y Docker Compose
  • Python 3.10 o superior
  • VectorAI DB (regístrate en la edición para la comunidad)
  • SDK de Python de Actian-VectorAI-Client: pip install actian-vectorai-client

Asegúrate de que tu ordenador tenga al menos 8 GB de RAM (se recomiendan 16 GB) y 10 GB de espacio en disco.

Si utilizas Windows, ejecuta todos los comandos en WSL2. Para configurar WSL2, ejecuta wsl --install en PowerShell, utiliza el terminal de Ubuntu para este tutorial.

Estructura del proyecto

Crea un directorio para el proyecto y una estructura de carpetas:

mkdir -p vectorai-observability/{prometheus,grafana,scripts}
cd vectorai-observability

touch docker-compose.yml prometheus/prometheus.yml prometheus/alert_rules.yml scripts/load_test.py

El directorio de tu proyecto debería tener este aspecto:

vectorai-observability/

├── docker-compose.yml

├── prometheus/

│   ├── prometheus.yml

│   └── alert_rules.yml

├── grafana/

└── scripts/

    └── load_test.py

Tu pila de observabilidad se ejecutará como tres servicios de Docker Compose: VectorAI DB (REST/métricas en el puerto 6573, gRPC en el puerto 6574 y la interfaz de usuario local en el puerto 6575), Prometheus (puerto 9090) y Grafana (puerto 3000).

services:
  vectorai:
    image: actian/vectorai:latest
    platform: linux/amd64
    container_name: vectorai
    ports:
      - "6573:6573"
      - "6574:6574"
      - "6575:6575"
    volumes:
      - ./local_data:/var/lib/actian-vectorai
    environment:
      - ACTIAN_VECTORAI_ACCEPT_EULA=YES
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
      - ./prometheus/alert_rules.yml:/etc/prometheus/alert_rules.yml
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
    restart: unless-stopped
    depends_on:
      - vectorai

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    restart: unless-stopped
    depends_on:
      - prometheus

volumes:
  grafana_data:

Añade esto a prometheus/prometheus.yml. En las implementaciones de Docker Compose, Prometheus identifica VectorAI DB por el nombre del servicio. Si estás ejecutando VectorAI DB como un contenedor independiente fuera de la red de Compose, utiliza host.docker.internal:6573 en su lugar, como destino de la extracción:

global:
  scrape_interval: 15s

rule_files:
  - "alert_rules.yml"

scrape_configs:
  - job_name: "vectorai"
    scrape_interval: 15s
    static_configs:
      - targets: ["vectorai:6573"]

docker compose up -d

Ir a localhost:9090/targets. El vectorai El trabajo debería mostrar 1/1 UP con una duración de la lectura inferior a 20 ms. Si muestra DOWN, comprueba que el puerto 6573 esté abierto y que ningún cortafuegos esté bloqueando la conexión.

Ir a localhost:3000 e inicia sesión con tus credenciales de administrador. A continuación, ve a «Conexiones», selecciona «Fuentes de datos», haz clic en «Añadir nueva fuente de datos», selecciona «Prometheus» y configura la URL en http://prometheus:9090, configúralo como predeterminado y guarda los cambios.

Crear el panel de control de la base de datos Vector

El panel de control supervisa cuatro indicadores clave: la tasa de solicitudes, la latencia p95, la tasa de errores y la presión de memoria. La supervisión de estos indicadores te ayuda a optimizar el rendimiento de la indexación y la búsqueda. Añade las siguientes consultas PromQL al archivo grafana/dashboard.json a medida que creas cada panel en Grafana.

Panel 1: Frecuencia de solicitudes REST por punto de conexión

Este panel muestra el rendimiento de las consultas por punto final a lo largo del tiempo. Crea un panel de series temporales con esta consulta PromQL:

sum by (endpoint) (rate(actian_vectorai_rest_responses_total[5m]))

Establece el formato de la leyenda en {{endpoint}}. Muestra el rendimiento de cada punto final, lo que te permite identificar qué rutas están generando carga y detectar patrones de consultas antes de que afecten al rendimiento.

Panel 2: Latencia de REST p95 por punto final

Esta es la señal de latencia principal para la supervisión del SLA. Métricas de histograma de Prometheus actian_vectorai_rest_responses_duration_seconds exponer automáticamente _bucket serie, que es lo que histogram_quantile para realizar consultas. Crea un panel de series temporales:

histogram_quantile(0.95, sum by (le, endpoint) (rate(actian_vectorai_rest_responses_duration_seconds_bucket[5m])))

Establece el formato de la leyenda en {{endpoint}}. Si la latencia aumenta mientras que la tasa de solicitudes se mantiene constante, podría indicar una sobrecarga de memoria o una reconstrucción de índices que afecte al rendimiento de las búsquedas.

Panel 3: Índice de errores de gRPC

El SDK de Python se comunica a través de gRPC, por lo que la supervisión de errores se lleva a cabo en la capa de gRPC. Crea un panel de estadísticas con:

sum(rate(actian_vectorai_grpc_responses_fail_total[5m]))
/
(sum(rate(actian_vectorai_grpc_responses_total[5m])) > 0 or vector(1))

La consulta devuelve una fracción comprendida entre 0 y 1. Establece los valores umbral en 0,01 para el verde, 0,05 para el amarillo y cualquier valor superior a 0,05 para el rojo, o configura la unidad de Grafana en percent (0-1) para mostrar los valores en forma de porcentajes de forma automática. El panel pasa de verde a amarillo a medida que los errores se acercan al 5 %, y a rojo una vez que superan ese umbral, lo que permite detectar una consulta de recopilación errónea o un fallo de conectividad antes de que la situación se agrave.

Módulo 4: Presión de memoria

Este panel realiza un seguimiento de dos señales que, en conjunto, indican si el motor está funcionando dentro de los límites seguros de utilización de la memoria. Crea un panel de series temporales con dos consultas:

# RSS: RAM consumed by vector indexes
actian_vectorai_memory_resident_bytes

# Early warning signal for disk paging
rate(actian_vectorai_process_major_page_faults_total[5m])

Establece las etiquetas de la leyenda en RSS y Major Page Faults/s. Si la tasa de fallos aumenta cuando el RSS se acerca a su límite, el motor recurrirá al disco y la latencia aumentará rápidamente.

Una vez que hayas configurado los cuatro paneles, abre la configuración de Dashboard, ve a «Modelo JSON» y copia el contenido. Guárdalo en grafana/dashboard.json. Este archivo también se encuentra en el Repositorio de GitHub, así que puedes clonar el repositorio e importarlo a Grafana de inmediato.

Configurar reglas de alerta

Añade las siguientes reglas de alerta a prometheus/alert_rules.yml. Prometheus los carga automáticamente al iniciarse a través del rule_files directiva en prometheus.yml.

groups:
  - name: vectorai
    rules:
      - alert: VectorAIHighRESTErrorRate
        expr: >
          sum(rate(actian_vectorai_rest_responses_fail_total[5m]))
          /
          sum(rate(actian_vectorai_rest_responses_total[5m]))
          > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB REST error rate above 5%"
          description: "{{ $value | humanizePercentage }} of REST requests are returning errors."

      - alert: VectorAIHighRESTLatency
        expr: >
          histogram_quantile(0.95, sum by (le) (rate(actian_vectorai_rest_responses_duration_seconds_bucket[5m])))
          > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB REST p95 latency above 2s"
          description: "REST p95 latency is {{ $value }}s."

      - alert: VectorAIHighGRPCErrorRate
        expr: >
          sum(rate(actian_vectorai_grpc_responses_fail_total[5m]))
          /
          sum(rate(actian_vectorai_grpc_responses_total[5m]))
          > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB gRPC error rate above 5%"
          description: "{{ $value | humanizePercentage }} of gRPC calls are failing."

      - alert: VectorAIRecoveryModeActive
        expr: actian_vectorai_app_status_recovery_mode == 1
        for: 0m
        labels:
          severity: critical
        annotations:
          summary: "VectorAI DB is in recovery mode"
          description: "The engine has entered recovery mode and requires immediate attention."

      - alert: VectorAIHighMemoryUsage
        expr: actian_vectorai_memory_resident_bytes > 0.8 * 8589934592  # Replace with your memory limit in bytes
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB memory usage above 80%"
          description: "RSS is {{ $value | humanize }}B, exceeding 80% of available memory."

      - alert: VectorAIMajorPageFaultsRising
        expr: rate(actian_vectorai_process_major_page_faults_total[5m]) > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB major page faults rising"
          description: "Sustained major page faults indicate memory pressure and potential disk paging."

      - alert: VectorAIFileDescriptorExhaustion
        expr: actian_vectorai_process_open_fds > 0.8 * 65536  # Replace with your system fd limit
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB file descriptors approaching limit"
          description: "Open file descriptors at {{ $value }}, approaching 80% of system limit."

      - alert: VectorAIRebuildFailures
        expr: rate(actian_vectorai_rebuild_failed_total[1h]) > 0
        for: 0m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB index rebuild failure detected"
          description: "One or more index rebuilds have failed in the last hour."

Hay dos reglas que utilizan valores específicos del entorno que debes configurar antes de la implementación. VectorAIHighMemoryUsage se activa cuando el RSS supera el 80 % de la memoria disponible, así que sustituye 8589934592 con tu límite de memoria real en bytes. VectorAIFileDescriptorExhaustion se activa cuando los descriptores de archivo abiertos se acercan al 80 % del límite del sistema, así que sustituye 65536 con el resultado de ulimit -n en tu servidor.

VectorAIRecoveryModeActive y VectorAIRebuildFailures uso for: 0m, lo que significa que se activan de inmediato, en lugar de esperar a que se produzca una condición prolongada. Los fallos en el modo de recuperación y en la reconstrucción deben atenderse en el momento en que se producen, no tras un plazo de cinco minutos.

Comprueba que las ocho reglas se hayan cargado correctamente accediendo a localhost:9090/alerts.

Validar bajo carga

Ejecuta el script de prueba de carga para generar tráfico de consultas real en tu instancia de VectorAI DB. Añade lo siguiente a scripts/load_test.py:

import random
import time
from concurrent.futures import ThreadPoolExecutor
from actian_vectorai import VectorAIClient, VectorParams, Distance

COLLECTION = "load_test"
DIMENSION = 128
TOTAL_QUERIES = 1000
RPS = 50
DURATION = 60

def random_vector(dim):
    return [random.uniform(-1, 1) for _ in range(dim)]

def run_query(client):
    try:
        client.points.search(
            collection_name=COLLECTION,
            vector=random_vector(DIMENSION),
            limit=10
        )
    except Exception as e:
        print(f"Query error: {e}")

def main():
    with VectorAIClient("localhost:6574") as client:
        try:
            client.collections.create(
                name=COLLECTION,
                vectors_config=VectorParams(size=DIMENSION, distance=Distance.Cosine)
            )
            print(f"Created collection: {COLLECTION}")
        except Exception as e:
            print(f"Collection {COLLECTION} already exists, continuing... ({e})")

        print(f"Running {TOTAL_QUERIES} queries at {RPS} req/s for {DURATION}s...")
        interval = 1.0 / RPS
        start = time.time()
        count = 0

        with ThreadPoolExecutor(max_workers=10) as executor:
            while count < TOTAL_QUERIES and (time.time() - start) < DURATION:
                executor.submit(run_query, client)
                count += 1
                time.sleep(interval)

        elapsed = time.time() - start
        print(f"Done. {count} queries in {elapsed:.1f}s ({count/elapsed:.1f} req/s)")

if __name__ == "__main__":
    main()

A continuación, ejecútalo:

python scripts/load_test.py

El script se conecta a la base de datos de VectorAI a través de gRPC en el puerto 6574, crea una colección de 128 dimensiones y envía 1.000 consultas de vectores aleatorios a un ritmo de 50 solicitudes por segundo durante 60 segundos. A medida que se ejecuta el script, el panel de tasa de solicitudes registra el tráfico, la latencia p95 se estabiliza y la tasa de errores de gRPC se mantiene en cero.

Para que se active el panel de índices de error, realiza una consulta sobre una colección que no exista:

from actian_vectorai import VectorAIClient

with VectorAIClient("localhost:6574") as client:
    try:
        client.points.search(
            collection_name="nonexistent_collection",
            vector=[0.1]*128,
            limit=5
        )
    except Exception as e:
        print(f"Error: {e}")

El panel de índices de error de gRPC se dispara de inmediato. Esta secuencia muestra a tu equipo cómo se comporta el sistema cuando funciona correctamente y cuando surge algún problema.

Tres escenarios de seguimiento

El pico en la tasa de solicitudes que has observado durante la prueba de carga es lo que se conoce como «pico de tráfico» en un motor de recomendación de productos. Cuando ese pico se produce junto con un aumento de la latencia p95, el índice vectorial se ve sometido a presión de memoria. El panel de presión de memoria lo detecta antes de que llegue al usuario.

Los fallos en la reconstrucción de índices en un sistema de recuperación de imágenes médicas reducen silenciosamente la precisión de la recuperación sin generar ningún error. El panel de ratios de errores de gRPC no los detecta, pero actian_vectorai_rebuild_failed_total y el VectorAIRebuildFailures Se activará una alerta. La alerta se activa en el plazo de una hora tras cualquier fallo, y la supervisión actian_vectorai_rebuild_duration_seconds te avisa cuando las reconstrucciones de índices, provocadas por la incorporación de nuevos datos o por actualizaciones de modelos, están tardando más de lo previsto.

El panel de índices de error de gRPC se disparó hasta 0.952 en nuestra prueba, ya que 20 solicitudes fallidas consecutivas, frente a un nivel de referencia bajo de solicitudes exitosas, hicieron que la proporción se acercara a 1. Esa misma señal es la que detecta un proceso de detección de fraudes cuando los fallos de autenticación impiden consultar las transacciones en tiempo real. La comparación de los vectores de transacciones con las firmas de fraude conocidas requiere una latencia de consulta inferior a 100 ms. Cuando ese indicador se pone en rojo, el proceso ya está en riesgo.

Configurar el registro estructurado

Añade lo siguiente a la configuración de tu base de datos VectorAI para habilitar los registros en formato JSON compatibles con Elasticsearch, Loki o Datadog.

registro:
  formato: json
  nivel: info

Configura el nivel de registro en función de tu entorno:

El uso de los niveles «debug» o «trace» en el entorno de producción genera un gran volumen de datos de registro y puede afectar al rendimiento de la base de datos. Utiliza estos niveles únicamente para la resolución de problemas a corto plazo y, a continuación, vuelve al nivel «info».

Conclusión

Ahora dispones de una pila de monitorización que muestra cuándo se producen cambios en la latencia de la búsqueda vectorial, la presión de memoria o los errores de gRPC antes de que los usuarios lo noten. Prometheus recopila métricas en tiempo real desde el puerto 6573; tu panel de Grafana, compuesto por cuatro paneles, recoge las señales que realmente importan; y ocho reglas de alerta se activan en el momento en que cualquiera de ellas supera un umbral definido por tu equipo.

Clona el Repositorio de GitHub Para obtener la pila completa: docker-compose.yml, prometheus/prometheus.yml, prometheus/alert_rules.yml, grafana/dashboard.json, y scripts/load_test.py. Importa el archivo JSON del panel a Grafana y ya tendrás la pila lista.

Para obtener más información sobre el punto final de métricas y la configuración de la supervisión, consulta la documentación sobre la supervisión de VectorAI DB.

Acerca del autor

Acerca de Tahiya Chowdhury

Tahiya Chowdhury es la directora de producto de Actian Zen y VectorAI DB, donde dirige la estrategia de la plataforma de datos en el borde más sólida del sector. Gracias a su experiencia en MongoDB y Goldman Sachs, Tahiya se especializa en crear productos que se sitúan en la intersección entre las necesidades empresariales a gran escala y la agilidad de los desarrolladores modernos. Le apasiona eliminar la complejidad de la infraestructura de datos, lo que permite a los equipos de ingeniería pasar más rápidamente del prototipo a la producción.