SetFN
SetFNDocs2026年10月27日

连接 Qdrant

Qdrant 是作为单独服务器运行的向量数据库。当文档较多、搜索数据超过数万条，或希望将 AI 搜索数据与 SpaceBuilder 服务器分开运营时使用。

即使使用 Qdrant，原始文件和文档文本仍保留在 SpaceBuilder 中。Qdrant 中只存储搜索所需的向量和最少量的信息。

开始之前

  • 所需权限：Workspace 管理员，以及管理 Qdrant 连接信息的权限
  • SpaceBuilder 服务器必须能够访问 Qdrant 的 REST 和 gRPC 端点。
  • 确认嵌入模型的输出维度。

安装 Qdrant

需要一个 SpaceBuilder 服务器能够访问的 Qdrant 服务器。如果已有正在运行的 Qdrant，请跳过本节，直接前往连接设置。

使用 Docker 安装 Qdrant 最为简单。以下步骤假定 Linux 服务器上已安装 Docker。

准备

项目内容
服务器可以与 SpaceBuilder 放在同一台服务器上，也可以使用单独的服务器。如果在同一台服务器上，会与 SpaceBuilder 共享内存，请预留充足的余量。
内存为了保证搜索速度，向量会加载到内存中。按 Qdrant 推荐的计算公式（向量数 × 维度 × 4 字节 × 1.5），以 bge-m3（1024 维）为准，10 万个向量约需 0.6GB，100 万个向量约需 6GB。
磁盘由于向量和文档片段文本会一起存储，请预留内存需求量的 2～3 倍。
端口6333（REST API）和 6334（gRPC）。SpaceBuilder 优先使用 gRPC，无法连接时切换为 REST。

运行

请务必挂载存储文件夹，以便删除容器后数据仍然保留。以下示例将数据保存在 /data/qdrant，并设置为服务器重启后也会自动重新启动。

镜像版本通过 QDRANT_VERSION 变量固定。如果不指定版本，会安装 latest，在重新创建容器时可能会意外升级版本。以下版本是编写本文档时的示例。实际安装时，请在 Qdrant 发布页面中换成组织已验证的版本。

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}

如果与 SpaceBuilder 运行在不同的服务器上，或处于多人可以访问的网络中，请同时启用 API 密钥。密钥应设置为较长且难以猜测的值。

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='<API 密钥>' \
  qdrant/qdrant:${QDRANT_VERSION}

验证安装

curl http://localhost:6333/collections

如果返回包含 "status":"ok" 的响应，则表示正常。如果启用了 API 密钥，需要像 curl -H 'api-key: <API 密钥>' http://localhost:6333/collections 这样加上 api-key 标头才会有响应。

在浏览器中打开 http://<Qdrant 服务器地址>:6333/dashboard，可以看到用于查看集合和已存储数据的仪表板。

运维提示

  • 更新：请按照 Qdrant 官方升级指南，逐级升级次版本（例如：1.12 → 1.13）。将 QDRANT_VERSION 改为下一个版本，用 docker pull qdrant/qdrant:${QDRANT_VERSION} 拉取镜像后，删除容器并用相同的命令重新运行。数据会保留在 /data/qdrant 中。
  • 备份：停止容器后整体复制 /data/qdrant 文件夹，或使用 Qdrant 的快照 API。不过，向量是可以从原始文件重新生成的派生数据，即使没有备份，也可以通过 SpaceBuilder 的 同步已有嵌入 重新填充向量数据库。
  • 防火墙：请限制为只有 SpaceBuilder 服务器可以访问 6333 和 6334 端口。如果需要通过 HTTPS 访问，建议在 Qdrant 前面部署反向代理。

连接设置

在知识存储页面的 向量数据库设置 中按如下方式输入并保存。

项目输入值说明
驱动程序Qdrant使用外部 Qdrant 服务器。
REST 端点http://<Qdrant 服务器地址>:6333Qdrant 的 REST API 地址。留空时使用 http://localhost:6333。
gRPC 端点（推荐）http://<Qdrant 服务器地址>:6334搜索和向量存储优先使用。留空时会根据 REST 地址自动推断，无法连接时切换为 REST。
集合此实例（当前 SpaceBuilder）专用的名称建议使用页面上显示的建议名称（setfn_knowledge_...）。
API 密钥在 Qdrant 中设置的 API 密钥未启用认证时留空。已保存的值以掩码显示，不更改则保持原样。清空后保存即删除。
向量维度嵌入模型的输出维度bge-m3 为 1024。选择模型后，已知模型会自动填入。

Qdrant 属于服务型存储，因此不会显示 数据路径 输入框。数据全部存储在 Qdrant 服务器上。

保存后，索引调度器会立即检查新设置，并在需要时自动开始对全部原始文件重新索引。无需另外执行同步。

集合会自动创建

无需在 Qdrant 仪表板中预先创建集合。SpaceBuilder 在存储第一条搜索数据时，会以设置的名称创建集合，并同时创建搜索过滤所需的索引。

自动创建项目值
向量格式无名称的单一向量（dense）
向量大小设置的向量维度
距离计算Cosine
过滤索引实例、世代、空间、所有者、原始路径

首次索引之前，向量数据库概览 的 集合配置 中会显示 尚未创建 · 首次索引时自动创建。这不是错误，等待索引开始即可。

手动创建集合时的注意事项

在 Qdrant 仪表板的 Create New Collection 页面中，使用 Simple Hybrid Search 或带名称的向量（named vector）创建的集合与 SpaceBuilder 不兼容。如果指定了这类集合，集合配置 会显示 集合配置需要检查，并且索引会在存储阶段失败。

如果必须手动创建集合，请在仪表板的 Console 中执行以下请求。size 必须与设置的向量维度相同。

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

查看已存储的数据

在 向量数据库概览 中查看 Qdrant 的状态。

项目含义
连接状态是否能够访问 Qdrant 服务器
已存储的向量数此实例存储的向量数。不包含使用同一集合的其他实例的数据。
集合数Qdrant 服务器上的全部集合数。也包含 SpaceBuilder 创建之外的集合。
集合配置所设置集合的维度和距离计算方式是否与 SpaceBuilder 一致

1 个向量对应 1 个文档片段（块）。文档会根据格式先按章节、页或行拆分，再按以韩文计约 700～1,000 字的大小拆分后存储。因此向量数远多于文档数是正常的。

在 Qdrant 仪表板的 Console 中可以查看实际存储的内容。

查看每个文件的向量数：

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

查看部分已存储的文档片段：

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

多个实例共用一个 Qdrant 时

如果每个实例使用不同的集合名称，数据会完全分离。如果直接使用默认集合名称（knowledge_vectors），页面会显示警告，并给出此实例的建议名称。

即使共用同一个集合，新存储的向量也会带有实例隔离键，搜索和删除只在各实例自己的数据范围内进行。不过，如果要按实例分别进行备份、容量管理和删除，拆分集合更为安全。

如果同一台服务器上正在运行的其他 SpaceBuilder 项目使用了相同的集合，设置页面会显示警告。

相关文档