Qdrant 查询接口是什么
Qdrant 新版客户端把查询统一收敛到 query_points 一个方法：既能按向量做近邻检索，也能按已有 id 做相似推荐（recommend，可给出正负样例），还能按条件 scroll 浏览数据。旧版的 search 接口在较新的 qdrant-client 中已被并入 query，沿用旧写法会收到弃用提示甚至报错。查询时可以只取需要的 payload 字段，减少带宽与反序列化开销，这在宽 payload 场景下非常明显。
基本信息
| 统一入口 | client.query_points(collection_name, query=...) |
|---|---|
| 查询类型 | 向量近邻、RecommendQuery（正负样例）、scroll 浏览 |
| 过滤 | query_filter 中使用 must / should / must_not 条件 |
| 返回控制 | limit、with_payload（可指定字段列表）、with_vectors |
| 兼容性 | 旧 search 接口在新客户端中已弃用 |
典型使用场景
- 常规检索：向量近邻加元数据过滤，取 top 10
- 相似内容推荐：给定已有 point 的 id 找相近内容，可加入负样例排除方向
- 数据巡检：按条件 scroll 抽样查看 payload 是否符合预期
- 带宽优化：只返回 source 与 title 字段，避免整段原文来回传输
- 迁移适配：把旧 search 调用按迁移指南改写为 query_points
向量检索与带过滤检索
向量检索与带过滤检索
from qdrant_client import QdrantClient, models
client = QdrantClient(url='http://localhost:6333')
res = client.query_points(
collection_name='kb',
query=query_vec,
query_filter=models.Filter(must=[models.FieldCondition(
key='source', match=models.MatchValue(value='handbook'))]),
limit=10, with_payload=['source', 'title'],
)
for p in res.points:
print(p.id, p.score, p.payload)按已有 id 找相似
按已有 id 找相似
res = client.query_points(
'kb',
query=models.RecommendQuery(recommend=models.RecommendInput(
positive=['c-1', 'c-7'], negative=['c-9'])),
limit=5, with_payload=False) # 只要 id 与分数查询类型与参数
| 查询 | 关键参数 | 注意点 |
|---|---|---|
| 向量近邻 | query=向量, limit | 向量维度必须与集合一致 |
| 带过滤检索 | query_filter | 过滤字段建议建 payload 索引 |
| RecommendQuery | positive/negative id 列表 | 负样例用于排除方向，可省略 |
| scroll | filter, limit | 用于巡检，不是相关性排序 |
接口迁移与调优要点
- 版本对齐：升级 qdrant-client 后按官方迁移指南把 search 改写为 query_points
- 字段瘦身：with_payload 传字段列表，别把整段原文来回传输
- 索引补齐：过滤用到的 payload 字段建索引，否则过滤阶段逐点扫描
- 结果校验：对同一查询分别跑过滤与不过滤，确认过滤条件真的生效
with_payload 指定字段列表能显著减少传输量：payload 里放了长文本时，全字段返回会让延迟随结果条数线性上升，而检索阶段真正需要的往往只有来源与标题。