Qdrant 是用 Rust 编写的开源向量数据库，适用于在 PostgreSQL 之外运行大规模检索的团队。它可支撑语义搜索、推荐系统、图像搜索，以及现代 RAG 技术栈中的检索环节。如果你希望对嵌入向量进行条件过滤，同时避免查询显著变慢，Qdrant 值得了解。
本文是 Qdrant 系列的起点，介绍基本概念、内部架构、与 pgvector 和 Milvus 的选型比较、2026 年的安全与量化能力，以及实际部署的学习路线。系列配套代码保存在 c4geeks/qdrant 仓库，原文示例在 Proxmox 虚拟机及相关 GPU 实例上测试。准确的行为定义应以 Qdrant 官方文档为准，qdrant/qdrant 仓库提供源码与发行版本。
为什么团队选择 Qdrant
当向量负载超出概念验证阶段，Qdrant 的三个特点尤其有用：相似度搜索叠加过滤条件后仍能保持较低延迟；量化可将内存需求降低到原来的约 1/4～1/40；运维范围相对集中，一名工程师也能维护生产系统。
项目于 2021 年首次发布，采用 Apache 2.0 许可证，可自行部署。官方 Docker 镜像、Helm Chart 和托管云使用相同的数据库程序，从笔记本演示迁移到 Kubernetes 集群无需学习另一套产品。
- 支持过滤的 HNSW 搜索：索引遍历会考虑过滤条件。例如“与 X 相似、属于分类 Y、价格低于 Z”的查询，在数百万个点上也可实现个位数毫秒级延迟，具体取决于负载和配置。
- 量化能力：标量量化以少量召回损失换取约 4 倍内存节省；乘积量化可达 8～64 倍；二值量化约节省 32 倍内存，借助 SIMD 的 popcount 运算，搜索路径最高可加速约 40 倍。这些是原文给出的能力范围，并非所有数据集的固定收益。
- 稠密与稀疏混合检索：命名向量和稀疏向量 API 可在单次查询中结合语义相似度与 BM25 风格的关键词检索。
- 基于 Raft 的集群管理：三节点集群支持分片、副本以及节点故障后的协调与恢复。
- 默认行为明确：默认 Docker 启动方式没有认证、可以直接访问；生产安全配置需要主动启用。
什么是向量数据库
向量数据库存储称为 embedding（嵌入向量）的高维数值数组，并对其执行最近邻查询。CLIP、BGE、OpenAI text-embedding-3 等模型可将文本、图像或音频转换为嵌入；语义接近的输入通常在向量空间中距离较近。数据库本身不理解语义，但能计算距离，从而实现语义搜索、推荐、去重、异常检测和 RAG 检索。向量搜索与传统搜索的差别，在于稠密检索更适合处理表达模糊的语义意图。
核心概念速览
下列概念贯穿整个系列，先理解它们可以减少后续查阅文档的时间。
| 概念 | 含义 |
|---|---|
| Collection（集合） | 顶层命名空间，包含数据点、HNSW 索引和载荷结构，大致对应 SQL 中的表。 |
| Point（数据点） | 一条记录，包括 ID、一个或多个向量，以及 JSON 元数据载荷。 |
| Vector（向量） | 搜索引擎比较的数值数组。一个点可拥有多个命名向量，例如同时保存稠密向量和稀疏向量。 |
| Payload（载荷） | 附加在数据点上的任意 JSON 元数据，可过滤、可建索引，也可随搜索结果返回。 |
| Shard 与 replica（分片与副本） | 集群将集合拆为分片；分片可在不同节点上拥有多个副本，以提供容错。 |
Qdrant 的内部工作方式
搜索请求通过 6333 端口的 REST 或 6334 端口的 gRPC 进入系统。集合层将查询分派给相关 segment（段），各段通过 HNSW 索引找到候选近邻，载荷过滤条件排除不符合元数据约束的候选，随后合并并返回得分最高的数据点及其载荷。
写入首先进入 WAL（预写日志）以保证持久性，再写入活动段中的可变数据结构。后台优化器整理数据、生成或合并段、构建 HNSW 图，并按集合设置进行量化。集群中，写入会复制到目标分片的副本，并根据写入一致性配置等待确认。
- HNSW 索引：全称为 Hierarchical Navigable Small World，即分层可导航小世界图。它构建分层近邻图以加速近似最近邻查询；Qdrant 的变体考虑过滤条件，可处理
must、should、must_not等约束。 - 段与优化器：集合由多个段组成。优化器在后台合并小段、为新数据建索引并应用量化。
- WAL：保证 upsert 在崩溃后的可恢复性，是关键写入路径上需要进行持久化同步的部分。
- 快照：可为单个集合或完整存储生成归档，通过上传、URL 拉取或启动选项恢复。自 v1.10 起，可直接将快照写入兼容 S3 的对象存储。
- Raft 共识：集群模式使用 Raft 管理拓扑和集合元数据。数据点写入本身直接在分片副本间复制，不通过 Raft 日志，以提高吞吐量。
60 秒体验 Qdrant
安装 Docker 后，可以快速启动 Qdrant 并打开 Web UI。这只是体验环境，生产部署还需要后续安全配置。
docker run -d --name qdrant \
-p 6333:6333 -p 6334:6334 \
-v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
qdrant/qdrant在浏览器中访问本机 6333 端口的 /dashboard，即可看到内置 Web UI、Console、Collections 面板和交互教程。REST API 使用相同端口，gRPC 使用 6334；持久化卷使数据在容器重启后保留。
实际部署可先阅读本系列的 Ubuntu 安装教程，其中包含 Docker Compose、原生 deb 包、UFW 和 systemd；Rocky Linux 10 与 Debian 13 另有对应篇章。
部署方式比较
根据运维能力和数据驻留要求选择部署方式。
| 方式 | 适用场景 | 投入 |
|---|---|---|
| Docker | 单节点演示、开发笔记本、小型生产服务器 | 数分钟 |
| 原生 deb / rpm 包 | 使用 systemd、SELinux 且不运行 Docker 的加固服务器 | 数十分钟 |
| Kubernetes Helm | 需要高可用、Ingress 和 GitOps 的自行部署生产环境 | 首次配置数小时 |
| Qdrant Cloud 托管服务 | 不希望自行维护数据库的团队 | 无需自行部署数据库 |
| GPU 镜像 | 数千万向量及以上、索引构建负载较重的环境 | 与 Docker 类似，另需驱动 |
Docker 镜像与原生包使用相同程序、配置结构和端口；迁移时主要需要移动存储卷并重启。Helm Chart 为每个 Pod 配置 StatefulSet 和 PVC。数据库数据目录需要支持 POSIX 语义的块存储，不能直接用 NFS 或对象存储替代文件系统层的数据盘。
托管云与自行部署如何选择
缺少平台工程师的小团队可先评估 Qdrant Cloud；已有 Kubernetes 运维经验的团队则可评估自行部署。可以将每月托管费用与虚拟机、集群及工程师维护时间比较。原文给出的粗略参考，是每季度投入约一个工程师工作日所对应的运维成本。
| 维度 | Qdrant Cloud | 自行部署 |
|---|---|---|
| 运维成本 | 固定周期账单，无需自行值守数据库 | 虚拟机或集群费用，加工程师时间 |
| 数据驻留 | AWS、GCP、Azure 的服务区域，不是本地机房 | 可运行 Linux 的环境 |
| 升级 | 由服务方按维护窗口管理 | 自行负责，可用自动化重复执行 |
| 备份 | 内置，无需自己搭建 S3 流程 | 快照写入自有兼容 S3 存储 |
| SLA | 付费方案提供合同约定 | 取决于自己的运维保障 |
| 定制 | 限于服务提供的配置选项 | 可控制配置、进程运行环境与网络 |
Hybrid Cloud 介于两者之间：控制平面由 Qdrant Cloud 运行，数据平面位于自己的 Kubernetes 集群，使向量留在自有网络中，同时使用托管运维能力。
安全模型：API 密钥、JWT 与 TLS
默认情况下，Qdrant 监听全部接口且没有认证。这适合本地体验，不适合直接暴露在公网 VPS 上。生产安全主要分为三层：
- 静态 API 密钥：在
config.yaml中设置service.api_key，或传入环境变量QDRANT__SERVICE__API_KEY。之后请求必须携带api-key请求头，同时使用 TLS 防止密钥明文传输。 - JWT 与 RBAC：在静态密钥基础上启用
service.jwt_rbac。令牌使用 API 密钥作为 HMAC 签名密钥，可限制为只读、指定集合或指定载荷范围等权限。这样可为仪表盘发放受限令牌，而不暴露主密钥。 - TLS：可在前置 Nginx、Caddy 终止 TLS，也可在 Qdrant 中配置
tls.cert与tls.key。经 Nginx 代理 gRPC 时，还需正确配置 HTTP/2 与 TLS。
本系列的安全篇给出 API 密钥、TLS 和 Nginx 的完整配置；更细粒度的权限主题包括 JWT 与 RBAC。
用数字理解性能与量化
量化决定搜索引擎的内存消耗，也可能影响距离比较速度。不同模式在召回率和资源成本之间作出取舍，可按集合选择。
| 模式 | 内存节省 | 速度影响 | 召回影响 |
|---|---|---|---|
| 无量化，float32 | 基准 1 倍 | 基准 | 参考值 |
| 标量量化，int8 | 约 4 倍 | 通常略快，int8 计算成本较低 | 原文给出的典型损失约 1% |
| 乘积量化 | 可配置为 8～64 倍 | 与子向量数量等配置有关 | 压缩越强，通常损失越大 |
| 二值量化 | 约 32 倍 | XOR 与 popcount 路径最高约快 40 倍 | 原文给出的损失约 5%～10%，可重评分改善 |
常见模式是非对称量化：存储向量做二值量化，查询向量保持浮点精度。第一阶段得到粗略 top-k，再用原始向量重评分，恢复大部分召回。原文的性能调优篇以同一组一百万向量比较三种模式。
HNSW 的三个参数也值得了解：m 控制图连接度，ef_construct 影响构建阶段精度，ef 影响单次查询精度。多数负载可从默认值开始；确定召回目标并测得基准后，再调整参数。
与其他方案的选型比较
不存在适合所有场景的向量数据库，应结合现有技术栈、规模和团队能力判断。
- 已经运行 PostgreSQL，向量少于一千万：可先考虑 pgvector，减少独立组件，并直接与现有表关联。原文认为 pgvector 0.9 已缩小部分速度差距，并提供 PostgreSQL 17 安装教程。
- 需要高速条件过滤、希望自行部署，且已经超出 pgvector 的适用规模：可考虑 Qdrant，其过滤式 HNSW 和相对集中的运维范围是主要优势。
- 十亿级向量：先评估 Milvus，其设计重点包括大规模分片和分区。
- 希望开箱即用集成文本、图像、生成式模块：可评估 Weaviate，但需要维护更大的系统。
- 不希望维护向量数据库：比较 Qdrant Cloud 与 Pinecone 的价格、区域及服务能力。
原文另有 Qdrant、pgvector、Milvus、Weaviate 的基准与决策矩阵，包含延迟、每秒请求数和召回率。
日常运维：快照、监控与扩容
数据库上线后的维护同样重要。有些能力默认可用，有些需要主动配置。
- 快照：一次 REST 调用即可创建集合或全存储快照。自 v1.10 起可直接写入兼容 S3 的存储，便于通过 systemd 定时执行。原文所述 S3 恢复仍需经过 HTTP 上传步骤，备份篇会具体说明。
- 监控：
/metrics提供 Prometheus 与 OpenMetrics 指标，/sys_metrics提供系统指标。可导入相应 Grafana 仪表盘；本系列监控篇提供 Prometheus 配置与配套仪表盘 JSON。 - 纵向扩容：默认配置中 HNSW 图和未量化向量主要消耗内存。先评估量化或
on_disk: true，通常比直接增加服务器规格更经济。 - 横向扩容：三节点 Raft 集群是常见起点，可进行分片、复制和节点故障恢复。写入能否在故障时继续成功，还取决于副本和一致性配置。集群篇介绍引导、故障演练与分片迁移。
- GPU 加速：自 v1.13 起，GPU 镜像可加速 HNSW 索引构建；它不是查询加速器，主要适合较大的建索引任务。原文 GPU 专题比较 RTX 4090 的使用成本与 CPU 构建时间。
Qdrant 学习路线
系列按多数团队的采用过程安排：先了解基础概念，再按操作系统选择安装方式，随后学习当前所需的运维主题。下面保留原文规划，其中部分主题是后续计划，不代表都已出现在当前 14 篇目录中。
按操作系统安装
- Ubuntu 26.04 / 24.04 LTS：Docker 与原生 deb 两种方式。
- Rocky Linux 10 / AlmaLinux 10：包含 SELinux 上下文和 firewalld。
- Debian 13 / 12：Docker Compose 与 journald 日志转发。
核心操作
- Web UI：Dashboard、Console、Graph 与交互教程。
- 创建、配置和管理集合，包括命名向量与稀疏向量。
- REST 和 gRPC，包含 curl、Python 与 Go 示例。
- 过滤、载荷索引，以及稠密与稀疏混合检索。
生产运行
- API 密钥、TLS 和 Nginx 反向代理。
- JWT 与 RBAC 细粒度权限。
- 快照、备份与 S3 恢复。
- Prometheus 与 Grafana 监控。
扩展与优化
- 三节点分布式集群。
- Helm 部署 Kubernetes 集群。
- 量化、HNSW 和索引调优。
- GPU 索引构建加速。
构建应用
- 使用 Qdrant、Ollama、LangChain 构建本地 RAG，并与 Ollama、pgvector 方案比较。
- 使用 Qdrant 与 LlamaIndex 进行 PDF 问答。
- 使用 Qdrant 与 CLIP 实现图像搜索。
- 使用 Qdrant 与 FastAPI 构建语义搜索 API。
- 使用 Qdrant 与 n8n 构建无代码向量工作流。
比较与迁移
- Qdrant、pgvector、Milvus、Weaviate 的基准与选择。
- 从 Pinecone 迁移并进行验证。
- Qdrant 命令与 API 速查表。
原文说明后续篇章会陆续补充，总览会随之更新，可将其作为系列索引。
小结
对于 PostgreSQL 之外的自行部署向量检索，Qdrant 提供了相对集中的架构和运维能力，量化也有助于控制数千万向量场景的内存需求。初次评估时，可以先运行前面的 Docker 示例，体验 Web UI，再阅读对应操作系统的安装篇和安全篇，其余内容在此基础上展开。
系列配套代码保存在 c4geeks/qdrant 仓库。若命令无法在干净虚拟机上复现，可向原项目报告问题。
