你刚在笔记本上跑通了本地大模型,想给手头几百份设备说明书做个「问一句就翻到那一页」的问答。规则是:先让文档变成机器能比对的形状,再找一个能存它、查它的库。今天这个项目就是那个库。
项目名片
| 字段 | 内容 |
|---|---|
| 仓库 | 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 替掉的是「自己写相似度检索后端」这一整块;它替不掉的是嵌入模型本身——向量仍要靠模型算,模型选得差,库再快也搜不准。
核心机制
- 它用 HNSW 图做近似最近邻索引,牺牲少量精度换百倍级的查询加速(推断:中等规模数据下召回率在九成以上,是这类索引的常见水平,具体要看你的数据)。
- 每条数据是一个 point,由向量加 payload 组成;payload 是任意结构化字段,可以建索引后参与过滤,先按「设备型号=ZJS-500」缩小范围再找近邻。
- 数据落盘默认开启,写入先进 WAL 再刷盘,重启服务集合不丢(推断:单机可靠性是够用的,但备份仍要自己负责)。
- 支持标量量化,把向量压成低精度整数存放,显存和内存占用能降一个数量级(推断:适合百万条以上的场景,小数据别折腾)。
跑起来
机器上装好 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
从零到能用
- 上面四条命令起服务,确认 collections 接口返回空列表。
- 建一个测试集合,指定向量维度和距离度量。
- 用 upsert 写入几条带 payload 的向量。
- 用 query_points 发一个查询向量,看返回的近邻和得分。
- 把文档切成段,逐段过嵌入模型,批量写入,就是你的第一个语义搜索。
对应的 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 工程方向走的——搭一个带过滤的检索服务,写进简历里是有实感的项目经历。
别用的两类场景:数据只有几千条且更新少,内存里直接算距离更省事;需求其实是全文关键词匹配,传统倒排索引更合适,硬套向量检索反而会召回一堆似是而非的结果。
三个真实的坑
- 建集合报「Can't init WAL: Invalid argument」。issue #3132 里记录的环境是 docker 镜像加 qdrant_client 1.6.9,报错点在 WAL 初始化。遇到先别怀疑代码,检查存储卷挂载方式和镜像版本。
- 删除集合卡十秒后报「Waiting for consensus operation commit failed」。issue #3121 记录了同样现象:删除也走共识提交,磁盘 IO 慢时会超时。重试一次通常能过,频繁出现就该看盘了。
- 三节点集群跑几小时后节点间连不通。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
默认评论
Halo系统提供的评论