Qdrant 向量数据库核心操作指南

部署方式

Docker 生产环境部署命令：

docker pull qdrant/qdrant:v1.16
docker run -d \
  -p 6333:6333 \
  -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant:v1.16

数据结构模型

• Collection：逻辑存储单元，类比关系型数据库的表结构
• Vector：高维数值数组，典型维度为1024/768
• Payload：键值对形式的元数据存储
• Point：包含ID+Vector+Payload的完整数据单元

Python客户端初始化

from qdrant_client import QdrantClient
client = QdrantClient(host="localhost", port=6333)

集合管理

创建1024维余弦相似度集合：

client.create_collection(
    collection_name="text_embeddings",
    vectors_config=VectorParams(size=1024, distance=Distance.COSINE)
)

数据写入操作

批量插入带元数据的向量：

points = [
    PointStruct(
        id=idx,
        vector=embedding.tolist(),
        payload={"text": text, "source": "web"}
    )
    for idx, (text, embedding) in enumerate(data)
]
client.upsert("text_embeddings", points)

相似性检索

带过滤条件的近似搜索：

query_filter = Filter(
    must=[FieldCondition(key="source", match=MatchValue(value="web"))]
)
results = client.search(
    collection_name="text_embeddings",
    query_vector=query_embedding,
    query_filter=query_filter,
    limit=3
)

性能优化技巧

• 批量操作使用search_batch替代循环单次查询
• gRPC端口(6334)比HTTP端口(6333)吞吐量高30%
• 分页查询时合理设置offset和limit参数

距离度量选择

类型	适用场景	计算方式
COSINE	文本相似度	1 - cosθ
EUCLID	空间距离	√Σ(x-y)²
DOT	线性相关性	x·y

系统监控

获取集合统计信息：

collection_info = client.get_collection("text_embeddings")
print(f"向量数量：{collection_info.vectors_count}")
print(f"索引状态：{collection_info.status}")

故障排查

• 维度不匹配错误：检查embedding模型输出维度与collection配置是否一致
• 版本冲突：Python 3.13需指定兼容版本qdrant-client==1.6.1
• 存储异常：验证Docker卷挂载路径权限