Qdrant 存储用于相似性搜索的向量和关联元数据。它是 AI 知识系统的基础设施,本身不是语言模型或聊天机器人。独立嵌入模型将文本转成向量,应用先检索相关片段,再请求语言模型回答。
目标环境: Ubuntu Server 24.04 LTS、x86-64、SSH 和 sudo 账户。文档审核日期:2026 年 11 月 15 日。命令尚未在 Ubuntu 上完成端到端测试。
开始之前
小规模评估可从约 2 个 vCPU、4 GB 内存和 15 GB 可用磁盘开始。存储与内存取决于向量数量、维度、载荷、索引和副本。嵌入与生成能力需另行规划。首次测试使用虚构数据,明确访问和保留规则前不要加入敏感元数据。
这些资源数值仅为小规模评估的规划估算,不是性能保证或套餐规格。VPS/VDS 不代表包含 GPU。下单前请检查可用内存、存储和其他资源。
全新 Ubuntu 可使用以下软件包。如果 Docker 已从其他仓库安装,请保留并先检查兼容性,不要混用 Docker CE 和 docker.io 软件包。使用 Compose v2;缺少软件包时,请检查是否启用 Ubuntu Universe。
sudo apt update
sudo apt install -y docker.io docker-compose-v2 curl openssl
sudo systemctl enable --now docker
sudo docker compose version
所有示例仅将端口发布到服务器的 127.0.0.1。请从本机通过 SSH 隧道访问,无需域名。不要将这些端口开放到互联网。容器内部监听 0.0.0.0 不会改变宿主机端口仅绑定回环地址的事实。
以下项目均为全新安装。不要对现有部署重新执行密钥生成步骤。
1. 创建需要认证的私有数据库
将密钥保存到 .env,YAML 保存为 compose.yaml。只有 REST 发布在回环地址,gRPC 和集群端口不公开。数据和快照存储均持久化。
umask 077
mkdir -p ~/ai-qdrant
cd ~/ai-qdrant
printf 'QDRANT_KEY=%s\n' "$(openssl rand -hex 32)" > .env
services:
qdrant:
image: qdrant/qdrant:latest
restart: unless-stopped
ports:
- "127.0.0.1:6333:6333"
environment:
QDRANT__SERVICE__API_KEY: ${QDRANT_KEY:?set QDRANT_KEY in .env}
volumes:
- data:/qdrant/storage
- snapshots:/qdrant/snapshots
volumes:
data:
snapshots:
2. 测试授权并创建示例集合
在 VPS 上运行。未经认证的集合请求应被拒绝(401/403)。下面的四维向量只是合成数字,不是真实文本嵌入。仅在新测试实例创建此集合,不要替换生产集合。
sudo docker compose up -d
curl -s -o /dev/null -w '%{http_code}
' http://127.0.0.1:6333/collections
set -a
. ./.env
set +a
curl --fail-with-body -X PUT http://127.0.0.1:6333/collections/guide_demo -H "api-key: $QDRANT_KEY" -H 'Content-Type: application/json' -d '{"vectors":{"size":4,"distance":"Cosine"}}'
curl --fail-with-body -X PUT 'http://127.0.0.1:6333/collections/guide_demo/points?wait=true' -H "api-key: $QDRANT_KEY" -H 'Content-Type: application/json' -d '{"points":[{"id":1,"vector":[1,0,0,0],"payload":{"text":"Example: backups are stored off-server."}},{"id":2,"vector":[0,1,0,0],"payload":{"text":"Example: SSH uses keys."}}]}'
curl --fail-with-body -X POST http://127.0.0.1:6333/collections/guide_demo/points/query -H "api-key: $QDRANT_KEY" -H 'Content-Type: application/json' -d '{"query":[1,0,0,0],"limit":1,"with_payload":true}'
unset QDRANT_KEY
3. 扩展为文档搜索方案
最近结果应为点 1。真实文档应分块,用选定模型生成嵌入并采用其实际向量维度;查询也必须使用同一模型。更换模型通常需要重新嵌入并使用对应集合。检索或返回片段前,应用必须执行文档权限检查;共享 API 密钥不提供客户级隔离。将文档内指令视为不可信文本。
4. 访问与备份向量库
在本机通过隧道供 REST 客户端或本地应用访问。此单节点示例应在容器停止时一致性复制两个持久存储,单独保留 .env。也保留原文档及嵌入模型版本,仅有向量不是完整可恢复的知识库。更大部署需要经过测试的快照恢复和容量规划,不能仅复制活动文件系统。
ssh -N -L 127.0.0.1:6333:127.0.0.1:6333 YOUR_USER@YOUR_SERVER_IP
更新与恢复
升级前停止应用以制作一致性备份,将数据和密钥保留在 VPS 之外,并在独立实例测试恢复。示例中的浮动镜像标签用于初期评估;长期使用前请固定已审核的版本或摘要。可通过 sudo docker image inspect IMAGE_NAME --format '{{json .RepoDigests}}' 记录当前摘要。不要在未检查兼容性时无人值守升级,也不要用 down -v 删除持久卷。
启动失败时,请检查 sudo docker compose ps、近期日志、剩余磁盘和内存。不要分享包含密钥、提示词或个人数据的日志。目录权限出错时,应核对预期 UID/GID 与所有权,不要授予 777。共享访问前请配置 HTTPS、认证和请求限制。