qmd 本地 GPU 或 CPU 后端怎么选：QMD_LLAMA_GPU、--no-gpu 与 QMD_FORCE_CPU

qmd 本地 GPU 或 CPU 后端怎么选：QMD_LLAMA_GPU、--no-gpu 与 QMD_FORCE_CPU

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd

qmd 是一个完全本地运行的 CLI 文档搜索引擎，它的向量化（embedding）与重排序（rerank）由 llama.cpp 完成。默认情况下 qmd 会自动探测可用的 GPU 后端（Metal / Vulkan / CUDA），探测失败才回退 CPU。但在实际使用中有几类典型情况：机器上没有可用的 GPU 驱动，自动探测选错了后端，或者你希望 JSON 输出不被 llama.cpp 的原生日志干扰——这时需要手动干预。qmd 提供三个对应的开关：QMD_LLAMA_GPU、QMD_FORCE_CPU，以及等价的命令行参数--no-gpu。本文说明这三个开关各自解决什么问题、怎么设置，以及如何用qmd doctor和qmd status验证生效结果。

三个开关各管什么

qmd 的环境变量说明（见 README.md 的 Environment Variables 一节）中，与 GPU/CPU 选择直接相关的有三项：

三者职责不同，对应不同的使用场景：

• QMD_LLAMA_GPU=metal|vulkan|cuda：机器上有 GPU，但你想跳过自动探测、直接锁定某个后端。适用于 auto 选择结果不符合预期、或多 GPU 环境下需要明确指定后端的情况。
• QMD_FORCE_CPU=1或--no-gpu：完全绕过 CUDA/Vulkan/Metal 探测，直接进入 CPU 模式。适用于没有 GPU 的机器（CI 容器、服务器、无独立显卡的环境），以及需要保持 JSON 输出可解析的场景——按 CHANGELOG.md 记录，--no-gpu同时会把 llama.cpp 的原生 stdout 噪声路由到 stderr，避免污染 search/query 命令的 JSON 输出。
• QMD_LLAMA_GPU=false：只禁用 GPU 但不需要--no-gpu的完整语义时可选；注意它仍然会走解析逻辑（见下文"无效值会回退 auto"）。

优先级关系：QMD_FORCE_CPU优先于QMD_LLAMA_GPU。从实现（src/llm.ts 的resolveLlamaGpuMode）可以看到，QMD_FORCE_CPU先被检查，命中即返回 CPU 模式，QMD_LLAMA_GPU不再参与。

怎么选：按机器情况定后端

先跑一次默认流程，看它选了什么。不做任何设置时QMD_LLAMA_GPU为auto，qmd 自动探测。用诊断命令确认探测结果：

# Diagnose the install (runtime, sqlite-vec, embedding fingerprints, GPU probe) qmd doctor

qmd doctor的输出包含 GPU probe 结果（见 README.md 的 Index Maintenance 一节）。同时qmd status会显示 GPU mode/configuration，但它默认跳过原生设备探测以保证安全；如果 CPU-fallback 警告指向真实后端探测，按提示执行：

QMD_STATUS_DEVICE_PROBE=1 qmd status

Windows + CUDA 的已知坑。如果你遇到 CUDA 并行上下文崩溃（ggml-cuda.cu:98），README 给出的处理方式是：QMD_EMBED_PARALLELISM在 Windows CUDA 下默认为1，因为并行 CUDA 上下文可能崩溃；改用 Vulkan（QMD_LLAMA_GPU=vulkan）或仅在驱动稳定时调高并行度：

export QMD_LLAMA_GPU=vulkan # 或在驱动稳定后： export QMD_EMBED_PARALLELISM=2 # 取值范围 1-8

无 GPU 或不想探测时强制 CPU：

export QMD_FORCE_CPU=1 # 或者只在单条命令上生效： qmd query "你的查询" --no-gpu

--no-gpu的实现就是在启动时把process.env.QMD_FORCE_CPU置为"1"（见 src/cli/qmd.ts 中if (values["no-gpu"])分支），两者效果完全一致；区别只是环境变量全局生效、参数只对当前命令生效。

如何验证设置已生效

1. 看警告信息。后端选择和回退都会在 stderr 留下明确的QMD Warning:，这些是判断配置是否按预期工作的一手依据（均来自 src/llm.ts 实际输出）：

# 无效值回退 auto QMD Warning: invalid QMD_LLAMA_GPU="opengl", using auto GPU selection. # 指定后端初始化失败，回退 CPU QMD Warning: GPU init failed for QMD_LLAMA_GPU=cuda (错误详情), falling back to CPU. # 同一进程内之前已失败的后端会跳过重复初始化 QMD Warning: skipping previously failed GPU init for QMD_LLAMA_GPU=cuda, using CPU.

如果你设置了QMD_LLAMA_GPU却看到invalid ... using auto GPU selection，说明值写错了——该变量只接受metal、vulkan、cuda、false（以及off/none/disable/0等关闭取值）。

2. 用qmd doctor复核。在 CI 或容器中，仓库自身的测试流程（见 test/smoke-install.sh 与 CHANGELOG.md 相关条目）就是在自动模式与QMD_FORCE_CPU=1模式下分别跑 doctor 来确认安装状态，你可以照做：

qmd doctor QMD_FORCE_CPU=1 qmd doctor

3. 实际跑一次模型操作。后端选择影响的是qmd embed这类 llama.cpp 操作。改完后端设置后跑一次 embedding，配合上面的警告输出判断：没有GPU init failed警告、流程正常完成，说明所选后端在当前机器上可用；反之警告会直接指出是哪个后端初始化失败并回退到了 CPU。

边界与已知行为

• 回退是静默降级到 CPU，不是报错。GPU 初始化失败时 qmd 会继续用 CPU 完成操作，只发警告。也就是说"设了 GPU 后端"不等于"一定在用 GPU"，验证时应以警告输出和 doctor 结果为准。
• QMD_FORCE_CPU的取值语义：非空且不等于false/off/none/disable/disabled/0的值都会触发强制 CPU；--no-gpu等价于QMD_FORCE_CPU=1。
• 切换 GPU/CPU 后端不改变向量结果本身，只影响推理执行位置；文档中要求重新qmd embed的场景是更换 embedding 模型（QMD_EMBED_MODEL），与后端选择无关，两者不要混淆。

配置完成后，如果qmd doctor的 GPU probe 与你的预期一致、且 embedding 流程没有QMD Warning输出，后端选择就完成了。

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd