📦 一、Qdrant 简介

• 语言：Rust（高性能、内存安全）
• 协议：RESTful API + gRPC（v1.8+）
• 核心特性：
  • 支持 HNSW、IVF、DiskANN 等索引
  • Payload（元数据）过滤 + 全文检索（v1.9+）
  • 量化压缩（Scalar / Product Quantization）
  • 多向量、动态 schema、快照备份
• 适用场景：RAG、推荐系统、语义搜索、AI Agent 记忆库

🚀 二、单机部署（推荐用于开发/中小生产）

方式 1：Docker（最简单）

# 拉取最新镜像（2025 年推荐 v1.10+）
docker pull qdrant/qdrant:v1.10.0

# 创建持久化目录
mkdir -p ./qdrant_data

# 启动容器（带 API Key 认证）
docker run -d \
  --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v $(pwd)/qdrant_data:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY="your_strong_secret_key" \
  qdrant/qdrant:v1.10.0

✅ 默认数据目录：/qdrant/storage
✅ REST API：http://localhost:6333
✅ Dashboard（Web UI）：http://localhost:6333/dashboard

方式 2：二进制安装（无 Docker 环境）

适用于 CentOS / Ubuntu / macOS：

# 下载 Linux x86_64 二进制（替换为最新版）
wget https://github.com/qdrant/qdrant/releases/download/v1.10.0/qdrant-1.10.0-x86_64-unknown-linux-musl.tar.gz

tar -xzf qdrant-*.tar.gz
cd qdrant

# 创建配置文件 config.yaml（可选）
cat > config.yaml <<EOF
storage:
  storage_path: ./storage

service:
  api_key: your_strong_secret_key

telemetry_disabled: true
EOF

# 启动
./qdrant --config-path ./config.yaml

🔐 生产环境务必设置 api_key，否则任意人可写入！

🌐 三、集群部署（高可用生产环境）

Qdrant 支持 Raft 共识协议的分布式集群。

使用 Docker Compose 模拟 3 节点集群

# docker-compose.cluster.yml
version: '3.8'
services:
  qdrant-1:
    image: qdrant/qdrant:v1.10.0
    ports:
      - "6333:6333"
    volumes:
      - ./node1:/qdrant/storage
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
      - QDRANT__CLUSTER__HOSTS=qdrant-1:6335,qdrant-2:6335,qdrant-3:6335
    networks:
      - qdrant-net

  qdrant-2:
    image: qdrant/qdrant:v1.10.0
    volumes:
      - ./node2:/qdrant/storage
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
      - QDRANT__CLUSTER__HOSTS=qdrant-1:6335,qdrant-2:6335,qdrant-3:6335
    networks:
      - qdrant-net

  qdrant-3:
    image: qdrant/qdrant:v1.10.0
    volumes:
      - ./node3:/qdrant/storage
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
      - QDRANT__CLUSTER__HOSTS=qdrant-1:6335,qdrant-2:6335,qdrant-3:6335
    networks:
      - qdrant-net

networks:
  qdrant-net:
    driver: bridge

启动：

docker-compose -f docker-compose.cluster.yml up -d

⚠️ 注意：

• 所有节点必须能互相解析 hostname（Docker 内部网络自动支持）
• 首次启动需等待 Raft 选举完成（约 10-30 秒）
• 写入任一节点，数据自动同步

Kubernetes 部署（Helm Chart）

# 添加官方 Helm 仓库
helm repo add qdrant https://qdrant.github.io/qdrant-helm
helm repo update

# 安装（3 副本）
helm install qdrant-cluster qdrant/qdrant \
  --set replicaCount=3 \
  --set service.apiKey="your_secret" \
  --set persistence.enabled=true \
  --set persistence.size=50Gi

📦 Helm Chart 支持：PV、HPA、Prometheus 监控、TLS

🔐 四、安全与运维

1. 启用 API Key（强制）

# config.yaml
service:
  api_key: "my_secure_api_key_123!"

或环境变量：

-e QDRANT__SERVICE__API_KEY="my_secure_api_key_123!"

客户端调用时需携带 Header：

Authorization: Bearer my_secure_api_key_123!

2. 快照备份与恢复

创建快照：

curl -X POST http://localhost:6333/collections/my_collection/snapshots \
  -H "Authorization: Bearer your_key"

恢复快照：

# 先上传快照文件到 /qdrant/storage/snapshots/
curl -X PUT http://localhost:6333/collections/my_collection/snapshots/my_snapshot.snapshot

💡 自动快照策略可通过 snapshots 配置开启

3. 监控（Prometheus + Grafana）

Qdrant 内置 Prometheus 指标端点：

http://localhost:6333/metrics

关键指标：

• qdrant_rest_requests_total：请求计数
• qdrant_collection_vector_index_ram_usage_bytes：内存使用
• qdrant_search_latency_seconds：搜索延迟

💻 五、Python 应用集成

1. 原生 SDK（推荐）

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

# 初始化客户端
client = QdrantClient(
    url="http://localhost:6333",
    api_key="your_strong_secret_key",  # 如启用
    prefer_grpc=True  # 更高性能（需开放 6334）
)

# 创建 collection
client.create_collection(
    collection_name="articles",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
    # 可选：启用 payload 索引
    hnsw_config={"m": 16, "ef_construct": 100}
)

# 插入向量
points = [
    PointStruct(
        id=1,
        vector=[0.1, 0.9, ...],  # 1536 维
        payload={"title": "AI RAG", "author": "Qwen"}
    )
]
client.upsert(collection_name="articles", points=points)

# 搜索
search_result = client.search(
    collection_name="articles",
    query_vector=[0.2, 0.8, ...],
    query_filter={"must": [{"key": "author", "match": {"value": "Qwen"}}]},
    limit=3
)
print(search_result[0].payload)

✅ 安装：pip install qdrant-client

2. LangChain 集成（RAG 场景）

from langchain_qdrant import Qdrant
from langchain_openai import OpenAIEmbeddings

vector_store = Qdrant(
    client=QdrantClient(url="http://localhost:6333", api_key="..."),
    collection_name="my_docs",
    embeddings=OpenAIEmbeddings(),
)

# 构建 RAG Chain
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI

retriever = vector_store.as_retriever(search_kwargs={"k": 4})
prompt = ...  # 你的 prompt 模板
llm = ChatOpenAI()

rag_chain = (
    {"context": retriever, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

print(rag_chain.invoke("什么是 Qdrant？"))

⚙️ 六、性能调优建议（生产必备）

场景	推荐配置
高精度召回	hnsw.m=24, hnsw.ef_construct=200, ef=256
低内存占用	启用 quantization.scalar.type=int8
大吞吐写入	write_batch_size=1000, 异步批量 upsert
冷热分离	使用 on_disk: true 存储向量（v1.9+）
混合搜索	为 payload 字段创建索引：client.create_payload_index(…)

示例：创建 payload 索引加速过滤

client.create_payload_index(
    collection_name="articles",
    field_name="category",
    field_schema="keyword"
)

🛠 七、常见问题排查

❌ 问题1：Connection refused

• 检查端口是否开放：netstat -tuln | grep 6333
• Docker 是否正确映射端口

❌ 问题2：403 Forbidden

• 未提供 API Key 或 Key 错误
• 检查 Header：Authorization: Bearer

❌ 问题3：插入慢 / 内存爆炸

• 关闭 optimizers 自动优化（大批量导入时）：

optimizers:
  default:
    disabled: true

• 导 入完成后手动触发优化：

curl -X POST http://localhost:6333/collections/my_col/optimize

❌ 问题4：集群无法加入

• 检查 P2P_PORT 是否互通（默认 6335）
• 所有节点 HOSTS 列表必须完全一致

📚 八、官方资源

• 官网：https://qdrant.tech
• 文档：https://qdrant.tech/documentation/
• GitHub：https://github.com/qdrant/qdrant
• Playground（在线体验）：https://playground.qdrant.tech

✅ 总结：

Qdrant 是当前 RAG 场景下性能与易用性平衡最佳的开源向量数据库之一。

• 开发测试 → Docker 单机
• 中小生产 → 单机 + API Key + 快照备份
• 大规模高可用 → Kubernetes 集群 + 监控 + 量化压缩