Qdrant：高性能开源向量数据库（RAG/Agent 记忆底座）｜部署与使用全指南
本文基于 Qdrant 官方 GitHub README、官方文档（qdrant.tech/documentation）以及项目近期发布动态撰写，反映当前真实状态。文中所有命令、参数与配置项均来自官方资料；示例覆盖 Docker、二进制、Kubernetes 与源码编译四种部署形态。
一、项目简介与适用场景
Qdrant（读作 "quadrant"）是一个用 Rust 编写的高性能、大规模向量相似度搜索引擎与向量数据库。它提供生产可用的服务与便捷 API，用于存储、检索和管理 points（向量 + 附加 payload），并针对"扩展过滤（extended filtering）"做了深度优化，非常适合基于神经网络 / 语义匹配的检索、分面搜索等场景。
它把 embeddings 或神经网络编码器直接转化为可落地的应用：匹配、搜索、推荐等。项目同时提供全托管的 Qdrant Cloud（含免费额度），但本文聚焦开源自建部署。
活跃度与版本状态（截至 2026-10）
典型适用场景
RAG（检索增强生成）：作为 LLM 的外挂知识库检索底座，把文档切片向量化后存入 Qdrant，按语义召回最相关片段。
Agent 记忆（Memory）：存储对话历史、用户偏好、工具调用记录的 embedding，实现长期记忆的相似检索与去重。
语义搜索（Semantic Search）：替代关键词匹配，理解查询意图返回相关结果。
推荐系统：基于实时相似度匹配做个性化推荐（商品、内容、相似项）。
多模态检索：文本 + 图像联合检索、视频片段索引。
异常检测 / 数据分析：在高维数据中找出偏离正常模式的离群点。
二、核心功能逐条拆解
其他亮点特性
分面（Faceting）：按 payload 值聚合检索结果。
推荐（Recommendation）：用正负样本找相似点。
发现（Discovery）：把搜索约束在向量空间的特定区域。
检索相关性调优：MMR（最大边际相关）、相关性反馈查询等。
多租户（Multitenancy）：可扩展的数据分区，适合多用户环境。
可观测性（Observability）：完善的 metrics、telemetry、审计日志。
查询规划与 Payload 索引：利用 payload 信息优化查询执行策略。
SIMD 硬件加速：利用 x86-x64（AVX）与 ARM（Neon）指令集提升性能。
GPU 支持：支持 NVIDIA / AMD GPU 加速建索引（可选，非必需）。
异步 I/O：在 Linux 上使用
io_uring最大化磁盘吞吐。预写日志（WAL）：即便断电也能通过更新确认保证数据持久性。
Qdrant Edge：轻量嵌入式版本，进程内检索，适用于机器人 / 自助终端 / 移动端离线场景。
三、全套官方链接
四、硬件与环境前置要求
支持的操作系统与 CPU 架构
内存（RAM）
Qdrant 所需 CPU 与内存取决于：向量数量、向量维度、payload 及其索引、存储方式、复制因子、量化配置。
默认情况下向量常驻内存以获得最佳性能；开启 量化（Scalar/Binary/Product） 后 RAM 最高可降 97%。
把向量 / HNSW 索引 / payload 配置为
on_disk（或memory: cold）可进一步用磁盘换内存，但需 SSD/NVMe。官方提供 Cloud Pricing Calculator 做资源估算（不含 payload / 索引数据时）。
是否需要 GPU
不需要 GPU。CPU（开启 SIMD：x86 AVX、ARM Neon）即可获得高性能。
仅当希望加速建索引时，可选启用 NVIDIA / AMD GPU 支持（属于可选增强，非部署前提）。
存储（磁盘）
持久化存储需要 POSIX 兼容的块级文件系统（如 ext4、xfs、APFS、本地 SSD/NVMe）。
❌ 不支持网络文件系统（NFS 等）与对象存储（S3 等）作为主存储；但 S3/GCS/Azure 可作为快照远端备份目标。
向量卸载到本地磁盘时，强烈建议使用 SSD 或 NVMe。
Collection 维度建议
向量维度 size 必须与所用 embedding 模型输出维度严格一致，否则插入会报维度不匹配错误。常见参考：
建议：原型阶段小维度（384/768）足够；生产按所选模型固定即可，无需"越大越好"，维度越大内存与计算成本越高。
端口
五、多平台部署实战
默认数据目录在容器内为
/qdrant/storage。生产环境务必挂载持久卷 + 配置安全项（见第六章、第七章）。
5.1 Docker（最推荐的开发 / 测试方式）
拉取镜像：
docker pull qdrant/qdrant
最简启动（默认配置，无鉴权，仅本地测试）：
docker run -p 6333:6333 -p 6334:6334 \
-v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
qdrant/qdrant
启动后访问：
REST API：
http://localhost:6333Web UI（Dashboard）：
http://localhost:6333/dashboardgRPC：
http://localhost:6334
Windows 上若 bind mount 本地目录出现文件系统问题，请改用命名卷：
docker volume create qdrant-storage然后-v qdrant-storage:/qdrant/storage。
5.2 Linux 预编译二进制
Qdrant 官方 Docker 镜像基于 Debian；如需裸二进制，可从 GitHub Releases 下载对应架构的预编译包，或自行编译（见 5.4）。
解压后直接运行（数据目录默认 ./storage）：
./qdrant --config-path ./config/production.yaml
若无自定义配置，直接 ./qdrant 即可使用内置默认配置。建议用 systemd 托管（见第七章）。
5.3 Kubernetes（简述）
官方提供 Helm Chart（社区支持级别）。安装：
helm repo add qdrant https://qdrant.to/helm
helm install qdrant qdrant/qdrant
说明：Helm Chart 是社区支持的轻量部署方式，不具备 Qdrant Cloud / 企业 Operator 的零停机升级、自动再均衡、备份与灾难恢复等企业能力；分布式场景需自行配置负载均衡、持久卷（每个节点独立 PVC）、备份策略与监控。生产高可用建议使用 Qdrant Private Cloud 企业 Operator 或 Qdrant Cloud。
下图展示了"按时间分片（time-based sharding）"的分布式数据布局思路，便于理解分片在集群节点间的分布：
启用分布式（集群）模式的关键配置：
cluster:
enabled: true
# 首个节点声明自身可达地址
# 启动参数：./qdrant --uri 'http://qdrant_node_1:6335'
# 后续节点：./qdrant --bootstrap 'http://qdrant_node_1:6335'
集群通过 Raft 共识维护拓扑与集合结构一致性；用 GET /cluster 可查看 raft_info（term / commit / leader / role）。
5.4 源码编译（Rust）
适合需要针对特定 CPU 架构定制、或不希望使用 Docker 的场景。先安装 Rust 工具链与依赖（依赖项见仓库 Dockerfile），然后：
# 克隆
git clone https://github.com/qdrant/qdrant.git
cd qdrant
# 编译 release 二进制
cargo build --release --bin qdrant
# 产物路径
./target/release/qdrant
编译耗时较长（Rust 全量构建），建议在有充裕内存的机器上进行。
六、配置文件参数全解
现代 Qdrant 使用单一配置文件
config.yaml，内部以service:/storage:/tls:等顶层段落组织（早期版本曾拆分service.yaml与storage.yaml，现统一）。加载优先级（后者覆盖前者）：内置默认 →config/config.yaml→config/{RUN_MODE}.yaml→config/local.yaml→--config-path指定文件 → 环境变量（最高）。
6.1 Docker 运行参数（命令行 / 环境变量）
环境变量命名规则：QDRANT__ 前缀 + 双下划线 __ 表示嵌套。例如 QDRANT__SERVICE__API_KEY、QDRANT__LOG_LEVEL=INFO、QDRANT__SERVICE__ENABLE_TLS=true、QDRANT__TLS__CERT=./tls/cert.pem。
6.2 service: 段落（网络与鉴权）
v1.20.0 起：一旦配置了
api_key，enforce_internal_auth默认true，集群内部通信也强制鉴权。升级到 1.20.0 时，仅配置read_only_api_key或仅配置alt_api_key（且来自 v1.19.0/1.19.1）的集群会失联，需先设置api_key或显式enforce_internal_auth: false。
6.3 storage: 段落（数据与性能）
6.4 optimizers:（段优化）
6.5 hnsw_index:（HNSW 索引，可逐集合覆盖）
6.6 collection:（集合默认参数）
6.7 tls:（TLS 加密）
启用
enable_tls后，必须通过 TLS 终止或反向代理保护api_key传输；明文发送 API Key 是不安全的。
七、启动 / 后台常驻 / 开机自启 / 改端口
7.1 Docker 后台常驻 + 开机自启
docker run -d \
--name qdrant \
--restart unless-stopped \
-p 6333:6333 -p 6334:6334 \
-v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
qdrant/qdrant
-d：后台运行。--restart unless-stopped：Docker 守护进程启动时自动拉起，实现开机自启（需 Docker 本身开机启动）。
7.2 改端口
把宿主机端口映射到容器端口即可，例如改为 6338 / 6339：
docker run -d --name qdrant \
-p 6338:6333 -p 6339:6334 \
-v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
qdrant/qdrant
客户端连接时对应改为 http://localhost:6338。若需改容器内监听端口，则改配置 service.port / service.grpc_port 并相应调整 -p 映射。
7.3 systemd 托管（二进制部署，开机自启）
创建 /etc/systemd/system/qdrant.service：
[Unit]
Description=Qdrant Vector Database
After=network.target
[Service]
User=qdrant
Group=qdrant
WorkingDirectory=/opt/qdrant
ExecStart=/opt/qdrant/qdrant --config-path /opt/qdrant/config/production.yaml
Restart=on-failure
RestartSec=5
LimitNOFILE=10000
[Install]
WantedBy=multi-user.target
启用并启动：
sudo systemctl daemon-reload
sudo systemctl enable --now qdrant
# 查看状态 / 日志
sudo systemctl status qdrant
sudo journalctl -u qdrant -f
7.4 数据持久化要点
Docker：务必挂载
-v ...:/qdrant/storage，否则容器删除数据即丢失。备份策略、监控与负载均衡是生产必备（见第十章备份、第六章安全）。
八、功能实操教程
8.1 安装 Python 客户端
pip install qdrant-client
8.2 连接服务
from qdrant_client import QdrantClient
client = QdrantClient(url="http://localhost:6333")
# 若已开启鉴权：
# client = QdrantClient(url="http://localhost:6333", api_key="your_api_key_here")
8.3 创建 Collection
from qdrant_client.models import Distance, VectorParams
client.create_collection(
collection_name="test_collection",
vectors_config=VectorParams(size=4, distance=Distance.DOT),
)
size必须与后续插入向量的维度完全一致；distance可选Cosine/Euclid/Dot/Manhattan。
REST 等价（curl）：
curl -X PUT http://localhost:6333/collections/test_collection \
-H 'Content-Type: application/json' \
--data '{"vectors": {"size": 4, "distance": "Dot"}}'
8.4 插入向量（带 payload）
from qdrant_client.models import PointStruct
operation_info = client.upsert(
collection_name="test_collection",
wait=True,
points=[
PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Berlin"}),
PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={"city": "London"}),
PointStruct(id=3, vector=[0.36, 0.55, 0.47, 0.94], payload={"city": "Moscow"}),
PointStruct(id=4, vector=[0.18, 0.01, 0.85, 0.80], payload={"city": "New York"}),
PointStruct(id=5, vector=[0.24, 0.18, 0.22, 0.44], payload={"city": "Beijing"}),
PointStruct(id=6, vector=[0.35, 0.08, 0.11, 0.44], payload={"city": "Mumbai"}),
],
)
print(operation_info) # operation_id=0 status=COMPLETED
8.5 带过滤的相似搜索
from qdrant_client.models import Filter, FieldCondition, MatchValue
search_result = client.query_points(
collection_name="test_collection",
query=[0.2, 0.1, 0.9, 0.7],
query_filter=Filter(
must=[FieldCondition(key="city", match=MatchValue(value="London"))]
),
with_payload=True,
limit=3,
).points
print(search_result)
无过滤的基础搜索：
search_result = client.query_points(
collection_name="test_collection",
query=[0.2, 0.1, 0.9, 0.7],
with_payload=False,
limit=3,
).points
8.6 REST / Python 客户端小结
8.7 与 LangChain 集成（RAG 实战）
安装：
pip install langchain-qdrant qdrant-client langchain-openai
把文档写入 Qdrant 并构建检索器：
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document
from langchain_qdrant import QdrantVectorStore
from qdrant_client import QdrantClient
embeddings = OpenAIEmbeddings(model="text-embedding-3-small") # 1536 维
qdrant_client = QdrantClient(url="http://localhost:6333", api_key="your_api_key_here")
docs = [
Document(page_content="客服团队随时为您提供帮助。", metadata={"department": "support"}),
Document(page_content="新功能提升了搜索相关性与速度。", metadata={"department": "product"}),
Document(page_content="安全审计未发现严重漏洞。", metadata={"department": "security"}),
]
vector_store = QdrantVectorStore.from_documents(
documents=docs,
embedding=embeddings,
client=qdrant_client,
collection_name="langchain_demo",
# force_recreate=True, # 如需重建集合
)
# 相似检索
results = vector_store.similarity_search("用户如何获得帮助？", k=2)
for doc in results:
print(doc.page_content, doc.metadata)
接入已有集合（无需重复上传）：
from langchain_qdrant import QdrantVectorStore, RetrievalMode
from langchain_huggingface import HuggingFaceEmbeddings
embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-base-zh") # 768 维
vector_store = QdrantVectorStore.from_existing_collection(
embedding=embeddings,
collection_name="shared_docs",
url="http://localhost:6333",
api_key="your_api_key_here",
retrieval_mode=RetrievalMode.DENSE, # 或 HYBRID 做稠密+稀疏混合
)
retriever = vector_store.as_retriever(search_kwargs={"k": 5})
混合检索（Hybrid Search）：配合
FastEmbedSparse（如Qdrant/bm42-all-minilm-l6-v2-attentions）并设retrieval_mode=RetrievalMode.HYBRID，可同时用稠密向量与关键词（BM25/BM42）召回，再用 RRF/DBSF 融合。
九、全套报错故障排查（≥8 条）
1. 端口被占用（Address already in use）
现象：启动报错
error binding to 0.0.0.0:6333 ... address already in use。原因：宿主机已有进程占用 6333 / 6334 / 6335。
解决：换映射端口（
-p 6338:6333）或停掉占用进程；分布式请确保 6335 仅在集群内可达。
2. 内存不足 / OOM（Out of Memory）
现象：进程被 OOM Killer 杀掉、搜索变慢或启动失败。
原因：向量常驻内存，数据量大且未量化。
解决：开启量化（
quantization）或把向量 / HNSW 设为on_disk（memory: cold）；使用low_memory_mode: no_resident作为崩溃恢复旋钮；扩容 RAM。
3. 向量维度不匹配（Dimension mismatch）
现象：
BadRequest("Vector size mismatch")或插入返回 400。原因：插入向量的维度与集合创建时
size不一致。解决：核对 embedding 模型输出维度，重建集合使
size完全匹配（如 384 / 768 / 1536）。
4. 文件系统不兼容（Incompatible file system）
现象：日志
WARN ... HFS/HFS+ filesystem support is untested，甚至ERROR ... Filesystem check failed ... FUSE filesystems may cause data corruption，重启后向量变全零。原因：使用了非 POSIX 完全兼容的文件系统，常见于 Windows + WSL 的 bind mount 共享目录。
解决：改用 Docker 命名卷（
docker volume create qdrant-storage然后-v qdrant-storage:/qdrant/storage），或本地 Linux 原生文件系统（ext4/xfs）。严禁 NFS / 对象存储作主存储。
5. 打开文件数过多（Too many files open, OS error 24）
现象：日志
Error: Too many files open (OS error 24)。原因：集合段数多，单进程文件描述符上限过低。
解决：Docker 启动加
--ulimit nofile=10000:10000；非 Docker 执行ulimit -n 10000（须在启动 Qdrant 前）。
6. 快照 / WAL 错误（Can't open Collections meta Wal）
现象：分布式启动报错
Can't open Collections meta Wal: Os { code: 11, ... WouldBlock }。原因：同一份 WAL / 存储目录被多个 Qdrant 实例同时占用（如 K8s 多个 pod 共用同一 PVC）。
解决：每个节点必须有独立的存储目录 / 卷 / PVC；分布式部署不要把存储共享。
7. TLS 错误（证书 / 握手失败）
现象：客户端报
tls handshake/certificate verify failed/ 启用enable_tls后无法连接。原因：证书路径错误、证书与域名不匹配、或客户端未设
verify=False但使用了自签证书。解决：核对
tls.cert/tls.key路径与权限；内网自签证书客户端需关闭校验或注入 CA；务必在 TLS 保护下再传输api_key。
8. 鉴权失败（401 / Unauthorized）
现象：请求返回 401，提示需要
api-key头。原因：服务端已设
api_key但客户端未带、或 Key 错误；v1.20.0 起集群内部通信也默认强制鉴权。解决：请求头加
api-key: <KEY>或Authorization: Bearer <JWT>；分布式升级到 1.20.0 前请确保配置了api_key（而非仅read_only_api_key/alt_api_key），否则节点间失联。
9. 存储配额超限（HTTP 507 Insufficient Storage）
现象：写入返回 507
Disk usage is at 95% ... exceeding the configured limit of 90%。原因：节点配置了资源配额（
quotas），磁盘使用超阈值。解决：删除无用 points / 删除集合释放空间；扩容磁盘；或用
PUT /quotas调高max_disk_usage_percent。触发后需用量回落到"释放余量"以下才会恢复写入。
10. Python gRPC 客户端 multiprocessing 报错
现象：
StatusCode.UNAVAILABLE ... sendmsg: Socket operation on non-socket (88)。原因：
multiprocessing复制了 gRPC channel 共享同一 socket，父进程关闭后子进程用失效 socket。解决：设置
multiprocessing.set_start_method("forkserver")或"spawn"；或改用 REST / 异步客户端 / 客户端内置并行（upload_points）。
十、升级 / 回滚 / 卸载 教程
10.1 升级（建议先备份）
Docker：使用明确版本标签，避免盲目 :latest 跳多个大版本。
# 1) 先备份（见下）
# 2) 拉取目标版本
docker pull qdrant/qdrant:1.20.0
# 3) 停止并移除旧容器（数据卷保留）
docker stop qdrant && docker rm qdrant
# 4) 用相同 -v 映射重启新版本
docker run -d --name qdrant --restart unless-stopped \
-p 6333:6333 -p 6334:6334 \
-v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
qdrant/qdrant:1.20.0
官方建议逐版本升级（如 1.18 → 1.19 → 1.20），避免大跨度跳跃；分布式集群采用滚动升级（一次只重启一个 peer），实现零停机。
二进制 / systemd：编译或下载新版本二进制，替换后 sudo systemctl restart qdrant。
Kubernetes：helm upgrade qdrant qdrant/qdrant（社区 Chart，无自动零停机保障，需自行规划）。
10.2 数据备份（升级前必做）
快照（推荐）：通过 API 创建集合快照，可存本地或远端 S3/GCS/Azure。
curl -X POST http://localhost:6333/collections/test_collection/snapshots \
-H 'api-key: your_api_key_here'
整目录拷贝：直接复制
storage_path（默认./storage）所在卷 / 目录。配置
snapshots_config.snapshots_storage: s3可实现远端自动备份目标。
10.3 回滚
数据格式在相邻稳定版间通常向后兼容。回滚即用上一版本镜像标签 / 二进制重启，数据卷不变即可。
若曾跨多个大版本升级并触发索引格式变更，建议从升级前快照恢复，而非直接回退二进制。
分布式环境回滚同样采用滚动方式，并保证
api_key等安全配置一致。
10.4 卸载
Docker：
docker stop qdrant && docker rm qdrant
docker volume rm qdrant-storage # 同时删除数据卷（确认已备份！）
二进制 / systemd：
sudo systemctl disable --now qdrant
sudo rm /etc/systemd/system/qdrant.service
sudo rm -rf /opt/qdrant # 含二进制与配置（确认已备份 storage）
Kubernetes：
helm uninstall qdrant（PVC 默认保留，需手动清理）。
十一、商用许可与合规风险提示
许可
Qdrant 采用 Apache License 2.0，属于宽松开源许可，允许商用、修改、再分发，包括闭源商业产品集成。
主要义务：保留版权与许可证声明；若修改了带有声明/通知的文件，需保留这些声明；提供
NOTICE文件（如存在）；不主张商标（不得使用 Qdrant 名称/商标做背书）。Apache-2.0 自带专利授权条款，对商业使用友好，降低专利风险。
合规与数据安全风险提示
小结：Qdrant 开源版商用无任何许可障碍，但"默认不安全"是自建最大的合规陷阱——上线前请完成鉴权、网络隔离、TLS、备份四件套。
本教程基于 Qdrant 官方 GitHub README 与 qdrant.tech 官方文档撰写，命令与参数均来自官方资料，适用于 v1.20.x 系列。实际部署请以官方文档最新版本为准。