Qdrant

[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，重点回答”它值不值得用、怎么用、什么时候不用”。 底层概念链接到 related_concepts；真实项目落地链接到 used_in_projects。

Qdrant（读作 “quadrant”）是用 Rust 编写的高性能开源向量数据库，专为生产级语义搜索、混合检索和 AI Agent 工作负载设计。

为什么需要它

传统数据库无法高效执行向量相似度搜索，而 FAISS 等库缺少动态 CRUD、元数据过滤和分布式能力。Qdrant 填补了这个空白：提供完整的数据库服务（REST + gRPC），支持向量存储、实时搜索、JSON Payload 过滤和水平扩展——同时保持 Rust 级别的低延迟和内存安全。

没有它时，开发者需要自组合 FAISS + Elasticsearch + 手动同步逻辑，工程复杂且不可靠。

核心优势

• 过滤搜索性能卓越：过滤条件在 HNSW 图遍历过程中执行（非后过滤），过滤开销仅 1.09-1.11x（ChromaDB 为 3.3-8x）
• Rust 零 GC 暂停：无垃圾回收带来的延迟毛刺，适合实时在线服务
• 丰富向量类型：稠密向量（语义搜索）、稀疏向量（SPLADE/BM25）、多向量（ColBERT late interaction）
• 混合搜索：单查询融合稠密 + 稀疏 + 元数据，支持 RRF / DBSF 融合策略和自定义公式（含衰减函数）
• 多种量化方案：Scalar (int8) / Product / Binary / 1.5-bit / 2-bit / 非对称量化，Binary 量化后 1M×768 维向量仅需 ~3GB
• 多层多租户（v1.16+）：小租户共享分片 + 大租户专用分片 + 自动晋升，SaaS 场景利器
• ACORN 算法（v1.16+）：多弱选择性过滤条件下显著提升搜索质量

性能表现

10M 向量 / 768 维 / 余弦距离基准测试（8 vCPU / 32GB）：

过滤开销对比（Dataquest 生产 benchmark）：

x 值 = 过滤搜索耗时 / 无过滤搜索耗时，越接近 1 越好

关键性能特性：自适应查询规划器根据过滤基数自动选择图过滤或暴力扫描；v1.16+ GPU 加速 HNSW 索引构建（最高 10x 提速）。

快速上手

安装

# Docker（推荐）
docker pull qdrant/qdrant
docker run -p 6333:6333 -p 6334:6334 \
    -v ./qdrant_storage:/qdrant/storage \
    qdrant/qdrant

# Python 客户端
pip install qdrant-client
pip install "qdrant-client[fastembed]"  # 含内置 Embedding 模型

# Node / TypeScript
npm install @qdrant/js-client-rest

最小示例

from qdrant_client import QdrantClient, models

# 本地内存模式（开发调试）
client = QdrantClient(":memory:")

# 或连接服务器 / 云
# client = QdrantClient(url="http://localhost:6333")
# client = QdrantClient(url="https://xxx.cloud.qdrant.io", api_key="...")

# 创建集合
client.create_collection(
    collection_name="docs",
    vectors_config=models.VectorParams(size=768, distance=models.Distance.COSINE),
)

# 写入向量
client.upsert(collection_name="docs", points=[
    models.PointStruct(id=1, vector=[0.1, 0.2, ...],
                       payload={"title": "文档1", "category": "tech"}),
])

# 搜索（带过滤）
results = client.query_points(
    collection_name="docs",
    query=[0.1, 0.15, ...],
    limit=5,
    query_filter=models.Filter(must=[
        models.FieldCondition(key="category", match=models.MatchValue(value="tech"))
    ]),
)

配置要点

适用场景

适合：

• RAG 检索层：Qdrant 的核心强项，高效 ANN + Payload 过滤检索上下文（Anthropic 等在生产使用）
• 语义搜索 + 复杂过滤：需要结合元数据（分类、日期、权限、地理位置）的向量搜索
• 推荐系统：多向量支持 + 得分加权重排
• AI Agent 记忆存储：mem0、LangChain 等框架的默认向量库选择之一
• 多租户 SaaS：分层多租户（v1.16+）+ RBAC
• 成本敏感的生产部署：自托管免费（Apache 2.0），托管层也是同类最便宜

不适合：

• 高并发写入场景：Milvus 的分布式架构在写密集负载下表现更好（Qdrant v1.17+ 已改善）
• 小团队无运维能力：自托管需要一定 DevOps 经验（考虑 Pinecone 全托管）
• 已有 PostgreSQL 且向量规模 <10M：用 pgvector 避免引入新数据库
• 需要内置向量化能力：Qdrant 不内嵌模型（不像 Weaviate 有原生模型集成），需外部生成 Embedding向量

已知坑 & 注意事项

[!warning] 客户端-服务端版本必须匹配 如 qdrant-client v1.14.0 与 qdrant server v1.16.3 不兼容，会报 “Internal Server Error”。务必保持 SDK 和 Server 的 major.minor 版本一致。升级时先升 SDK，再升 Server。

[!warning] 不支持降级 升级会自动迁移数据到新存储格式，不可逆。自托管升级必须逐版本递进（1.15→1.16→1.17），不能跳版本。Qdrant Cloud 自动处理。

[!warning] gRPC 响应格式变更（v1.17+） v1.17.0 变更了 vector 字段的 gRPC 响应格式。官方 SDK 已更新，但自定义 gRPC 消费者需自行适配。

• NaN/Inf 向量注入：gRPC 写入不会拒绝 NaN、+Inf 等异常值，会静默损坏 HNSW 图。需在应用层做向量校验
• 大快照恢复慢：多 GB 的 snapshot 恢复可能耗时数小时，期间服务不可用
• WAL 锁冲突：分布式模式下多节点不能共享同一存储目录，每个节点需独立卷
• scroll(order_by) 重复问题：多值数字 Payload 字段可能返回重复记录
• HNSW 参数调优：默认参数非最优，需根据数据集实验调整

竞品对比

选择建议：

• 性能 + 过滤 + 开源 → Qdrant（过滤场景领先，Rust 性能，性价比最优）
• 极致写入吞吐 + 超大规模 → Milvus（分布式架构，写友好）
• 已有 PostgreSQL + 中小规模 → pgvector（零额外运维）
• 团队小 + 不想运维 → Pinecone（全托管，但闭源且贵）
• 需要内置模型推理 → Weaviate（原生模型集成模块）

生态 & 社区

• 维护状态：活跃开发，每 1-2 月一个大版本（v1.16 / Nov 2025, v1.17 / Feb 2026, v1.18 / May 2026）。累计融资 $87.8M（B 轮 2026.3）
• 文档质量：好。有完整的 API 文档、升级指南、故障排查、benchmark 页面。高级功能博客跟进及时
• 周边生态：
  • 官方 SDK：Python / JS-TS / Rust / Go / .NET / Java（共 6 种）
  • AI 框架集成（50+）：LangChain、LlamaIndex、Haystack、CrewAI、AutoGen、DSPy 等
  • 已被 mem0、Microsoft GraphRAG、Neo4j GraphRAG 等项目选为向量后端
  • 知名用户：Anthropic、Tripadvisor、HubSpot、Canva、Discord、Bosch
• 社区活跃度：~29K ⭐ / 250M+ 下载 / 30K+ 社区成员 / Discord 活跃

引入评估

结论：强烈推荐 — Qdrant 在开源向量数据库中提供了最佳的过滤搜索性能和性价比。Rust 基础保证低延迟和内存安全，丰富的量化方案适合成本敏感场景，50+ 框架集成覆盖主流 AI 生态。唯一需要注意的是版本升级路径（不可跳版本、不可降级），建议使用 Qdrant Cloud 减少运维负担。

推荐引入版本：qdrant:v1.18.0（Server）/ qdrant-client==1.18.0（Python SDK）

相关链接

前置知识：向量数据库 · Embedding向量 · RAG · 索引 竞品：PostgreSQL（pgvector） 使用场景：mem0 · LangChain · LangGraph 底层概念：哈希函数 · 哈希算法

• GitHub 仓库
• 官方文档
• Benchmark 页面
• 定价
• 升级指南
• Changelog

个人备注