小岳
2026-11-21
点 赞
0
热 度
0
评 论
0

Qdrant:把向量检索装进你的机器

  1. 首页
  2. 开源分享
  3. Qdrant:把向量检索装进你的机器

文章摘要

摸鱼小助手

你刚在笔记本上跑通了本地大模型,想给手头几百份设备说明书做个「问一句就翻到那一页」的问答。规则是:先让文档变成机器能比对的形状,再找一个能存它、查它的库。今天这个项目就是那个库。

项目名片

字段 内容
仓库 github.com/qdrant/qdrant
Star / Fork 35,648 / 2,829(2026-11-21 抓取)
技术栈 Rust,服务端编译为单个二进制
许可证 Apache-2.0(已核 LICENSE 原文)
最新版本 v1.20.2(2026-11-16 发布)
默认端口 6333(REST)/ 6334(gRPC)

它解决什么问题

关键词搜索的短板是认死理:搜「过热保护」就找不到写着「温升异常」的段落。向量检索的思路是把文本交给嵌入模型压成一个几百维的向量,语义相近的段落在空间里挨得近,找相似就变成了找近邻。

麻烦在于:自己拿 NumPy 暴力算距离,几千条向量还行;到了几十万条,每次查询都要全量比对,延迟和内存都扛不住。Qdrant 替掉的是「自己写相似度检索后端」这一整块;它替不掉的是嵌入模型本身——向量仍要靠模型算,模型选得差,库再快也搜不准。

核心机制

  1. 它用 HNSW 图做近似最近邻索引,牺牲少量精度换百倍级的查询加速(推断:中等规模数据下召回率在九成以上,是这类索引的常见水平,具体要看你的数据)。
  2. 每条数据是一个 point,由向量加 payload 组成;payload 是任意结构化字段,可以建索引后参与过滤,先按「设备型号=ZJS-500」缩小范围再找近邻。
  3. 数据落盘默认开启,写入先进 WAL 再刷盘,重启服务集合不丢(推断:单机可靠性是够用的,但备份仍要自己负责)。
  4. 支持标量量化,把向量压成低精度整数存放,显存和内存占用能降一个数量级(推断:适合百万条以上的场景,小数据别折腾)。

Qdrant 检索流程

跑起来

机器上装好 Docker,四条命令起来一个能用的实例:

docker pull qdrant/qdrant:v1.20.2
docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  qdrant/qdrant:v1.20.2
curl http://localhost:6333/collections

浏览器打开本机 6333 端口的 dashboard 页面,能看到集合、向量数和查询延迟的实时面板。再装 Python 客户端:

pip install qdrant-client

从零到能用

  1. 上面四条命令起服务,确认 collections 接口返回空列表。
  2. 建一个测试集合,指定向量维度和距离度量。
  3. 用 upsert 写入几条带 payload 的向量。
  4. 用 query_points 发一个查询向量,看返回的近邻和得分。
  5. 把文档切成段,逐段过嵌入模型,批量写入,就是你的第一个语义搜索。

对应的 Python 代码,可直接粘贴(向量维度按你的模型改):

from qdrant_client import QdrantClient
import qdrant_client.models as m

c = QdrantClient(url="http://localhost:6333")
c.create_collection(
    "demo",
    vectors_config=m.VectorParams(
        size=4, distance=m.Distance.COSINE
    ),
)
c.upsert("demo", points=[m.PointStruct(
    id=1, vector=[0.1, 0.2, 0.3, 0.4],
    payload={"doc": "变压器巡检记录"},
)])
hit = c.query_points(
    "demo", query=[0.1, 0.2, 0.3, 0.35]
)
print(hit.points[0].score)

注意 README 原文提示:默认启动是「不安全部署,无鉴权,监听所有网卡」。放到有公网 IP 的服务器上时,至少用防火墙把 6333 限到内网,或按官方文档开启 API Key。

适合谁用 / 别用

适合两类人:一是在本地跑模型、想给自己的文档库做语义检索的;二是找工作想往 AI 工程方向走的——搭一个带过滤的检索服务,写进简历里是有实感的项目经历。

别用的两类场景:数据只有几千条且更新少,内存里直接算距离更省事;需求其实是全文关键词匹配,传统倒排索引更合适,硬套向量检索反而会召回一堆似是而非的结果。

三个真实的坑

  1. 建集合报「Can't init WAL: Invalid argument」。issue #3132 里记录的环境是 docker 镜像加 qdrant_client 1.6.9,报错点在 WAL 初始化。遇到先别怀疑代码,检查存储卷挂载方式和镜像版本。
  2. 删除集合卡十秒后报「Waiting for consensus operation commit failed」。issue #3121 记录了同样现象:删除也走共识提交,磁盘 IO 慢时会超时。重试一次通常能过,频繁出现就该看盘了。
  3. 三节点集群跑几小时后节点间连不通。issue #4655 的报错指向 6335 端口,这是集群内部通信口,防火墙只放行 6333/6334 时集群会「假死」。单机玩不会踩,组集群前先把 6335 放行。

小结

开头那个想做说明书问答的场景,用 Qdrant 加一个嵌入模型,一个晚上就能从零搭起来。它把最难的「几十万条向量里找近邻」变成一条 API 调用,你只需要把向量算对、把 payload 设计好。今晚就 pull 下来跑一遍,简历上那句「语义检索系统」就有出处了。

参考资料

  • 仓库:https://github.com/qdrant/qdrant
  • 快速上手:https://qdrant.tech/documentation/quickstart/
  • v1.20.2 发布页:https://github.com/qdrant/qdrant/releases/tag/v1.20.2
  • 坑 1:https://github.com/qdrant/qdrant/issues/3132
  • 坑 2:https://github.com/qdrant/qdrant/issues/3121
  • 坑 3:https://github.com/qdrant/qdrant/issues/4655

本站站长,主角光环,怎么滴,你还想攻击你的站长吗,真是好big的狗胆

小岳

intp 逻辑家

站长

不具版权性
不具时效性

文章内容不具时效性。若文章内容有错误之处,请您批评指正。

目录

欢迎来到摸鱼干货栈,这里为您提供开源与摸鱼源码

43 文章数
7 分类数
0 评论数
47标签数
最近评论