QMD Extended 是面向 QMD 知识库的多后端嵌入管理器。其核心做法是对 QMD 的 llm.js 打补丁（v2），使其支持三种嵌入后端，并通过脚本与环境变量进行管理。
用途 用于管理 QMD 的嵌入后端，包括测试当前后端、切换后端以及查看后端状态。当需要在不同嵌入来源之间切换，或验证某个后端是否可用时使用。
主要能力 支持三种嵌入后端，通过环境变量 QMD_EMBED_BACKEND 选择：
- google：Google AI Studio 的 gemini-embedding-001，3072 维，免费。
- ollama：Mac Studio 上的 Ollama qwen3-embedding:8b，4096 维，局域网。
- local：node-llama-cpp 的 embeddinggemma-300M，768 维，CPU。 自动检测优先级为 google → ollama → local。
使用方式 测试当前后端： bash ~/clawd/skills/qmd-extended/scripts/embed-test.sh 测试所有后端： bash ~/clawd/skills/qmd-extended/scripts/embed-test.sh all 测试指定文本： bash ~/clawd/skills/qmd-extended/scripts/embed-test.sh google "自定义文本"
切换后端： bash ~/clawd/skills/qmd-extended/scripts/embed-switch.sh google bash ~/clawd/skills/qmd-extended/scripts/embed-switch.sh ollama 注意：切换后必须执行 qmd embed -f，因为维度会变化。
查看状态： bash ~/clawd/skills/qmd-extended/scripts/embed-status.sh
环境变量
- QMD_EMBED_BACKEND：默认 auto，用于强制指定后端 google/ollama/local。
- QMD_GOOGLE_EMBED_KEY：默认通过 pass 读取，Google API 密钥（自动从 pass 存储读取）。
- QMD_GOOGLE_EMBED_MODEL：默认 gemini-embedding-001，Google 模型名称。
- QMD_OLLAMA_EMBED_URL：Ollama 主机地址（例如 http://100.65.110.126:11434）。
- QMD_OLLAMA_EMBED_MODEL：默认 qwen3-embedding:8b，Ollama 模型名称。
补丁位置 /home/aa/.npm-global/lib/node_modules/@tobilu/qmd/dist/llm.js 备份：llm.js.bak（打补丁前的原始文件）。 注意：npm update @tobilu/qmd 会覆盖补丁，需要从备份重新应用或重新运行补丁脚本。
重新嵌入工作流 切换后端或全新安装后：
- 切换后端：export QMD_EMBED_BACKEND=google
- 强制重新嵌入所有集合：qmd embed -f
- 验证：qmd status 以及 bash ~/clawd/skills/qmd-extended/scripts/embed-status.sh
适用场景 适用于需要管理 QMD 嵌入、在不同嵌入后端之间切换、测试嵌入连通性，以及排查嵌入相关问题的场景。
限制与注意事项
- 切换后端后必须重新嵌入，否则搜索会出现维度不匹配。
- npm 更新 @tobilu/qmd 会覆盖补丁。
- 常见问题：qmd embed 在编译阶段卡住（首次运行会构建 node-llama-cpp，约需 10 分钟，仅影响 local 后端）；Google 嵌入报 429（触发速率限制，等待 60 秒或减小批量）；Ollama 嵌入离线（Mac Studio 休眠，唤醒或切换到 google）；pass: api/google-ai-studio 未找到（改为直接设置 QMD_GOOGLE_EMBED_KEY 环境变量）。
- 各后端的 API 文档、维度、速率限制与对比表见 references/backends.md。