Despliega Qdrant desde la plantilla de Easypanel, protégelo con su API key, crea una colección y prueba la búsqueda por similitud que usa un RAG.
Un RAG (generación aumentada por recuperación) responde preguntas con tus propios documentos: primero busca los fragmentos que más se parecen a la pregunta y después se los pasa a un modelo de lenguaje. Qdrant hace la primera parte, la recuperación: guarda cada fragmento como un vector y encuentra los más cercanos. Para montarlo y probarlo no necesitas ningún modelo de IA. En este manual lo despliegas desde una plantilla de Easypanel, lo proteges y haces una búsqueda real en unos quince minutos.
Antes de empezar
- Easypanel funcionando y un proyecto creado (Primeros pasos con Easypanel en tu VPS). En los ejemplos el proyecto se llama
demoy el servicio,qdrant. - Una clave larga y aleatoria para la API. Puedes generarla en tu ordenador con
openssl rand -hex 32y guardarla en tu gestor de contraseñas.
Paso a paso
- En tu proyecto, pulsa Plantillas y busca «Qdrant».
- Pulsa la tarjeta. En Crear Qdrant deja el nombre
qdranty la imagen que propone (qdrant/qdrant:v1.17cuando se hizo este manual) y pulsa Crear.
- Ponle la API key antes de nada. La plantilla no trae clave y publica el servicio con un dominio HTTPS desde el primer momento: sin clave, cualquiera que conozca la dirección puede leer y borrar tus datos. Ve a Entorno, añade esta línea con tu clave, pulsa Guardar y después Implementar:
QDRANT__SERVICE__API_KEY=tu_clave_larga
Lo comprobamos así: con la clave puesta, una petición sin ella responde 401 y con la cabecera api-key responde 200.
- En Dominios verás el dominio automático, del tipo
https://demo-qdrant.xxxxx.easypanel.host, que apunta al puerto 6333 del contenedor (http://demo_qdrant:6333/). El certificado es automático. Si quieres tu propio dominio, crea un registro A hacia la IP del VPS y añádelo con Agregar dominio, con el mismo destino.
- En Almacenamiento comprueba que existe el volumen
storagemontado en/qdrant/storage. Ahí viven tus colecciones: sobreviven a reinicios y a nuevas implementaciones. Desde esa misma pantalla puedes crear copias del volumen con Crear copia de seguridad de volumen.
- Abre el panel web de Qdrant en
https://demo-qdrant.xxxxx.easypanel.host/dashboard. Te pedirá la clave en Set API Key: pégala y pulsa Apply.
- Entra en Console y crea una colección para vectores de 4 dimensiones comparados por coseno. Escribe estas dos líneas y pulsa RUN encima de ellas:
PUT collections/documentos
{"vectors": {"size": 4, "distance": "Cosine"}}
La respuesta debe ser "result": true.
- Inserta cuatro fragmentos de ejemplo, cada uno con su vector y su texto en el
payload:
PUT collections/documentos/points?wait=true
{"points": [
{"id": 1, "vector": [0.9, 0.1, 0.1, 0.0], "payload": {"texto": "Renovar un dominio .es"}},
{"id": 2, "vector": [0.8, 0.2, 0.1, 0.1], "payload": {"texto": "Transferir un dominio"}},
{"id": 3, "vector": [0.1, 0.9, 0.2, 0.0], "payload": {"texto": "Configurar el correo en el móvil"}},
{"id": 4, "vector": [0.0, 0.1, 0.9, 0.3], "payload": {"texto": "Copia de seguridad del VPS"}}
]}
- Haz la búsqueda por similitud: el vector de la «pregunta» se parece a los de dominios, así que deben salir esos dos.
POST collections/documentos/points/query
{"query": [0.85, 0.15, 0.1, 0.05], "limit": 2, "with_payload": true}
Devuelve «Renovar un dominio .es» y «Transferir un dominio», con una puntuación cercana a 1.
De la prueba a tu RAG
En un RAG real los vectores no se escriben a mano: los calcula un modelo de embeddings a partir de cada fragmento, y la colección se crea con la dimensión de ese modelo (por ejemplo 384 o 1536). Al preguntar, calculas el vector de la pregunta con el mismo modelo, buscas como en el paso 9 y pasas los textos recuperados al modelo de lenguaje que elijas.
Tu aplicación se conecta así:
- Si corre en el mismo proyecto de Easypanel, por la red interna:
http://demo_qdrant:6333. - Desde fuera, por el dominio HTTPS, siempre con la cabecera
api-key:
curl -H "api-key: tu_clave_larga" https://demo-qdrant.xxxxx.easypanel.host/collections
Los clientes oficiales de Qdrant (Python, JavaScript y otros) piden esos mismos dos datos: la URL y la clave.
Cómo comprobar que ha funcionado
Sin la cabecera api-key, https://demo-qdrant.xxxxx.easypanel.host/collections responde 401; con ella, 200 y la colección documentos. Y la búsqueda del paso 9 devuelve los dos textos de dominios.
Si algo falla
- El panel web no muestra tus colecciones: la clave de Set API Key no coincide con la de Entorno. Pulsa el icono de la llave arriba a la derecha y vuelve a pegarla.
- La API sigue respondiendo sin clave: guardaste la variable pero no pulsaste Implementar.
- La búsqueda da un error de dimensión: el vector de la consulta debe tener el mismo tamaño que la colección.
- Cualquier otra cosa: abre un ticket desde tu área de cliente (Cómo abrir un ticket de soporte y que se resuelva a la primera).