Qdrant 部署与向量搜索¶

一句话概述¶

Qdrant 是一个用 Rust 编写的高性能向量数据库，支持精细的元数据过滤、混合搜索和多种量化技术，在 1000 万向量规模下查询延迟约 12ms，是生产环境中最受欢迎的开源向量搜索引擎之一。

核心知识点表格¶

知识点	说明
项目地址	https://github.com/qdrant/qdrant
官网	https://qdrant.tech
最新版本	v1.17.x（2026年）
开发语言	Rust
核心优势	高性能、精细过滤、多种量化
API 接口	REST + gRPC
量化支持	Scalar / Product / Binary（最高 40x 内存节省）
许可证	Apache 2.0
云服务	Qdrant Cloud（支持 GPU 加速索引）

安装与配置¶

方式一：Docker 安装（推荐）¶

# 拉取并启动 Qdrant
docker run -d \
  --name qdrant \                     # 容器名
  -p 6333:6333 \                      # REST API 端口
  -p 6334:6334 \                      # gRPC 端口
  -v qdrant_storage:/qdrant/storage \ # 数据持久化
  qdrant/qdrant:latest                # 官方镜像

# 验证服务是否启动
curl http://localhost:6333/healthz    # 健康检查

方式二：下载二进制文件¶

# 从 GitHub Releases 下载
# https://github.com/qdrant/qdrant/releases

# Linux 示例
wget https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-gnu.tar.gz
tar xzf qdrant-x86_64-unknown-linux-gnu.tar.gz  # 解压
./qdrant  # 直接运行

Python 客户端安装¶

pip install qdrant-client  # 安装 Python SDK

Docker Compose 部署¶

# docker-compose.yml
version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"           # REST API
      - "6334:6334"           # gRPC
    volumes:
      - qdrant_data:/qdrant/storage  # 数据目录
    environment:
      - QDRANT__SERVICE__API_KEY=your-secret-key  # API 密钥（生产环境必须设置）
    restart: unless-stopped

volumes:
  qdrant_data:

基本使用¶

创建集合和插入数据¶

from qdrant_client import QdrantClient  # 导入客户端
from qdrant_client.models import Distance, VectorParams, PointStruct  # 导入模型

# 连接到 Qdrant
client = QdrantClient(host="localhost", port=6333)

# 创建集合（定义向量维度和距离度量）
client.create_collection(
    collection_name="papers",          # 集合名
    vectors_config=VectorParams(
        size=384,                       # 向量维度（取决于嵌入模型）
        distance=Distance.COSINE        # 余弦距离（最常用）
    )
)

# 插入数据点
client.upsert(
    collection_name="papers",
    points=[
        PointStruct(
            id=1,                        # 点 ID
            vector=[0.1, 0.2, ...],      # 384维向量（由嵌入模型生成）
            payload={                     # 元数据（可过滤）
                "title": "Metagenomics of T2D gut microbiome",
                "year": 2024,
                "topic": "metagenomics",
                "language": "en"
            }
        ),
        PointStruct(
            id=2,
            vector=[0.3, 0.1, ...],
            payload={
                "title": "16S rRNA分析方法综述",
                "year": 2023,
                "topic": "amplicon",
                "language": "zh"
            }
        )
    ]
)

向量搜索¶

# 基本搜索（找到最相似的向量）
results = client.search(
    collection_name="papers",
    query_vector=[0.15, 0.25, ...],  # 查询向量
    limit=5                           # 返回前 5 个
)

for result in results:
    print(f"ID: {result.id}")                     # 数据点 ID
    print(f"相似度: {result.score:.4f}")           # 相似度分数
    print(f"标题: {result.payload['title']}")      # 元数据
    print("---")

带过滤的搜索¶

from qdrant_client.models import Filter, FieldCondition, MatchValue, Range

# 组合过滤条件搜索
results = client.search(
    collection_name="papers",
    query_vector=[0.15, 0.25, ...],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="topic",
                match=MatchValue(value="metagenomics")  # topic 必须是 metagenomics
            ),
            FieldCondition(
                key="year",
                range=Range(gte=2023)  # 年份 >= 2023
            )
        ]
    ),
    limit=5
)

高级用法¶

配合 Sentence-Transformers 使用¶

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct
from sentence_transformers import SentenceTransformer  # 嵌入模型

# 加载嵌入模型（384维）
model = SentenceTransformer("all-MiniLM-L6-v2")

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

# 创建集合
client.recreate_collection(
    collection_name="bioinfo_kb",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

# 准备文档
docs = [
    {"text": "Kraken2 是一个快速的宏基因组物种分类工具", "tool": "kraken2"},
    {"text": "MEGAHIT 使用简洁的de Bruijn图进行宏基因组组装", "tool": "megahit"},
    {"text": "MetaBAT2 是一个自动化的宏基因组binning工具", "tool": "metabat2"},
]

# 生成嵌入并插入
vectors = model.encode([d["text"] for d in docs])  # 批量编码

points = [
    PointStruct(id=i, vector=v.tolist(), payload=d)
    for i, (v, d) in enumerate(zip(vectors, docs))
]

client.upsert(collection_name="bioinfo_kb", points=points)

# 语义搜索
query = "有哪些宏基因组组装软件？"
query_vector = model.encode(query).tolist()  # 编码查询

results = client.search(
    collection_name="bioinfo_kb",
    query_vector=query_vector,
    limit=3
)

for r in results:
    print(f"{r.payload['tool']}: {r.payload['text']} (分数: {r.score:.4f})")

量化优化（节省内存）¶

from qdrant_client.models import (
    VectorParams, Distance,
    ScalarQuantization, ScalarQuantizationConfig, ScalarType
)

# 创建带标量量化的集合（内存减少 4 倍）
client.create_collection(
    collection_name="quantized_collection",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
    quantization_config=ScalarQuantization(
        scalar=ScalarQuantizationConfig(
            type=ScalarType.INT8,      # 将 float32 量化为 int8
            quantile=0.99,             # 保留 99% 的精度
            always_ram=True            # 量化后的向量始终在内存中
        )
    )
)
# 量化后搜索速度提升显著，内存使用大幅减少

Qdrant 快速入门模式（fastembed）¶

from qdrant_client import QdrantClient

# 快速模式：自动处理嵌入，零配置
client = QdrantClient(":memory:")  # 内存模式

# 直接添加文档（自动生成嵌入，不需要外部模型）
client.add(
    collection_name="demo",
    documents=[
        "宏基因组分析流程包括质控、组装、分箱",
        "16S rRNA 测序主要用于微生物群落结构分析",
        "宏转录组可以揭示微生物群落的功能活性"
    ],
    metadata=[
        {"type": "metagenomics"},
        {"type": "amplicon"},
        {"type": "metatranscriptomics"}
    ]
)

# 搜索（自动嵌入查询）
results = client.query(
    collection_name="demo",
    query_text="如何分析微生物基因组？",  # 直接传文本
    limit=3
)

for r in results:
    print(f"文档: {r.document}")
    print(f"元数据: {r.metadata}")
    print(f"分数: {r.score:.4f}")

常见报错与解决¶

报错信息	原因	解决方法
`Collection not found`	集合不存在	先用 `create_collection()` 创建
`Vector dimension mismatch`	向量维度与集合不匹配	检查嵌入模型输出维度是否与集合配置一致
`Connection refused`	Qdrant 未启动	`docker ps` 检查容器状态
`Unauthorized`	API Key 错误	检查 `QDRANT__SERVICE__API_KEY` 配置
`Timeout`	数据量大、请求慢	增加超时时间或使用 gRPC 协议
`Storage error`	磁盘空间不足	清理磁盘或使用量化减少存储

速查表¶

# === Qdrant Python SDK 速查 ===
from qdrant_client import QdrantClient
from qdrant_client.models import *

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

# 集合操作
client.create_collection("name", vectors_config=VectorParams(size=384, distance=Distance.COSINE))
client.get_collection("name")
client.delete_collection("name")
client.get_collections()

# 数据操作
client.upsert("name", points=[PointStruct(id=1, vector=[...], payload={...})])
client.delete("name", points_selector=PointIdsList(points=[1]))
client.retrieve("name", ids=[1])
client.count("name")

# 搜索
client.search("name", query_vector=[...], limit=5)
client.search("name", query_vector=[...], query_filter=Filter(must=[...]))

# 快速模式（自动嵌入）
client.add("name", documents=["..."])
client.query("name", query_text="...", limit=5)

与同类工具对比¶

特性	Qdrant	Chroma	Milvus	Weaviate
开发语言	Rust	Rust+Python	Go+C++	Go
查询延迟(10M)	~12ms	较高	~15ms	~15ms
量化支持	Scalar/Product/Binary	有限	多种	RQ
精细过滤	非常强	基本	强	强
边缘部署	Qdrant Edge	不支持	Milvus Lite	不支持
适合场景	高性能生产	快速原型	大规模分布式	多模态搜索

选择建议：需要高性能、低延迟、精细过滤的生产向量搜索用 Qdrant。快速原型和学习用 Chroma。十亿级向量用 Milvus。