qmd-extended

name

qmd-extended

description

Extended QMD knowledge base with multi-backend embedding (Google AI Studio / Ollama / local). Use when managing QMD embeddings, switching backends, testing embedding quality, re-indexing, or troubleshooting QMD vector search. Triggers on "qmd embed", "embedding backend", "切换embedding", "embedding测试", "re-embed", "知识库embedding", "qmd扩展". For general QMD queries and knowledge retrieval, use memory-router skill instead.

QMD Extended — Multi-Backend Embedding Manager

Architecture

QMD's llm.js is patched (v2) to support three embedding backends:

QMD_EMBED_BACKEND=google|ollama|local

google  → Google AI Studio gemini-embedding-001 (3072-dim, free)
ollama  → Mac Studio Ollama qwen3-embedding:8b (4096-dim, LAN)
local   → node-llama-cpp embeddinggemma-300M (768-dim, CPU)

Auto-detect priority: google → ollama → local

Quick Commands

Test current backend

bash ~/clawd/skills/qmd-extended/scripts/embed-test.sh        # test current
bash ~/clawd/skills/qmd-extended/scripts/embed-test.sh all     # test all backends
bash ~/clawd/skills/qmd-extended/scripts/embed-test.sh google "自定义文本"

Switch backend

bash ~/clawd/skills/qmd-extended/scripts/embed-switch.sh google   # switch to Google
bash ~/clawd/skills/qmd-extended/scripts/embed-switch.sh ollama   # switch to Ollama
# ⚠️ After switching: qmd embed -f  (required — dimensions change)

Check status

bash ~/clawd/skills/qmd-extended/scripts/embed-status.sh

Environment Variables

Var	Default	Purpose
QMD_EMBED_BACKEND	auto	Force backend: google/ollama/local
QMD_GOOGLE_EMBED_KEY	via pass	Google API key (auto-read from pass store)
QMD_GOOGLE_EMBED_MODEL	gemini-embedding-001	Google model name
QMD_OLLAMA_EMBED_URL	—	Ollama host (e.g. http://100.65.110.126:11434)
QMD_OLLAMA_EMBED_MODEL	qwen3-embedding:8b	Ollama model name

Patch Location

/home/aa/.npm-global/lib/node_modules/@tobilu/qmd/dist/llm.js
Backup: llm.js.bak (original pre-patch)

⚠️ npm update @tobilu/qmd will overwrite the patch. Re-apply from backup or re-run the patch script.

Backend Details

See references/backends.md for API docs, dimensions, rate limits, and comparison table.

Re-Embedding Workflow

When switching backends or after fresh install:

# 1. Switch backend
export QMD_EMBED_BACKEND=google

# 2. Force re-embed all collections
qmd embed -f

# 3. Verify
qmd status
bash ~/clawd/skills/qmd-extended/scripts/embed-status.sh

Troubleshooting

Issue	Fix
qmd embed hangs at compile	First run builds node-llama-cpp. Wait ~10 min. Only affects local backend.
Google embed error: 429	Rate limit hit. Wait 60s or reduce batch size.
Ollama embed: offline	Mac Studio sleeping. Wake it or switch to google.
Dimension mismatch in search	Backend changed without re-embed. Run qmd embed -f.
pass: api/google-ai-studio not found	Set QMD_GOOGLE_EMBED_KEY env var directly instead.