商洛网站开发云搜索引擎

Qdrant 是近年来非常热门的向量数据库，广泛用于文本搜索、推荐系统、图像相似度匹配等场景。本文将带你从最实用的三个层面入手，快速上手并用好 Qdrant 的核心能力：

1. ✅ 远程连接配置详解

2. 🏗️ 集合创建参数全面解释

3. 🔍 查询参数高级用法

4. 🔥本例为Qdrant 1.14.2（注意！）

---

✅ 一、远程连接配置详解（QdrantClient）

在本地你可以用 host 和 port 来连接 Qdrant 服务，而在生产中，通常使用 Qdrant Cloud 提供的 HTTPS 接口和 API 密钥：

from qdrant_client import QdrantClientclient = QdrantClient(url="https://your-qdrant-endpoint.qdrant.io",api_key="your-api-key-here"
)

参数	类型	说明
url	str	Qdrant 服务的远程地址，必须是 HTTPS
api_key	str	API 密钥，保护访问权限
timeout	int/float	（可选）请求超时，默认 5 秒
prefer_grpc	bool	（可选）是否优先使用 gRPC，速度更快，但需服务器支持

📌 本地开发：

client = QdrantClient(host="localhost", port=6333)

---

🏗️ 二、创建集合（Collection）参数详解

向量搜索的前提是集合（Collection），它类似于表结构，用于存储向量及其 metadata。下面是一个完整的创建集合示例：

from qdrant_client.http.models import VectorParams, Distanceclient.create_collection(collection_name="c_names",vectors_config=VectorParams(size=4,distance=Distance.COSINE)
)points = [PointStruct(id=str(uuid.uuid4()), vector=[0.1, 0.2, 0.3, 0.4], payload={"name": "Tokyo"}),PointStruct(id=str(uuid.uuid4()), vector=[0.2, 0.1, 0.4, 0.3], payload={"name": "Kyoto"}),
]client.upsert(collection_name="c_names", points=points)
print("✅ 已插入测试数据")

✳️ 参数解析

参数名	说明
collection_name	集合名称（自定义）
size	向量维度（取决于你的 embedding 模型）
distance	相似度计算方式（推荐使用 COSINE）

📌 常见模型维度对照

模型名称	维度（size）
MiniLM-L12-v2	384
e5-base	768
text-embedding-3-small	1536

🛠️ 可选参数（进阶）：

参数名	说明
on_disk_payload	是否将 payload 存储到磁盘（节省内存）
hnsw_config	索引构建参数，可优化召回速度

---

🔍 三、查询参数详解：

query_points()

 实战

Qdrant 旧接口 search() 已弃用，推荐使用新版 query_points()。这是最常用的检索 API，支持分页、筛选、相似度阈值等强大功能：

from qdrant_client.http.models import QueryVectorresults = client.query_points(collection_name="c_names",query=[0.1, 0.2, 0.3, 0.4],limit=5,with_payload=True,score_threshold=0.9
)print("🔍 查询结果：")
for r in result.points:print(f"- id: {r.id}, score: {r.score}, payload: {r.payload}")

📌 参数详解

参数名	类型	说明
collection_name	str	要查询的集合名
query	QueryVector	查询向量，维度必须匹配
limit	int	返回结果数量上限
with_payload	bool	是否返回 metadata（如地名）
score_threshold	float	仅返回相似度高于该阈值的记录
offset	int	分页偏移量（跳过前N条）
filter	Filter 对象	高级筛选条件（如国家名）

---

🔥 

score_threshold

 使用技巧

如果你希望结果尽量“接近”原始向量，可以使用 score_threshold，比如：

score_threshold=0.95

这意味着只保留相似度高于 0.95 的结果，常用于高置信度翻译、名称匹配等场景。

---

🎯 高级筛选：按字段过滤（

filter

）

from qdrant_client.http.models import Filter, FieldCondition, MatchValuemy_filter = Filter(must=[FieldCondition(key="country",match=MatchValue(value="Japan"))]
)

然后作为参数传入：

results = client.query_points(collection_name="place_names",query=[...],filter=my_filter,limit=10
)

---

📌 总结速查表

场景	推荐配置
文本相似搜索	distance=COSINE + 384 维
精准匹配	加入 score_threshold=0.9+
分类过滤	使用 filter 结合 payload
排查效果	开启 with_vectors=True 查看返回向量

---

🎁 附加建议

• 使用 sentence-transformers 快速生成文本向量；

• 本地测试建议使用 Docker 启动 Qdrant；

• 在线部署推荐使用 Qdrant Cloud，支持备份与权限管理；

• API 更新频繁，记得关注 官方文档。