Mac下部署Qdrant向量数据库

- 十月 28, 2026

本方案采用 macOS 原生 ARM64 二进制部署，不需要 Docker、Colima 或虚拟机。

部署环境

免费 · 本地运行

操作系统	macOS
处理器	Apple Silicon M1–M5
数据库	Qdrant v1.20.0
安装方式	ARM64 原生二进制
REST API	127.0.0.1:6333
gRPC	127.0.0.1:6334
数据目录	~/qdrant/storage
Web 管理	/dashboard

一、创建安装目录

打开 Mac 终端。

先检查处理器架构：

uname -m

Apple Silicon 应返回：

arm64

创建 Qdrant 安装文件夹：

mkdir -p ~/qdrant
cd ~/qdrant

这里的 ~ 表示当前用户的主目录。在你之前的环境中对应：

/Users/zhang/qdrant/

二、下载 Qdrant 官方 ARM64 程序

这里统一使用已经在你的 Mac 上成功启动过的 v1.20.0 版本。

官方发布地址：

Qdrant v1.20.0 GitHub Releases

执行：

curl -fL --retry 5 \
  -o qdrant.tar.gz \
  https://github.com/qdrant/qdrant/releases/download/v1.20.0/qdrant-aarch64-apple-darwin.tar.gz

这是 Qdrant 官方发布的 macOS ARM64 版本。

GitHub

如果 GitHub 下载速度慢，也可以通过浏览器手动下载 qdrant-aarch64-apple-darwin.tar.gz，放入 ~/qdrant 文件夹。

验证文件完整性

下载完成后执行：

shasum -a 256 qdrant.tar.gz

Qdrant v1.20.0 ARM64 安装包的 SHA-256 应为：

531904e822050790bb8c1da6705f801ee48b91eb4c229d0d605ff06f6331b20a

如果哈希不一致，不要继续解压，应重新下载。

AIMap 智图

三、解压并设置运行权限

执行：

tar -xzf qdrant.tar.gz

设置可执行权限：

chmod +x qdrant

查看：

ls -lh qdrant

解压后应存在一个名为 qdrant 的可执行文件。

此时目录结构如下：

~/qdrant/
├── qdrant
└── qdrant.tar.gz

四、首次启动 Qdrant

确保当前位于安装目录：

cd ~/qdrant

执行：

QDRANT__SERVICE__HOST=127.0.0.1 ./qdrant

其中：

QDRANT__SERVICE__HOST=127.0.0.1：只允许本机访问。
./qdrant：运行当前目录下的数据库程序。

正常情况下，终端会出现类似日志：

Qdrant
Version: 1.20.0

Qdrant HTTP listening on 6333
Qdrant gRPC listening on 6334

Qdrant 官方支持通过 QDRANT__ 前缀的环境变量覆盖配置。

Qdrant

注意，这个终端会一直运行服务。不要关闭终端或按 Control + C，否则数据库会停止。

五、检查数据库是否正常运行

打开第二个终端，执行：

curl http://127.0.0.1:6333/

正常情况下会返回包含 Qdrant 版本信息的 JSON。

再检查集合：

curl http://127.0.0.1:6333/collections

如果暂时没有创建任何集合，应该返回类似：

{
  "result": {
    "collections": []
  },
  "status": "ok",
  "time": 0.0001
}

time 的数值仅为示例。

到这里，数据库服务已经部署成功。

六、解决 Web Dashboard 404 问题

这是你实际安装时遇到的关键问题。

你之前访问：

http://localhost:6333/dashboard

显示 HTTP 404，同时终端出现：

Static contents folder for Web UI './static' does not exist

原因是下载的 Qdrant 原生二进制包没有包含 Dashboard 的静态文件，需要单独下载官方 WebUI。

第 1 步：下载 WebUI 文件

在第二个终端执行：

cd ~/qdrant

下载：

curl -fL --retry 5 \
  -o dist-qdrant.zip \
  https://github.com/qdrant/qdrant-web-ui/releases/latest/download/dist-qdrant.zip

这是官方 WebUI 的发布资源，其打包过程会生成 dist-qdrant.zip。

GitHub

WebUI 官方项目：

qdrant/qdrant-web-ui

第 2 步：解压 WebUI

创建静态文件目录：

mkdir -p ~/qdrant/static

解压：

unzip -o dist-qdrant.zip -d ~/qdrant/static

发布包中通常包含一层 dist 目录，需要将其中的文件移到 static 根目录。

执行：

cd ~/qdrant

if [ -f static/dist/index.html ]; then
  cp -R static/dist/. static/
  rm -rf static/dist
fi

检查：

ls -l ~/qdrant/static/index.html

只要 index.html 存在，就说明页面入口文件已经就位。

第 3 步：重新启动数据库

回到第一个运行 Qdrant 的终端，按：

Control + C

然后重新启动：

cd ~/qdrant

QDRANT__SERVICE__HOST=127.0.0.1 ./qdrant

第 4 步：打开 Dashboard

Qdrant Web 管理页面

复制

http://127.0.0.1:6333/dashboard

浏览器在运行 Qdrant 的同一台 Mac 上打开。

如果仍然显示旧的 404，使用 Command + Shift + R 强制刷新，再确认 static/index.html 存在。

Qdrant Dashboard 可以管理 Collections、查看数据点并通过 Console 调用数据库 API。

Qdrant 向量数据库

七、最终的文件目录结构

完成部署后，建议保持如下结构：

/Users/zhang/qdrant/
│
├── qdrant                 # 数据库主程序
├── qdrant.tar.gz          # 安装压缩包，可归档
├── dist-qdrant.zip        # WebUI安装包，可归档
│
├── static/                # Dashboard 前端静态文件
│   ├── index.html
│   ├── assets/
│   └── ...
│
├── storage/               # 数据库实际存储目录
│   ├── collections/
│   └── ...
│
└── snapshots/             # 集合快照的默认目录

Qdrant 默认以当前工作目录为基准，使用 ./storage 保存数据库数据。

GitHub

因此，日常启动前应始终执行：

cd ~/qdrant

如果要备份数据库，建议使用 Qdrant 的快照机制，而不是直接复制正在写入的 storage 文件夹。

八、让 Qdrant 在 Mac 后台运行

前面的启动方式需要一直保持终端打开。如果希望关闭终端后 Qdrant 继续运行，可以使用 nohup。

首先停止当前前台 Qdrant 服务（Control + C），再执行：

cd ~/qdrant

nohup env QDRANT__SERVICE__HOST=127.0.0.1 \
  ./qdrant > qdrant.log 2>&1 &

echo $! > qdrant.pid

此后可以关闭终端窗口。

检查运行状态：

curl http://127.0.0.1:6333/collections

查看日志：

tail -f ~/qdrant/qdrant.log

停止后台服务：

kill "$(cat ~/qdrant/qdrant.pid)"

nohup 可以避免普通终端退出导致的挂断，但不负责 Mac 重启后的自动启动。

如果以后需要开机自动启动，可以进一步配置 macOS 的 launchd 服务。

九、创建适用于 EmbeddingGemma 2 的图片向量集合

你部署 Qdrant 的主要目的是保存 EmbeddingGemma 2 生成的 768 维图片向量。

可以直接创建一个集合。

打开新终端执行：

curl -X PUT \
  "http://127.0.0.1:6333/collections/photo_embeddings" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 768,
      "distance": "Cosine"
    }
  }'

创建成功后，在 Qdrant Dashboard 的 Collections 页面应该看到：

photo_embeddings

集合的主要参数：

参数	值
Collection 名称	`photo_embeddings`
向量维度	768
距离计算方式	Cosine
向量模型	EmbeddingGemma 2

以后可以在每张图片对应的数据点中保存图片路径、尺寸、文件哈希、向量，以及 Qwen3-VL 的描述或结构化分析结果。

注意：这一步只创建空集合，不会自动导入 Google Drive 里的照片或以前生成的 .npy 文件。导入需要另写一个迁移程序，但不必重新计算已经保存的图片向量。

十、常见问题排查

问题	原因及处理
`cd: no such file or directory`	先执行 `mkdir -p ~/qdrant`
`curl: (22) 404`	核对 GitHub 下载地址与发布版本
`Permission denied`	执行 `chmod +x qdrant`
`Address already in use`	6333 端口已有进程监听，检查是否已启动 Qdrant
Dashboard 返回 404	检查 `static/index.html`，重新启动
`Config file not found`	未提供自定义配置，通常不影响默认运行
`jemalloc ... pthread only`	macOS 上的提示，通常不妨碍运行
数据似乎消失	检查启动工作目录及对应的 `storage` 路径

如果端口被占用：

lsof -nP -iTCP:6333 -sTCP:LISTEN

可以查看到底哪个进程正在使用 6333 端口。

十一、部署完成后的管理命令

需求	命令
前台启动	`cd ~/qdrant && QDRANT__SERVICE__HOST=127.0.0.1 ./qdrant`
查看数据库 API	`curl http://127.0.0.1:6333/collections`
查看运行进程	`pgrep -fl qdrant`
查看后台日志	`tail -f ~/qdrant/qdrant.log`
查看数据占用	`du -sh ~/qdrant/storage`
打开管理页面	`http://127.0.0.1:6333/dashboard`

搜索此博客

弗兰克的小课桌