Qdrant es un motor de búsqueda vectorial de alto rendimiento y gran escala, que sirve como base para aplicaciones de inteligencia artificial y ya cuenta con una amplia adopción.
Escrito en Rust, Qdrant ofrece características de alta velocidad y seguridad en memoria. Además, utiliza un índice HNSW filtrable innovador que mejora significativamente el rendimiento de búsquedas mixtas de vectores y escalares, logrando un buen equilibrio entre rendimiento y tasa de recuperación.
Sitio web oficial de Qdrant: https://qdrant.tech/
- Instalación en un solo nodo
Se recomienda utilizar Docker para instalar Qdrant. La instalación en un solo nodo es muy sencilla. Primero descargamos la imagen:
docker pull qdrant/qdrant:v1.11.4
Dado que Qdrant se actualiza frecuentemente, la versión v1.11.4 actualmente utilizada tiene dos versiones de diferencia con la más reciente v1.14.0 (hasta el 14 de julio de 2025), pero su uso es prácticamente similar.
Antes de ejecutarlo, necesitamos preparar un archivo de configuración. El archivo por defecto puede obtenerse del repositorio fuente: https://github.com/qdrant/qdrant/blob/master/config/config.yaml
También podemos copiar la configuración de ejemplo desde la documentación oficial: https://qdrant.tech/documentation/guides/configuration/
Ambos métodos ofrecen configuraciones básicamente equivalentes. Creamos un directorio de proyecto para Qdrant y copiamos el archivo de configuración a config/config.yaml dentro del directorio. Luego lo modificamos ligeramente.
Para asegurar un acceso básico seguro, configuramos api_key y read_only_api_key bajo service:
service:
api_key: xxxxxxxx
read_only_api_key: xxxxxxxx
El campo api_key otorga permisos completos de administración, mientras que read_only_api_key está destinado únicamente a consultas.
Mantenemos el resto de la configuración por defecto. Creamos un archivo de configuración Docker Compose en el directorio del proyecto:
services:
qdrant:
image: qdrant/qdrant:v1.11.4
restart: always
container_name: qdrant
ports:
- 6333:6333
- 6334:6334
- 6335:6335
expose:
- 6333
- 6334
- 6335
configs:
- source: qdrant_config
target: /qdrant/config/production.yaml
volumes:
- /data/qdrant:/qdrant/storage
configs:
qdrant_config:
file: ./config/config.yaml
Qdrant escucha tres puertos principales: 6333 para HTTP, 6334 para gRPC y 6335 para comunicación entre nodos en clúster.
En configs, mapeamos el archivo de configuración externo al contenedor y usamos volumes para mapear el directorio de datos externo.
Finalmente iniciamos el servicio Qdrant:
docker compose up -d
Tras iniciar, verificamos los logs para confirmar que todo funciona correctamente. Si no hay errores, podemos acceder a la interfaz web en http://<ip>:6333/dashboard.
Desde allí, podemos seguir el tutorial para crear colecciones, insertar datos y realizar búsquedas. En el menú "Collections" se muestran las colecciones creadas y sus detalles. El menú "Console" permite ejecutar consultas simples.
Este es el proceso básico de instalación de Qdrant en un solo nodo.
- Despliegue distribuido
Para configurar un despliegue en clúster, se requiere al menos tres nodos conectados mediante el protocolo Raft.
Supnogamos que tenemos tres nodos con las siguientes direcciones IP:
10.22.1.21 node1
10.22.1.22 node2
10.22.1.23 node3
Modificamos ligeramente la configuración para crear un clúster. Añadimos lo siguiente:
cluster:
enabled: true
Esto habilita el modo clúster. Cada nodo debe tener este archivo de configuración sincronizado.
En el primer nodo, modificamos el archivo Docker Compose así:
services:
qdrant:
image: qdrant/qdrant:v1.11.4
command: ./entrypoint.sh --uri 'http://10.22.1.21:6335'
# ...
Solo añadimos el parámetro --uri, que especifica la dirección IP y puerto del nodo actual para que otros nodos puedan conectarse.
Los nodos restantes se configuran así:
# node2
services:
qdrant:
image: qdrant/qdrant:v1.11.4
command: ./entrypoint.sh --uri 'http://10.22.1.22:6335' --bootstrap 'http://10.22.1.21:6335'
# ...
# node3
services:
qdrant:
image: qdrant/qdrant:v1.11.4
command: ./entrypoint.sh --uri 'http://10.22.1.23:6335' --bootstrap 'http://10.22.1.21:6335'
# ...
Los nodos adicionales deben incluir tanto --uri como --bootstrap, indicando cuál nodo actúa como punto de arranque para establecer la conexión.
Una vez iniciado, el primer nodo se convierte en líder del clúster. Durante el inicio, podría aparecer un error temporal al intentar conectar, debido a que los puertos aún no están activos, pero esto no afecta el funcionamiento si no persiste.
Es importante usar direcciones IP en lugar de nombres de host, ya que estamos trabajando con redes de contenedores donde los nombres de host no son reconocidos.
Al reiniciar posteriormente, dado que el estado del clúster se guarda localmente, se puede omitir el parámetro --bootstrap.
Podemos verificar el estado del clúster con:
curl -H 'api-key: xxxxx' http://10.22.1.21:6333/cluster | python3 -m json.tool
Se mostrará la lista de nodos y sus roles. Si algún nodo falla y es detectado, aparecerán errores en consensus_thread_status.
Referencias: