qdrant/qdrant：Rust编写的高性能向量搜索引擎

一、官方信息

二、项目背景

向量数据库通常要在"内存速度"和"数据规模"之间做权衡：把向量全放内存查询快但成本高，放磁盘又怕拖慢延迟。Qdrant（发音是 quadrant）由俄罗斯团队开发，用 Rust 重写了整套向量检索引擎，目标就是在保证亚毫秒级查询延迟的同时，把单机能承载的数据量做到极致。

Qdrant 把自己定位成"向量搜索引擎"而非单纯的向量数据库，核心卖点是带过滤条件的向量检索：你可以一边做 ANN 相似度搜索，一边用 payload（结构化字段）做 WHERE 过滤，比如"在商品分类=电子 且 价格<5000 的向量里找最相似的 10 个"。这种过滤能力对推荐、广告、RAG 权限过滤场景极其重要。

Qdrant 单二进制部署极其轻量，一个 Docker 镜像就能跑，自带 RESTful API 和 gRPC，官方还提供了一套漂亮的 Web UI（Qdrant Web UI / Console）。它原生支持 LangChain、LlamaIndex、Haystack，是目前 RAG 项目里部署最简单、口碑最好的向量库之一。

三、核心特性

• Rust 编写：内存安全、单二进制、无 JVM 开销，单机性能强悍。
• 带 Payload 过滤的向量检索：向量相似度 + 结构化条件联合查询。
• 多种距离度量：Cosine、Dot、Euclidean、Manhattan。
• 丰富索引：HNSW 可调，支持标量索引、全文索引、稀疏向量。
• 量化压缩：Scalar / Product / Binary Quantization，大幅降低内存占用。
• 集群与分布式：支持分片、副本、水平扩展。
• 开箱 Web UI：内置控制台，可视化浏览 collections 与数据。
• REST + gRPC：Python / JS / Go / Rust 客户端齐全。

四、环境要求

• 操作系统：Linux（推荐 Ubuntu 22.04）、macOS、Windows（WSL2）。
• Docker 20.10+（推荐）；或直接下载二进制。
• 内存：建议 2GB 以上；向量数据量大时按数据规模加内存。
• 端口：6333（HTTP / Web UI）、6334（gRPC）。

五、详细部署步骤

方式一：Docker 单容器（最简单）

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

参数说明：

• -p 6333:6333：HTTP API 与 Web UI 端口。
• -p 6334:6334：gRPC 端口，高性能客户端使用。
• -v ...:/qdrant/storage：持久化数据目录，必须映射否则重启丢数据。

方式二：Docker Compose（生产推荐，带 API Key）

mkdir qdrant && cd qdrant
cat > docker-compose.yml <<'EOF'
services:
  qdrant:
    image: qdrant/qdrant:latest
    restart: always
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_storage:/qdrant/storage
    environment:
      QDRANT__SERVICE__API_KEY: "your-strong-api-key"
EOF
docker compose up -d

关键配置：QDRANT__SERVICE__API_KEY 设置后，所有请求都需在 Header 带 api-key: your-strong-api-key，公网部署务必开启。

方式三：裸二进制部署

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

创建 Collection 并写入数据

# 创建一个 768 维、Cosine 距离的 collection
curl -X PUT http://localhost:6333/collections/rag_docs \
  -H 'Content-Type: application/json' \
  -d '{
    "vectors": { "size": 768, "distance": "Cosine" },
    "on_disk_payload": true
  }'

# 写入带 payload 的点
curl -X PUT http://localhost:6333/collections/rag_docs/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {"id": 1, "vector": [0.1]*768, "payload": {"source": "manual.pdf", "page": 3}}
    ]
  }'

Python SDK 使用

pip install qdrant-client

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

client = QdrantClient(url="http://localhost:6333", api_key="your-strong-api-key")

client.recreate_collection(
    collection_name="rag_docs",
    vectors_config=VectorParams(size=768, distance=Distance.COSINE),
)

client.upsert(
    collection_name="rag_docs",
    points=[PointStruct(id=1, vector=[0.1]*768, payload={"source": "manual.pdf"})],
)

# 带过滤的相似度搜索
hits = client.search(
    collection_name="rag_docs",
    query_vector=[0.1]*768,
    limit=5,
    query_filter={"must": [{"key": "source", "match": {"value": "manual.pdf"}}]},
)
print(hits)

验证部署

curl http://localhost:6333/collections
# 浏览器打开 Web UI：
# http://服务器IP:6333/dashboard

六、使用方法

1. 浏览器访问 http://服务器IP:6333/dashboard 打开 Web UI，若设置了 API Key 需在页面输入。
2. UI 中可查看所有 collections、向量数据、payload，执行滚动查询。
3. 在 LangChain 中作为向量库：from langchain_community.vectorstores import Qdrant，传入 url 与 api_key。
4. 默认无账号密码（未设 API Key 时）；设了 Key 后客户端都要带 api_key。

七、常见问题 FAQ

Q1：dashboard 打不开但 API 正常？
A：Qdrant Web UI 路径是 /dashboard，根路径 / 返回的是 JSON 欢迎信息，属正常现象。

Q2：内存占用太高怎么办？
A：开启量化（Scalar / Product Quantization），把向量存到磁盘并配合 on_disk 参数，可用 1/4 ~ 1/16 的内存承载同样数据。

Q3：如何开启鉴权？
A：在环境变量 QDRANT__SERVICE__API_KEY 中设置，重启后所有请求需在 Header 携带。

Q4：6333 和 6334 区别？
A：6333 是 REST HTTP（Web UI 也走它），6334 是 gRPC，适合高吞吐生产客户端。

Q5：数据备份？
A：直接备份挂载的 qdrant_storage 目录；也可用 snapshots API 做在线快照。

八、跳转链接

• GitHub 仓库：https://github.com/qdrant/qdrant
• 官方文档：https://qdrant.tech/documentation/
• Docker 镜像：https://hub.docker.com/r/qdrant/qdrant
• Python 客户端：https://github.com/qdrant/qdrant-client