什么是 Qdrant？
做 AI 应用离不开向量搜索。Qdrant 是目前最流行的开源向量数据库之一，由 Rust 编写，性能强、接口友好。它支持余弦相似度、欧氏距离、点积等多种距离度量，自带过滤查询，还能和 LangChain、LlamaIndex 等框架无缝对接。
相比 PGVector、Milvus，Qdrant 的优势是轻量、单二进制部署简单、API 设计直观。本文教你用 Docker 五步搞定本地部署。
准备工作
你需要：
- 一台服务器（本地电脑或 VPS 均可，推荐 2 核 4GB）
- Docker 已安装（没装的话：
curl -fsSL https://get.docker.com | bash） - curl 工具（测 API 用）
如果服务器内存只有 1GB，用 Qdrant 时建议不开启 WAL 压缩和磁盘持久化，纯内存运行。
第一步：创建项目目录
mkdir -p ~/qdrant-data && cd ~/qdrant-data
把数据目录挂在宿主机上，这样容器重建也不会丢数据。
第二步：写 docker-compose.yml
version: "3.8"
services:
qdrant:
image: qdrant/qdrant:latest
container_name: qdrant
restart: unless-stopped
ports:
- "6333:6333"
- "6334:6334"
volumes:
- ./qdrant_data:/qdrant/data
- ./qdrant_snapshots:/qdrant/snapshots
environment:
- QDRANT__SERVICE__HTTP_PORT=6333
- QDRANT__SERVICE__GRPC_PORT=6334
- QDRANT__SERVICE__ENABLE_AUTH API_KEY=
healthcheck:
test: ["CMD-SHELL", "curl -sf http://localhost:6333/ || exit 1"]
interval: 10s
timeout: 5s
retries: 5
关键说明：
6333是 REST API 端口，前端和 curl 都走这里6334是 gRPC 端口，性能要求高的场景用qdrant_data目录持久化向量数据，qdrant_snapshots目录存快照- 如果不想暴露到公网，把端口改成本地映射
127.0.0.1:6333:6333
第三步：启动服务
docker compose up -d
启动后等几秒，检查健康状态：
docker compose ps
看到 healthy 状态就OK了。如果一直是 starting，查一下日志：
docker compose logs -f qdrant
第四步：创建集合，写入向量
Qdrant 的逻辑层次是：服务器 → 集合（Collection）→ 点（Point）。一个集合就是一个独立的向量索引。
用 curl 创建一个名为 my_rag 的集合，维度 768（和常见的 Embedding 模型对齐）：
curl -X PUT http://localhost:6333/collections/my_rag \
-H "Content-Type: application/json" \
-d '{
"vectors": {
"size": 768,
"distance": "Cosine"
}
}'
返回 {"result":true} 说明创建成功。
写入几条向量数据：
curl -X PUT http://localhost:6333/collections/my_rag/points \
-H "Content-Type: application/json" \
-d '{
"points": [
{
"id": 1,
"vector": [0.1] 768,
"payload": {"title": "什么是向量数据库"}
},
{
"id": 2,
"vector": [0.2] 768,
"payload": {"title": "RAG 原理入门"}
}
]
}'
注意：实际使用中向量是从 Embedding 模型生成的，这里演示用随机数代替。
第五步：向量搜索
搜索最相似的 3 条结果：
curl -X POST http://localhost:6333/collections/my_rag/points/search \
-H "Content-Type: application/json" \
-d '{
"vector": [0.15] 768,
"limit": 3,
"with_payload": true,
"with_vector": false
}'
返回结果包含每个点的相似度分数（score）和附加信息（payload），这就是 RAG 检索的核心接口。
验证部署成功
两种方式确认 Qdrant 跑起来了：
方式一：看健康检查
curl http://localhost:6333/collections/my_rag
返回集合信息就说明服务正常。
方式二：打开 Web UI
open http://localhost:6333/dashboard
浏览器会打开 Qdrant 的管理界面，可以直接在页面上创建集合、上传数据、执行搜索，适合调试。
常见问题
Q1：向量维度怎么选？
取决于你用的 Embedding 模型。text-embedding-ada-002 是 1536 维，bge-large 是 1024 维，bge-m3 是 1024 维。不确定就去查模型文档。
Q2：远程服务器怎么安全暴露？
不要直接把端口暴露到公网。用 Tailscale、Cloudflare Tunnel 或 Nginx 反向代理，配合 API Key 鉴权。
# 开启 API Key 鉴权
environment:
- QDRANT__SERVICE__API_KEY=your-secret-key
调用时带 Header：
curl -H "api-key: your-secret-key" http://your-server:6333/collections
Q3：数据丢了怎么办？
只要 qdrant_data 目录还在，重建容器数据就还在。定期备份这个目录：
tar czf qdrant-backup-$(date +%Y%m%d).tar.gz qdrant_data/
Q4：Qdrant 和 PGVector 怎么选？
Qdrant 专注向量搜索，性能强、功能全。PGVector 适合已经在用 PostgreSQL 的项目，不想多维护一个服务。两者可以结合使用——PG 存业务数据，Qdrant 存向量。
下一步
Qdrant 配好之后，接一个 Embedding 模型就能搭完整的 RAG 系统。推荐搭配 Ollama 跑本地 Embedding，或者直接用 OpenAI API 生成向量。配合之前的 Ollama 部署教程，本地 AI 检索管道就全了。
去试试你的第一个向量集合吧，遇到报错随时来问。