qdrant-vector-search

用途

Qdrant 是一个用 Rust 编写的高性能向量数据库，主要用于生产环境的 RAG（检索增强生成）与语义搜索。当需要低延迟的最近邻搜索、向量与元数据混合过滤、水平扩展（分片/副本）、本地部署并完全掌控数据，或每条记录存储多向量（稠密 + 稀疏）时，适合使用 Qdrant。它也适用于构建实时推荐系统。

如果场景更偏向简单嵌入、追求最大原始速度的研究/批处理、完全托管零运维，或偏好 GraphQL 与内置向量化器，资料建议考虑 Chroma、FAISS、Pinecone、Weaviate 等替代方案。

主要能力

Rust 驱动：内存安全、高性能。
丰富过滤：搜索时可按任意 payload 字段过滤。
多向量：每个 point 支持稠密、稀疏、多稠密向量。
量化：标量、乘积、二值量化，用于节省内存。
分布式：Raft 共识、分片、副本。
REST + gRPC：两种 API 功能对等。

安装与快速开始

Python 客户端：

pip install qdrant-client

Docker（推荐用于开发）：

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

带持久化存储的 Docker：

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage \
    qdrant/qdrant

基础用法示例：

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

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

client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

client.upsert(
    collection_name="documents",
    points=[
        PointStruct(
            id=1,
            vector=[0.1, 0.2, ...],
            payload={"title": "Doc 1", "category": "tech"}
        ),
        PointStruct(
            id=2,
            vector=[0.3, 0.4, ...],
            payload={"title": "Doc 2", "category": "science"}
        )
    ]
)

results = client.search(
    collection_name="documents",
    query_vector=[0.15, 0.25, ...],
    query_filter={
        "must": [{"key": "category", "match": {"value": "tech"}}]
    },
    limit=10
)

for point in results:
    print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")

核心概念

Points（点）：基本数据单元，由 ID、向量和 payload 组成。ID 可为整数或 UUID 字符串，payload 为任意 JSON 元数据。推荐使用批量 upsert，并可设置 wait=True 等待索引完成。

Collections（集合）：向量的容器。创建时可配置向量维度、距离度量，以及 HNSW 参数（如 m、ef_construct、full_scan_threshold）和 on_disk_payload。可通过 get_collection 查看点数与向量数。

距离度量：

度量	适用场景	范围
COSINE	文本嵌入、归一化向量	0 到 2
EUCLID	空间数据、图像特征	0 到 ∞
DOT	推荐、未归一化向量	-∞ 到 ∞
MANHATTAN	稀疏特征、离散数据	0 到 ∞

搜索操作

基础搜索：指定 query_vector、limit，可控制是否返回 payload 与向量。
过滤搜索：使用 Filter 与 FieldCondition，支持 must、must_not，以及 MatchValue、Range 等条件，也可使用简写字典语法。
批量搜索：通过 search_batch 与 SearchRequest 在单次请求中执行多个查询。

RAG 集成

可与 sentence-transformers 配合：用编码器生成向量，创建集合、索引文档，并封装 retrieve 函数返回文本与分数，再拼入 RAG 提示词。

LangChain 集成示例：

from langchain_community.vectorstores import Qdrant
from langchain_community.embeddings import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
vectorstore = Qdrant.from_documents(documents, embeddings, url="http://localhost:6333", collection_name="docs")
retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

LlamaIndex 集成示例：

from llama_index.vector_stores.qdrant import QdrantVectorStore
from llama_index.core import VectorStoreIndex, StorageContext

vector_store = QdrantVectorStore(client=client, collection_name="llama_docs")
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
query_engine = index.as_query_engine()

多向量支持

命名向量：集合可同时定义多个向量（如 dense 与 sparse），插入时以字典形式提供，搜索时用元组指定目标向量。
稀疏向量：支持 BM25、SPLADE 等，通过 SparseVectorParams 与 SparseVector（indices + values）配置与插入。

量化与索引

标量量化示例（约 4 倍内存缩减）：

from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType

client.create_collection(
    collection_name="quantized",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
    quantization_config=ScalarQuantization(
        scalar=ScalarQuantizationConfig(
            type=ScalarType.INT8,
            quantile=0.99,
            always_ram=True
        )
    )
)

搜索时可开启重打分：search_params={"quantization": {"rescore": True}}。

Payload 索引可加速过滤，索引类型包括 KEYWORD、INTEGER、FLOAT、GEO、TEXT（全文）、BOOL：

from qdrant_client.models import PayloadSchemaType

client.create_payload_index(
    collection_name="documents",
    field_name="category",
    field_schema=PayloadSchemaType.KEYWORD
)

生产部署与调优

连接 Qdrant Cloud：

from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://your-cluster.cloud.qdrant.io",
    api_key="your-api-key"
)

性能调优：可通过 update_collection 调整 HNSW 参数（如提高 ef_construct、m 以提升召回）或调整 optimizer_config 的 indexing_threshold 以优化批量导入速度。

最佳实践

批量操作：使用批量 upsert/search 提升效率。
Payload 索引：为过滤字段建立索引。
量化：大规模集合（>100 万向量）启用。
分片：集合超过 1000 万向量时使用。
磁盘存储：大 payload 启用 on_disk_payload。
连接池：复用客户端实例。

常见问题

带过滤的搜索慢：为过滤字段创建 payload 索引。
内存不足：启用量化与磁盘存储。
连接问题：设置超时与重试，并可用 prefer_grpc=True 提升性能。

适用场景与限制

适用场景包括生产级 RAG、语义搜索、混合搜索、实时推荐，以及需要本地部署、水平扩展和多向量存储的系统。限制方面，资料未提供具体的性能上限、价格或收费信息；若追求极简嵌入、最大原始速度或完全托管零运维，资料建议改用其他替代方案。

资源

GitHub：https://github.com/qdrant/qdrant （22k+ stars）
文档：https://qdrant.tech/documentation/
Python 客户端：https://github.com/qdrant/qdrant-client
云服务：https://cloud.qdrant.io
版本：1.12.0+
许可证：Apache 2.0