Conectar Qdrant

Qdrant es una base vectorial que se ejecuta como servidor independiente. Utilícela si los datos superan decenas de miles de elementos o si quiere separarlos del servidor de SpaceBuilder.

Los archivos y el texto original permanecen en SpaceBuilder. Qdrant solo guarda los vectores y la información mínima necesaria para buscar.

Antes de comenzar

Permisos: administrador de Workspace y autorización para administrar la conexión
El servidor de SpaceBuilder debe acceder a los endpoints REST y gRPC.
Compruebe las dimensiones de salida del modelo de embeddings.

Instalar Qdrant

Necesita un servidor Qdrant accesible. Si ya existe, vaya a Configurar la conexión. El método más sencillo es Docker en Linux.

Preparación

Elemento	Descripción
Servidor	Puede ser el mismo equipo o uno separado. Si comparte equipo, reserve memoria para ambos servicios.
Memoria	Fórmula recomendada: vectores × dimensiones × 4 bytes × 1,5. Para `bge-m3` de 1024 dimensiones, unos 0,6 GB por 100 000 vectores y 6 GB por un millón.
Disco	Reserve entre dos y tres veces la memoria, pues guarda vectores y texto de fragmentos.
Puertos	`6333` para REST y `6334` para gRPC. SetFN prefiere gRPC y recurre a REST si falla.

Conecte siempre una carpeta persistente. El ejemplo guarda en /data/qdrant, reinicia automáticamente y fija la versión mediante QDRANT_VERSION. Sustituya la versión por una validada de Qdrant Releases.

QDRANT_VERSION=v1.19.1
sudo mkdir -p /data/qdrant

docker run -d --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -p 6334:6334 \
  -v /data/qdrant:/qdrant/storage \
  qdrant/qdrant:${QDRANT_VERSION}

En otro servidor o una red compartida, active una clave API larga y difícil de adivinar.

QDRANT_VERSION=v1.19.1
docker run -d --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -p 6334:6334 \
  -v /data/qdrant:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY='<clave API>' \
  qdrant/qdrant:${QDRANT_VERSION}

Comprobar la instalación

curl http://localhost:6333/collections

Una respuesta con "status":"ok" confirma el servicio. Con clave API, utilice curl -H 'api-key: <clave API>' http://localhost:6333/collections. Abra http://<dirección del servidor Qdrant>:6333/dashboard para ver el panel.

Consejos operativos

Actualización: avance versiones menores de una en una según la guía oficial, por ejemplo, de 1.12 a 1.13. Cambie QDRANT_VERSION, ejecute docker pull qdrant/qdrant:${QDRANT_VERSION} y vuelva a crear el contenedor con el mismo comando; /data/qdrant conserva los datos.
Copia de seguridad: detenga el contenedor y copie /data/qdrant, o use la API de snapshots. Los vectores también pueden reconstruirse con Sync Existing Embeddings de SpaceBuilder.
Cortafuegos: permita los puertos 6333 y 6334 solo desde SpaceBuilder. Para HTTPS, coloque un proxy inverso delante de Qdrant.

Configurar la conexión

Introduzca los valores en Vector DB Setup de Almacenamiento de conocimiento y seleccione Save.

Campo	Valor	Descripción
`Driver`	`Qdrant`	Utiliza el servidor externo.
`REST endpoint`	`http://<dirección del servidor Qdrant>:6333`	Si queda vacío, usa `http://localhost:6333`.
`gRPC endpoint`	`http://<dirección del servidor Qdrant>:6334`	Se prefiere para buscar y guardar. Si queda vacío se deduce de REST y, si no conecta, se utiliza REST.
`Collection`	Nombre exclusivo de esta instancia	Utilice el nombre recomendado `setfn_knowledge_...`.
`API key`	Clave configurada en Qdrant	Déjela vacía si no hay autenticación. Se muestra enmascarada; vacío al guardar la elimina.
`Vector dimensions`	Salida del modelo	`bge-m3` utiliza `1024`; los modelos conocidos se completan automáticamente.

Qdrant no muestra Data Path porque todo se guarda en su servidor. Al guardar, el planificador comprueba el cambio e inicia automáticamente una reindexación completa si hace falta.

La colección se crea automáticamente

SpaceBuilder crea la colección al guardar el primer dato y añade los índices de filtros necesarios.

Elemento	Valor
Formato	Un único vector dense sin nombre
Tamaño	Dimensiones configuradas
Distancia	Cosine
Índices de filtro	Instancia, generación, espacio, propietario y ruta original

Antes de la primera indexación, Collection configuration muestra Not created yet · it is created automatically on first indexing. No es un error.

Precauciones al crearla manualmente

Las colecciones Simple Hybrid Search o con named vectors no son compatibles. Para crear una manualmente, seleccione Create New Collection, abra Console, ejecute esta solicitud y ajuste size.

PUT /collections/setfn_knowledge_example
{
  "vectors": { "size": 1024, "distance": "Cosine" }
}

Consultar los datos guardados

Consulte estos valores en Vector DB Overview.

Campo	Significado
`Connection`	Si el servidor es accesible
`Stored vectors`	Vectores de esta instancia; excluye otras instancias de la misma colección
`Total Collections`	Total del servidor Qdrant
`Collection configuration`	Compatibilidad de dimensiones y distancia

Un vector representa un fragmento. Un documento se divide por secciones, páginas o filas y después en segmentos de unas 700–1000 letras coreanas, por lo que suele haber muchos más vectores que documentos.

Para contar vectores por archivo en la consola:

POST /collections/setfn_knowledge_example/facet
{ "key": "source_path", "limit": 50 }

Para ver algunos fragmentos:

POST /collections/setfn_knowledge_example/points/scroll
{ "limit": 10, "with_payload": ["source_path", "text"], "with_vector": false }

Varias instancias en un mismo Qdrant

Un nombre de colección distinto por instancia separa completamente los datos. Si conserva knowledge_vectors, se muestra una advertencia y el nombre recomendado.

Aunque compartan colección, una clave de aislamiento limita búsquedas y eliminaciones a cada instancia. Para copias, capacidad y eliminación independientes, utilice colecciones separadas. También se muestra una advertencia si otro proyecto activo del mismo servidor comparte la colección.

Documentos relacionados

← Documento anterior

Operar el almacenamiento de conocimiento

Documento siguiente →

Preparar un servidor Qdrant