CPU 环境下 QMD 安装 GGUF 模型

本文适用于 QMD（含 OpenClaw 使用的 QMD 记忆后端）在 CPU 模式或网络受限环境下，需手动安装本地 GGUF 模型时使用。

• 制定日期：2026-03-05

---

一、模型说明

QMD 通过 node-llama-cpp 加载三个本地 GGUF 模型，用于向量嵌入、重排序与查询扩展。首次使用时会从 HuggingFace 自动下载；若自动下载失败（如 ETIMEDOUT、ENETUNREACH）或需离线部署，可按本文手动下载并放入缓存目录。

1.1 模型列表与用途

模型	用途	约大小	HuggingFace 仓库
embeddinggemma-300M-Q8_0	向量嵌入	~300MB	ggml-org/embeddinggemma-300m-qat-q8_0-GGUF
qwen3-reranker-0.6b-q8_0	重排序	~640MB	ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF
qmd-query-expansion-1.7B-q4_k_m	查询扩展	~1.1GB	tobil/qmd-query-expansion-1.7B

1.2 缓存目录

• 若已设置 XDG_CACHE_HOME（如 OpenClaw 与 QMD 对齐时）：$XDG_CACHE_HOME/qmd/models/
• 否则：~/.cache/qmd/models/

手动安装时，请保证 QMD 实际使用的缓存目录 与下面操作一致（与运行 qmd status 时一致）。若 QMD 由 OpenClaw Gateway 调起，通常为：~/.openclaw/agents/main/qmd/xdg-cache/qmd/models/（或你实际使用的 agentId 对应路径）。

---

二、方式一：huggingface-cli 下载（推荐）

# 安装 HuggingFace CLI（若未安装）
pip install -U "huggingface_hub[cli]"

# 创建缓存目录
CACHE="$HOME/.cache/qmd/models"
# 若使用 OpenClaw 的 XDG 对齐，改为：
# STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
# CACHE="$STATE_DIR/agents/main/qmd/xdg-cache/qmd/models"
mkdir -p "$CACHE"
cd "$CACHE"

# 下载三个模型（需可访问 HuggingFace）
huggingface-cli download ggml-org/embeddinggemma-300m-qat-q8_0-GGUF --local-dir . --local-dir-use-symlinks False
huggingface-cli download ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF --local-dir . --local-dir-use-symlinks False
huggingface-cli download tobil/qmd-query-expansion-1.7B qmd-query-expansion-1.7B-Q4_K_M.gguf --local-dir . --local-dir-use-symlinks False

下载后确认目录内存在与仓库中一致的 .gguf 文件名（若 CLI 带子目录，把 .gguf 文件移到 $CACHE 根目录，或保持子目录结构并确保 QMD 能解析到该路径，以官方文档为准）。

---

三、方式二：浏览器或 wget/curl 直链下载

从浏览器或命令行下载下列文件，保存到上述 $CACHE 目录，文件名与下表一致。下表为官方下载地址（HuggingFace）：

保存文件名	直链（HuggingFace 官方）
embeddinggemma-300m-qat-q8_0.gguf	https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF/resolve/main/embeddinggemma-300M-Q8_0.gguf
qwen3-reranker-0.6b-q8_0.gguf	https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/resolve/main/qwen3-reranker-0.6b-q8_0.gguf
qmd-query-expansion-1.7B-Q4_K_M.gguf	https://huggingface.co/tobil/qmd-query-expansion-1.7B/resolve/main/qmd-query-expansion-1.7B-Q4_K_M.gguf

官方直链（可直接在浏览器打开或复制到 wget/curl）：

CACHE="$HOME/.cache/qmd/models"
mkdir -p "$CACHE"
cd "$CACHE"
wget -c "https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF/resolve/main/embeddinggemma-300M-Q8_0.gguf"
wget -c "https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/resolve/main/qwen3-reranker-0.6b-q8_0.gguf"
wget -c "https://huggingface.co/tobil/qmd-query-expansion-1.7B/resolve/main/qmd-query-expansion-1.7B-Q4_K_M.gguf"

中国大陆用户： 若访问 huggingface.co 较慢或不可达，可改用镜像站。下面将环境变量与下载命令放在一起，在同一终端中执行即可（环境变量供本终端内其它工具使用；持久生效可把 export 行写入 ~/.bashrc 或 ~/.zshrc）：

# 设置环境变量（中国大陆建议使用镜像）
export HF_ENDPOINT=https://hf-mirror.com

CACHE="$HOME/.cache/qmd/models"
mkdir -p "$CACHE"
cd "$CACHE"
wget -c "https://hf-mirror.com/ggml-org/embeddinggemma-300M-GGUF/resolve/main/embeddinggemma-300M-Q8_0.gguf"
wget -c "https://hf-mirror.com/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/resolve/main/qwen3-reranker-0.6b-q8_0.gguf"
wget -c "https://hf-mirror.com/tobil/qmd-query-expansion-1.7B/resolve/main/qmd-query-expansion-1.7B-Q4_K_M.gguf"

---

四、验证

# 确认 XDG 与 OpenClaw 一致（若用 OpenClaw 跑 QMD）
export XDG_CACHE_HOME="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/main/qmd/xdg-cache"
ls -la "$XDG_CACHE_HOME/qmd/models/"
# 或默认缓存
ls -la "$HOME/.cache/qmd/models/"

# 再运行 QMD 状态或一次查询，不应再触发模型下载
qmd status

若仍报「找不到模型」或自动下载，说明 QMD 使用的缓存路径与当前不一致，需根据 qmd status 或官方文档确认实际 XDG_CACHE_HOME 再放入对应目录。

---

五、CPU 模式安装后还需的配置

完成「安装 QMD（含 NODE_LLAMA_CPP_CUDA=false）」和「手动安装三个 GGUF 模型」后，无需再为 CPU 模式做额外系统配置（无需新增环境变量或系统服务配置）。只需确认：

项目	说明
OpenClaw 配置	若尚未配置 QMD 记忆后端，需在 openclaw.json 中设置 memory.backend: "qmd"、qmd.paths、qmd.limits 等，并重启 gateway。详见 OpenClaw 配置指南。
模型缓存路径一致	若 QMD 由 OpenClaw Gateway 调起，模型应放在 ~/.openclaw/agents/main/qmd/xdg-cache/qmd/models/（或你实际使用的 agentId 对应路径）；若之前放在 ~/.cache/qmd/models/，需将同一批 .gguf 拷贝到上述 xdg-cache 路径。

---

参考链接

说明	链接
QMD 官方仓库	https://github.com/tobi/qmd
node-llama-cpp CUDA 说明	https://node-llama-cpp.withcat.ai/guide/CUDA