Qdrant：从连接到查询的实战指南

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

1. ✅ 远程连接配置详解

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

3. 查询参数高级用法

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

---

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

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

from qdrant_client import QdrantClient

client = 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, Distance

client.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 QueryVector

results = 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, MatchValue

my_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 更新频繁，记得关注 官方文档。