Alojar Qdrant en un VPS

Por qué autoalojar Qdrant en un VPS

Requisitos previos y recursos VPS recomendados

• RAM: mínimo 1 GB para pruebas, 2 GB para unos cientos de miles de vectores, 4–8 GB por encima del millón de vectores en alta dimensión (el índice HNSW vive en memoria).
• Almacenamiento: 20–50 GB de SSD NVMe para persistir colecciones y snapshots.
• CPU: 1–2 vCPU son suficientes para tráfico moderado; añada núcleos si indexa continuamente.
• Docker y Docker Compose instalados en el VPS.
• Puertos 6333 (REST) y 6334 (gRPC) accesibles desde su aplicación; 80/443 para el reverse proxy público.
• Un registro DNS A (p. ej. vectors.midominio.com) si expone la API en HTTPS.

Instalar Qdrant con Docker Compose

1. 01

   Crear el directorio y el compose.yml

   En el VPS, cree una carpeta dedicada: mkdir -p /opt/qdrant && cd /opt/qdrant. Cree el siguiente compose.yml:

   services:
     qdrant:
       image: qdrant/qdrant:latest
       restart: unless-stopped
       ports:
         - "127.0.0.1:6333:6333"
         - "127.0.0.1:6334:6334"
       volumes:
         - ./qdrant_storage:/qdrant/storage
       environment:
         - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}

   Enlazar los puertos a 127.0.0.1 impide cualquier exposición directa en Internet; solo el reverse proxy puede acceder a ellos.

2. 02

   Generar la clave API e iniciar el contenedor

   Cree el archivo .env con su clave:

   echo "QDRANT_API_KEY=$(openssl rand -hex 32)" > .env

   Inicie Qdrant:

   docker compose up -d

3. 03

   Comprobar la salud de la instancia

   Espere unos segundos y verifique el endpoint de salud:

   curl -s http://localhost:6333/healthz
   # Esperado: {"title":"qdrant - vector search engine","version":"..."}

4. 04

   Crear su primera colección

   Cree una colección de prueba con vectores de dimensión 384:

   curl -s -X PUT http://localhost:6333/collections/test \
     -H 'Content-Type: application/json' \
     -H "api-key: $(grep QDRANT_API_KEY .env | cut -d= -f2)" \
     -d '{"vectors":{"size":384,"distance":"Cosine"}}'

Segurizar el acceso: clave API y TLS

vectors.midominio.com {
    reverse_proxy localhost:6333
}

location / {
    proxy_pass http://127.0.0.1:6333;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Probar la autenticación y el reverse proxy

1. 05

   Verificar que el acceso sin clave es rechazado

   curl -s https://vectors.midominio.com/collections
   # Esperado: {"status":{"error":"Unauthorized",...}}

2. 06

   Llamada autenticada con la clave API

   curl -s https://vectors.midominio.com/collections \
     -H "api-key: YOUR_KEY"
   # Esperado: {"result":{"collections":[]},"status":"ok",...}

3. 07

   Verificar el certificado TLS

   curl -sv https://vectors.midominio.com/healthz 2>&1 | grep 'SSL connection\|issuer'
   # Esperado: líneas confirmando Let's Encrypt y TLS 1.3

Crear una colección e insertar vectores con el cliente Python v1

1. 08

   Instalar el cliente oficial

   pip install qdrant-client>=1.7

2. 09

   Conectar con la clave API

   from qdrant_client import QdrantClient
   
   client = QdrantClient(
       url="https://vectors.midominio.com",
       api_key="YOUR_KEY",
   )

3. 10

   Crear una colección con VectorParams

   from qdrant_client.models import Distance, VectorParams
   
   client.recreate_collection(
       collection_name="documentos",
       vectors_config=VectorParams(size=384, distance=Distance.COSINE),
   )

4. 11

   Insertar puntos con payload y consultar

   from qdrant_client.models import PointStruct
   
   client.upsert(
       collection_name="documentos",
       points=[
           PointStruct(
               id=1,
               vector=[0.1, 0.2, ...],
               payload={"titulo": "Guía Qdrant", "lang": "es"},
           ),
       ],
   )
   
   resultados = client.search(
       collection_name="documentos",
       query_vector=[0.1, 0.21, ...],
       limit=5,
       with_payload=True,
   )
   for r in resultados:
       print(r.score, r.payload)

Optimizar el rendimiento: ajuste de HNSW

Parámetros HNSW clave

Desplace la tabla

Reducir la huella de memoria: cuantificación escalar y binaria

• Cuantificación escalar (uint8): comprime cada coordenada float32 (4 bytes) a uint8 (1 byte), una reducción de RAM de ~4×. Ligera pérdida de precisión compensada por el sobremuestreo (oversampling).
• Cuantificación binaria: reducción de hasta 32× binarizando cada dimensión. Ideal para modelos entrenados para cuantificación binaria.
• Parámetro on_disk: almacena los vectores originales en disco y mantiene en RAM solo el índice cuantificado. Indispensable en un VPS con memoria limitada.
• Oversampling: con oversampling=2.0 en la consulta, Qdrant recupera el doble de candidatos del índice cuantificado y los reordena con los vectores originales.

Hacer copias de seguridad y restaurar con snapshots de Qdrant

1. 12

   Crear un snapshot de una colección

   curl -s -X POST https://vectors.midominio.com/collections/documentos/snapshots \
     -H "api-key: YOUR_KEY"

2. 13

   Listar los snapshots disponibles

   curl -s https://vectors.midominio.com/collections/documentos/snapshots \
     -H "api-key: YOUR_KEY"

3. 14

   Descargar el snapshot

   curl -O https://vectors.midominio.com/collections/documentos/snapshots/NOMBRE_SNAPSHOT \
     -H "api-key: YOUR_KEY"

   Copie el archivo .snapshot a un almacenamiento de objetos externo para una copia de seguridad fuera del sitio.

4. 15

   Restaurar desde un snapshot

   curl -s -X PUT https://vectors.midominio.com/collections/documentos/snapshots/upload \
     -H "api-key: YOUR_KEY" \
     -H 'Content-Type: multipart/form-data' \
     -F [email protected]

Resolución de problemas habituales

• Connection refused en el puerto 6333: compruebe que el contenedor está en marcha (docker compose ps) y que el puerto no está bloqueado por ufw.
• Error OOM / contenedor eliminado: reduzca ef_construct o active la cuantificación escalar para bajar la huella de RAM del índice.
• Lentitud en el arranque o la primera carga: el índice HNSW se carga desde el disco en el primer acceso; use SSD NVMe y realice una búsqueda de calentamiento tras el inicio.
• Unauthorized 403: la clave en la cabecera api-key no coincide con QDRANT__SERVICE__API_KEY; compruebe que no hay espacios ni saltos de línea en la variable de entorno.
• Recall degradado tras activar la cuantificación binaria: aumente oversampling a 3.0 o 4.0 y active rescore=True para reordenar los candidatos con los vectores originales.

Asociar Qdrant con Ollama para un stack RAG totalmente autónomo