Qdrant：Rust 编写的开源向量数据库

为什么需要 Qdrant：从「近似搜索库」到「生产级向量数据库」

在 Qdrant 出现之前，工程团队做语义检索通常只有两类选择。一类是 FAISS、Annoy 这类近似最近邻（ANN，Approximate Nearest Neighbor，即不追求绝对精确、只求「足够接近」的近邻检索）算法库：检索快，但数据只存在于内存中，没有持久化、没有条件过滤、没有服务化 API，从「算出 Top-K」到「上线给业务调用」之间还隔着存储、并发、容灾一大堆自研工作。另一类是直接用 Elasticsearch 做语义扩展：倒排索引擅长关键词精确匹配，但在语义相似（同义改写、跨语言）上先天不足。两类方案都无法同时满足「语义检索 + 业务过滤 + 生产可用」三个条件。

Qdrant 把向量索引、payload 过滤、持久化存储、分片复制、监控指标打包成一个独立服务。payload 是附加在向量上的业务元数据（如用户 ID、类目、价格），Qdrant 允许在向量检索的同时按这些字段过滤，且过滤在索引内部完成（pre-filter），避免「先检索后过滤」导致的高分结果被丢弃。Rust 实现带来高并发与可控的内存占用；官方 SDK（Python、Go、TS/JS、Rust 等）屏蔽了 HTTP/gRPC 细节；API 在单机到集群的不同部署规模下保持一致。因此 Qdrant 常被选为 RAG 管道的默认向量存储。

与 LangChain 这类编排框架相比，Qdrant 只负责「存储 + 检索」这一层，职责单一、接口稳定；与 Milvus 相比，Qdrant 单机起步更轻、分布式组件更少；与 Pinecone 相比，它完全开源可自托管。它代表的是「检索与过滤并重」的技术路线，而不是「纯向量相似度」的简易包装。

安装与环境配置：3 步就绪

步骤一：Docker 方式（推荐）。拉取镜像并启动，容器暴露两个端口：6333 是 REST API，6334 是 gRPC。生产环境务必用 -v 挂载持久化卷，容器内数据目录为 /qdrant/storage，否则容器重建后数据丢失。启动后可访问 http://localhost:6333/dashboard 打开内置管理界面。

步骤二：二进制方式。适合没有 Docker 的生产服务器。从 GitHub Releases 下载对应平台的预编译压缩包，解压后目录内自带 config/config.yaml，直接执行 ./qdrant 即可，默认读取同目录配置。

步骤三：安装客户端并验证。Python 客户端是 qdrant-client 包；服务是否就绪用 GET /healthz 检查，返回 ok 即正常。

# 1. Docker 方式（推荐）docker run -d --name qdrant \  -p 6333:6333 -p 6334:6334 \  -v "$(pwd)/qdrant_storage:/qdrant/storage" \  qdrant/qdrant # 2. 二进制方式（Linux x86_64）curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-gnu.tar.gz -o qdrant.tar.gztar xzf qdrant.tar.gz && cd qdrant && ./qdrant # 3. 客户端安装与验证pip install qdrant-clientcurl http://localhost:6333/healthz

快速上手：10 分钟跑通「建库-写入-检索」

最小可用流程只有四步：连接客户端 → 创建 collection（集合，即一组向量的容器）→ upsert（写入或更新）带向量与 payload 的数据点 → search 检索。核心概念是：collection 在创建时就固定了向量维度（size）与距离度量（distance），之后不可修改，所以第一步必须先确定 embedding 模型的输出维度。

1. 创建 collection：在 Python 中指定 VectorParams(size=768, distance=Distance.COSINE)，768 要与你使用的 embedding 模型输出维度一致；文本语义检索默认用 Cosine（余弦相似度）。

2. 写入数据：upsert 每个点包含 id（唯一标识）、vector（浮点数组）、payload（业务元数据字典）。

3. 执行检索：search 传入查询向量、过滤条件与返回数量，返回结果按相似度降序。

4. 进阶技巧：在 search 的 query_filter 中按 payload 字段过滤，即可实现「先过滤再检索」的复合查询。

执行后你会看到 id=2 的结果排在前面，且只返回 category="ai" 的点，说明「向量排序 + payload 过滤」在同一次查询内完成。这就是 Qdrant 和纯检索库最直观的差别。

from qdrant_client import QdrantClientfrom qdrant_client.models import Distance, VectorParams, Filter, FieldCondition, MatchValue client = QdrantClient(host="localhost", port=6333) # 1. 创建 collection（维度与 embedding 模型输出对齐）client.create_collection(    collection_name="articles",    vectors_config=VectorParams(size=768, distance=Distance.COSINE),) # 2. 写入数据（向量 + 业务元数据）client.upsert(    collection_name="articles",    points=[        {"id": 1, "vector": [0.1] * 768, "payload": {"category": "tech", "views": 1200}},        {"id": 2, "vector": [0.2] * 768, "payload": {"category": "ai", "views": 3400}},    ],) # 3. 检索：语义相似 + 按 category 过滤hits = client.search(    collection_name="articles",    query_vector=[0.15] * 768,    query_filter=Filter(must=[FieldCondition(key="category", match=MatchValue(value="ai"))]),    limit=5,)for hit in hits:    print(hit.id, hit.score, hit.payload)  # score 为相似度分数，越大越相似

核心能力详解：5 大支柱

支柱一：HNSW 索引与多种距离度量。Qdrant 默认使用 HNSW（分层可导航小世界图，一种通过多层图结构做近似最近邻检索的索引），在召回率与查询延迟之间取得平衡，可通过 m、ef_construct、ef 三个参数调节「内存 vs 精度」。支持四种距离度量：Cosine（余弦，文本语义检索默认）、Dot（点积，适合已归一化向量与推荐打分）、Euclid（欧氏距离）、Manhattan（曼哈顿距离，用于低维特征或特殊业务距离）。距离度量在创建 collection 时选定，之后不可更改。

支柱二：payload 过滤与复合查询。每个向量可携带任意 JSON payload，Qdrant 为 payload 字段建立独立索引，支持数值范围、字符串匹配、标签集合、嵌套对象以及地理位置过滤（圆形、矩形、多边形）。过滤与向量检索在同一次查询内执行，是 pre-filter 而非后置过滤，因此不会因过滤截断而丢失高相关结果。

支柱三：量化与内存控制。标量量化（scalar quantization）把 float32 向量压为 int8，内存降约 4 倍；二进制量化（binary quantization）压到 1 bit，向量部分内存再降一个数量级。量化会损失召回率，可配合 oversampling（过采样，即检索时多取候选再重排）补偿。这一能力让千万级向量在单节点上运行成为现实。

支柱四：多向量与混合检索。支持 named vectors（一个点存多个命名向量，例如同时存标题向量与正文向量）。自 1.12 起支持全文稀疏向量（基于 BM25 的稀疏表示），可与稠密向量做混合检索，用 RRF（倒数排名融合，把多个检索结果按排名倒数加权合并）或加权和融合，同时兼顾语义相似与精确关键词匹配——这对 RAG 中「专有名词必须精确命中」的场景尤其关键。

支柱五：分布式与运维原生能力。collection 可拆分为多个分片（shard），每个分片配置多个副本；分片分发策略支持基于 payload 字段的 hash 与自定义 key。内置快照（snapshot）备份与恢复、集合别名、Prometheus /metrics 指标端点。最核心的特性是 API 不随部署规模变化：单机进程与多节点集群使用同一套接口，迁移成本低。

生产部署与监控：从上线到运维

方式一：Docker Compose 单机部署。这是大多数团队的第一站，但生产环境必须补三件事：挂载持久化卷（容器内 /qdrant/storage）、配置 restart 策略、限制容器资源。一个最小可用的 compose 配置如下，./qdrant_storage 会落在宿主机上，容器重建不丢数据。

方式二：Kubernetes / Helm 与 Qdrant Cloud。需要水平扩展时，官方 Helm chart 支持分片副本、持久卷声明与水平扩缩容；Qdrant Cloud 则提供全托管与混合云部署，把升级、备份、监控全部外包。选型依据很简单：团队有 7×24 运维能力的选自托管，没有则优先托管服务；日向量查询量在千万级以下，单机 + 量化通常已经够用。

可观测性。Qdrant 在 6333 端口暴露 /metrics，输出 Prometheus 格式指标（向量点数、分片状态、请求延迟直方图），接入 Prometheus 后可用 Grafana 展示；健康检查使用 GET /healthz 与 GET /livez；日志默认 JSON 格式便于采集。备份策略建议用快照 API 定期导出到对象存储，而不是直接拷贝数据目录。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>生产环境不挂载持久化卷：Docker 容器默认数据写在容器内层，重启或重建即全部丢失；务必挂载 /qdrant/storage，并对卷做独立备份。</li><li>向量维度与距离度量创建后不可修改：建 collection 时若 size 设错，只能删除重建并重灌数据；先确认 embedding 模型输出维度，再决定 384/768/1536 等取值。</li><li>升级版本前先做快照与恢复演练：Qdrant 快照在同版本恢复最可靠，跨大版本恢复前必须在测试环境验证，降级方向尤其危险。</li></ul>

services:  qdrant:    image: qdrant/qdrant:latest    ports:      - "6333:6333"      - "6334:6334"    volumes:      - ./qdrant_storage:/qdrant/storage    restart: unless-stopped

版本迭代

Qdrant 于 2021 年开源，2022 年在 0.x 阶段快速迭代，2023 年 7 月发布 1.0 稳定版，此后以约每月一版的节奏演进。主线清晰：从「可用的向量检索服务」→「过滤与多向量能力」→「量化与内存优化」→「稀疏向量与混合检索」，每次大版本都直接扩大可用场景边界。（截至训练数据，可能已有更新版本）

AI 应用场景

常见误区

面试题

参考来源

• webpageQdrant 官网产品介绍、功能亮点与文档入口
• webpageGitHub 仓库源码、Release 记录与 Issue 讨论
• webpage官方示例仓库RAG、推荐、混合检索等落地示例