Qdrant 向量数据库手册

适用版本：v1.20.0（2026-10-22，Latest，核实于 2026-11） 许可与形态：Apache 2.0（自托管）／Qdrant Cloud、Private Cloud 商业形态；单机服务 / 分布式集群 / 全托管 一句话定位：以 Rust 实现的专用向量数据库，用 point = id + vector + payload 组织数据，向量检索与 payload 标量过滤在同一查询里完成。 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

Qdrant 是面向向量相似度检索的专用数据库。每条记录抽象成 point：一个 id、一个（或一组）vector、以及 JSON 风格的 payload（标量字段）。检索时既能按向量取近邻，又能用 payload 条件过滤，两者在一次 query_points 里完成。对外暴露三个面（官方资料确认）：

1.2 与同类产品的本质差别

1.3 适合 / 不适合

1.4 规模参考量级（经验值，非官方承诺）

1.5 在 RAG / 推荐 / 以图搜图链路中的位置

Qdrant 处在召回层：文档/物品/图片经 embedding 得到向量，连同 payload（分类、时间、租户、来源等）写入集合；查询用 query_points 取近邻并用 query_filter 过滤，返回 top-k 候选，再交给重排或 LLM 拼 context。重排与融合 API 以官方文档为准、实测为准。

2. 版本、许可与官方入口

2.1 版本状态表（2026-11）

避坑：开源 Latest 与 Private Cloud 验证版本不是同一节奏线，私有云选型以对应渠道 changelog 为准，别直接套主线版本号。

2.2 许可证与商业版边界

自托管为 Apache 2.0；Qdrant Cloud / Private Cloud 为商业形态，功能与计费以官方为准。企业特性、托管版专属能力与价格未查到官方明确说明，本手册不列举具体价格，请以官网报价为准；许可变更风险以官方 LICENSE 与当次发版说明为准。

2.3 官方 URL 表

2.4 版本识别

docker images | grep qdrant/qdrant          # 已拉取镜像 tag
pip show qdrant-client                       # 客户端版本
curl -s http://localhost:6333/healthz        # 存活探测
curl -s http://localhost:6333/metrics        # 指标端点（可用 ?per_collection=true）

服务端精确版本字段以 /metrics 或官方版本入口实际返回为准。

2.5 近两年重要变更与弃用提醒

版本差异：client.search() 的所有变体已废弃，当前统一用 client.query_points()，详见第 5、9 章。

版本差异：v1.20 起配置 API key 时 service.enforce_internal_auth 默认改为 true，多节点内网通信可能受影响，升级时需核对配置。

版本差异：v1.20 新增 BM25 全文打分、nested payload 索引、match: {substring}、公式查询，以及 turbo8 / turbo16 向量类型。

3. 安装与启动

3.1 方式一：Docker 单机

docker run -p 6333:6333 -p 6334:6334 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant

前置：Docker 可用。数据持久化到宿主机 ./qdrant_storage，对应容器内 /qdrant/storage。

3.2 方式二：Helm 部署到 Kubernetes

helm repo add qdrant https://qdrant.to/helm && helm install qdrant qdrant/qdrant

前置：Kubernetes 集群与 Helm 3。

3.3 方式三：Python 客户端

pip install qdrant-client

连服务端用 QdrantClient(url="http://localhost:6333")；本地无服务可用 QdrantClient(":memory:") 做进程内测试。

3.4 目录与端口表

3.5 健康检查与连通性验证

curl -s http://localhost:6333/healthz        # 存活
curl -s http://localhost:6333/readyz         # 就绪
curl -s http://localhost:6333/livez          # 存活
curl -s "http://localhost:6333/metrics?per_collection=true"   # 指标

浏览器打开 http://localhost:6333/dashboard 进内置 Web UI；客户端连通性用第 5 章脚本验证。防火墙放行等基础操作见根目录运维手册。

3.6 生产最小配置建议

4. 核心概念与数据模型

4.1 术语对照表

4.2 数据模型层级

Collection（vectors_config 定义向量维度与度量）
    └── Point = id + vector + payload（任意键值）
            ├── 稠密 / 稀疏 / 多命名向量（通用概念，以官方文档为准）
            └── payload 字段可被索引用于过滤

create_collection 用 VectorParams(size=..., distance=...) 声明向量维度与度量；写入用 PointStruct(id=..., vector=..., payload={...})。

4.3 字段 / 向量类型与距离度量

未核实（重要）：距离度量完整枚举（例如是否含 COSINE / EUCLID / MANHATTAN 等及其确切常量名）未查到官方明确说明。本手册只把 Distance.DOT 当确定可用度量，其余以官方文档为准，不写成确定事实；可确认稀疏向量仅用 dot-product。

Distance.DOT 为点积，通常点积越大越相似；其余度量方向以官方文档与实测为准。

4.4 索引类型与关键参数

4.5 生命周期与一致性模型

upsert 支持 wait=True，通常表示等待写入对检索可见后再返回；不待 wait 时可能异步可见。索引构建是否后台异步、是否需显式优化、分布式副本一致性语义，未查到官方明确说明，以官方文档与实测为准。

5. 快速上手：完整 CRUD 示例

5.1 完整可运行 Python 示例（基于官方 Quickstart）

from qdrant_client import QdrantClient
from qdrant_client.models import (
    Distance,
    VectorParams,
    PointStruct,
    Filter,
    FieldCondition,
    MatchValue,
)

# 连接：服务端用 url=；本地无服务可用 QdrantClient(":memory:")
client = QdrantClient(url="http://localhost:6333")

# 建集合：示例用 4 维小向量，实际常见 768 / 1024 / 1536
# distance 用官方资料确认的 Distance.DOT；完整距离枚举以官方文档为准
client.create_collection(
    collection_name="test_collection",
    vectors_config=VectorParams(size=4, distance=Distance.DOT),
)

# 插入（写入）：wait=True 等待写入可见
client.upsert(
    collection_name="test_collection",
    wait=True,
    points=[
        PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Berlin"}),
        PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={"city": "London"}),
        PointStruct(id=3, vector=[0.36, 0.55, 0.47, 0.94], payload={"city": "Berlin"}),
    ],
)

query_vec = [0.2, 0.1, 0.9, 0.7]

# 1) 纯相似度检索
res = client.query_points(
    collection_name="test_collection",
    query=query_vec,
    with_payload=True,
    limit=3,
).points
print(res)

# 2) 带标量过滤检索：只取 city == "London"
res2 = client.query_points(
    collection_name="test_collection",
    query=query_vec,
    query_filter=Filter(
        must=[
            FieldCondition(key="city", match=MatchValue(value="London"))
        ]
    ),
    with_payload=True,
    limit=3,
).points
print(res2)

# 3) 更新：upsert 对同一 id 覆盖写（如改 city）
client.upsert(
    collection_name="test_collection",
    wait=True,
    points=[
        PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Paris"}),
    ],
)

避坑：旧教程会写成 client.search(collection_name=..., query_vector=..., query_filter=...) 及其各种变体。search() 的所有变体已废弃，当前统一用 client.query_points(..., query=..., query_filter=Filter(must=[...]))，并从 .points 取结果。完整对照见第 9 章。

5.2 输出怎么读

.points 通常是一组命中点，每点常见字段如下（逐字段细节以 SDK 实际输出为准）：

5.3 更新 / 删除 / 清理（经验性说明）

• 更新：官方 Quickstart 已给出 upsert，对同一 id 再写一次即覆盖（见 5.1 第 3 步），为官方资料确认写法。
• 删除 / 清理：Quickstart 未逐字给出删除点、删除集合的方法名。按事实优先原则，不在可运行示例里编造这些调用；经验上这类客户端通常具备按 id / 过滤删除点、删除整个集合的能力，方法名与参数以 qdrant-client 官方文档为准、实测为准。

⚠️ 危险：删除集合或批量删点不可逆，生产前必须核对集合名、先备份、低峰操作。

5.4 REST / cURL 等价示例（仅健康与指标探测）

curl -s http://localhost:6333/healthz
curl -s http://localhost:6333/readyz
curl -s "http://localhost:6333/metrics?per_collection=true"

6. 索引与检索进阶

6.1 索引参数调优表（经验性）

上述参数确切名称、默认值、建议范围均未查到官方明确说明，以官方 indexing / quantization 文档为准；本表为经验性讨论。

6.2 检索进阶要点

• recall 与延迟：扩大 HNSW 查询搜索范围，recall 上升但 P99 延迟上升；量化用精度换内存。建议以未量化精确结果为基线算 recall@k，再逐步调参，实测为准。
• 标量过滤：query_filter 把过滤下推到一次查询里；Filterable HNSW、ACORN（v1.16+）用于改善「带过滤条件时召回不足」。过滤条件过严导致返回少于 limit 是常见现象（见第 8 章），具体 pre / post-filter 实现以官方文档为准。
• 混合检索：v1.20 新增 BM25 全文打分、稀疏向量仅 dot-product、提供 IDF Modifier，稠密 + 稀疏/BM25 混合可行；但融合 / 重排 / RRF 的具体 API 与参数官方未明确，以官方文档为准。

6.3 内存与磁盘容量估算（经验公式）

原始向量内存 ≈ 条数 N × 维度 D × 每维字节数（float32 = 4 B）
示例：N = 1e7，D = 768，float32 → 1e7 × 768 × 4 B ≈ 30.7 GB（仅原始向量）

不含 HNSW 图结构、payload、payload 索引、副本、量化压缩比与系统开销；为经验估算，实际以压测与 /metrics 监控为准。

7. 生产部署与运维

7.1 高可用、集群与备份

分布式集群通常通过分片（shard）与副本（replica）提供容量与高可用，具体配置以官方集群文档为准。数据落在 /qdrant/storage，备份需覆盖该目录，通常以官方快照（snapshot）流程做一致性备份；快照命令、索引是否需重建，未查到官方明确说明，以官方备份文档为准。

7.2 监控、容量与扩缩容

具体指标名与告警阈值未查到官方明确说明，以官方监控文档为准。建议至少覆盖：存活/就绪、写入失败率、查询 P99、内存与磁盘水位、集合点数；阈值按业务 SLO 设定，实测为准。容量按 6.3 估算后叠加 HNSW 图、payload 索引与副本余量；扩缩容以官方集群文档为准。

7.3 升级与跨版本迁移

版本差异：从 <1.20 升到 v1.20，若已配置 API key，注意 service.enforce_internal_auth 默认变为 true，多节点内网通信需一并核对，否则可能节点间鉴权失败。

版本差异：旧代码里的 client.search() 升级后虽多仍能跑（废弃不等于立即移除），但应尽快迁到 query_points。跨版本数据格式兼容矩阵、是否需停机，未查到官方明确说明，以官方升级指南为准。

7.4 安全基线与日志

8. 高频故障与排障

9. 常见坑与避坑清单

1. 沿用 client.search()：废弃告警、新参数不生效，原因是所有变体已废弃；怎么做：统一改 client.query_points(..., query=..., query_filter=Filter(must=[...]))，结果取 .points。
2. 把 Distance 枚举写全：用了不存在的常量报错，原因是完整距离枚举官方未明确；怎么做：只用确认的 Distance.DOT，其余以官方文档为准，不照搬旧教程枚举名。
3. 忽略 service.enforce_internal_auth 默认变化：v1.20 升级后多节点内部通信鉴权失败；怎么做：升级前核对所有节点配置与 key。
4. 稀疏向量用错度量：稀疏检索结果异常，原因是稀疏仅支持 dot-product；怎么做：按 dot-product 使用，以官方文档为准。
5. 向量维度与 size 不一致：upsert 报错；怎么做：建集合与写入用同一维度，常见 768 / 1024 / 1536。
6. 不带 wait=True 就查：刚写入查不到，原因是写入可能异步可见；怎么做：示例用 upsert(..., wait=True)，生产按一致性需求选择，以官方文档为准。
7. 过滤条件写得过严：返回条数远少于 limit，原因是 must 条件过窄；怎么做：先用无 query_filter 查询对比，再逐步加条件。
8. 默认无认证上生产：6333 可被任意访问；怎么做：部署即配 key、收敛网络。

   ⚠️ 危险：无认证 + 公网直曝等于数据裸奔，属高危配置。

9. 误删集合 / 批量删点：线上数据丢失；怎么做：先备份、核对集合名、低峰执行。

   ⚠️ 危险：删除集合不可逆，务必先备份。

10. 容器不挂存储卷：容器重建后数据全空，原因是没映射 /qdrant/storage；怎么做：按 3.1 显式 -v 持久化。

    ⚠️ 危险：生产不挂卷等于把数据放在可丢弃层，重建即丢。

10. 速查表

常用端口与路径

11. 参考与延伸

11.1 官方文档链接清单

官网 https://qdrant.tech ｜ 文档 https://qdrant.tech/documentation ｜ Quickstart https://qdrant.tech/documentation/quickstart/ ｜ 安装 https://qdrant.tech/documentation/guides/installation/ ｜ GitHub https://github.com/qdrant/qdrant ｜ Releases https://github.com/qdrant/qdrant/releases/tag/v1.20.0 ｜ Docker 镜像 https://hub.docker.com/r/qdrant/qdrant ｜ 索引 https://qdrant.tech/documentation/concepts/indexing/ ｜ 量化 https://qdrant.tech/documentation/guides/quantization/ ｜ 监控 https://qdrant.tech/documentation/ops-monitoring/monitoring/

11.2 与同册其他产品的关系

• 已有 PostgreSQL 实例、只需加向量列：见融合型分册 pgvector 篇（模板示例 pgvector.md）。
• 对比同为专用向量库的架构与 API：见 Milvus.md、Weaviate.md；免运维托管见云托管分册 Qdrant Cloud 相关篇；只要进程内索引库见向量索引库分册 Faiss / hnswlib 篇。

11.3 进阶阅读方向

HNSW 参数与 Filterable HNSW / ACORN 的过滤场景调优、四种量化（scalar/product/binary/turbo）的召回-内存权衡、稀疏向量与 BM25 混合检索、turbo8 / turbo16 向量类型、nested payload 索引与公式查询；具体 API 与参数以官方文档为准。

11.4 本篇「未核实 / 以官方为准」事项

1. 距离度量完整枚举（重点）：目前仅确认 Distance.DOT 可用、稀疏向量仅 dot-product；其余度量常量名与取值（如 COSINE / EUCLID / MANHATTAN 等是否可用）官方未明确。正文只把 Distance.DOT 当确定事实，其余以官方文档为准，请勿当作确定结论。
2. 删除点 / 删除集合的方法名与参数：Quickstart 未逐字给出，5.3 为经验性说明，以 qdrant-client 官方文档为准、实测为准。
3. 各索引 / 量化参数的确切名称、默认值、建议范围（HNSW 的 m / ef_construct、查询搜索范围参数、distance 默认值等）：官方未明确，以官方 indexing / quantization 文档为准；第 6 章均为经验性讨论。
4. 一致性模型、写入→可检索的异步细节、多命名向量 / 重排 / 混合检索融合（RRF）API、pre/post-filter 具体行为：官方未明确，以官方文档为准、实测为准。
5. CRUD 的 REST 路径、监控具体指标名、快照/备份恢复具体命令、文件日志默认路径、服务端精确版本字段：官方未明确，以官方文档为准。
6. 距离 / score 方向、容量公式、规模量级、告警阈值：为通用经验，正文一律以「通常 / 实测为准 / 以官方文档为准」表述，非官方结论。