@gmvp3/qmd-chinese

v1.2.0

Published

2 months ago

Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking

0High
0Medium
0Low

markdown search fts full-text-search vector semantic-search sqlite bm25 embeddings rag mcp reranking knowledge-base local-ai llm

🐉 QMD-Chinese (QMD 中文语义版)

QMD-Chinese 是专为中文语境深度改造的本地 RAG (检索增强生成) 命令行检索引擎。本分支在原版的基础上，彻底重写了中文分词与分块逻辑，并全面替换了最顶尖的中文开源大模型，旨在为 OpenClaw 等 AI 代理提供最极致的本地中文私有知识库支持。

👏 特别鸣谢 (Credits)

本项目基于卓越的开源项目 [QMD (https://github.com/tobi/qmd)] 进行本地化改造。核心的 RRF (倒数秩融合) 排序算法、CLI 架构及底层的向量混合检索逻辑均归功于原作者的出色工作。本分支仅针对中文 NLP 场景与模型依赖进行了深度重构与优化。向原作者致以最诚挚的感谢！

🚀 核心特性与模型组合

摒弃了原版对英文主导模型的依赖，本分支使用了当前地表最强的本地中文处理流水线。同时本分支已开始同步 upstream v2.1.0 的关键能力，包括：

AST 感知代码切块: 支持 TypeScript/JavaScript、Python、Go、Rust 的函数/类级切块（--chunk-strategy auto）
Bench 基准评测: 新增 qmd bench <fixture.json> 用于量化检索质量
可点击搜索结果链接: 终端 TTY 下支持跳转到编辑器指定行
Collection 级模型配置: 支持在 index.yml 中按集合配置 embed / rerank / generate 模型
更稳的 Embedding / BM25 / 启动器修复: 吸收上游稳定性与跨平台改进

当前默认模型仍保持中文优化路线：

Query Expansion (查询前置扩写): Qwen2.5-1.5B-Instruct (极大提升中文口语化提问的命中率)
Embedding (向量嵌入): BGE-M3 (智源顶配多语言向量模型，支持超长上下文)
Reranking (重排模型): bge-reranker-v2-m3 (精准的二次语义排序)
优化中文语义理解:

💻 硬件与运行环境建议

⚠️ 【强烈警告】：非常不建议在常规 VPS (如 1核1G / 2核4G 的云服务器) 上运行本项目。 多模型并发推理会瞬间耗尽 VPS 的内存并导致进程被系统 OOM 杀掉。

推荐运行环境：

本地 PC 工作站 (Windows WSL2 或原生 Linux)
独立显卡： 强烈推荐配备 NVIDIA 独立显卡 (如 RTX 30系 / 40系 / 50系)。本项目底层依赖 node-llama-cpp，配置正确的 CUDA 加速后，检索与推理速度将有数十倍的提升。
网络需求： 必须具备外网访问能力以联网下载模型。请注意，普通的 proxy 环境变量对 Node.js 原生的 fetch 无效。在国内网络环境下，可以通过设置 Hugging Face 国内镜像来顺利下载模型。

🚀 模型下载与环境配置 (国内环境指南)

1. 设置镜像环境变量 在终端中执行以下命令（建议将其加入到 ~/.bashrc 或 ~/.zshrc 等配置文件中使其永久生效）：

export HF_ENDPOINT=https://hf-mirror.com

2. 触发模型自动下载 配置好镜像后，可以通过运行基础命令来触发依赖模型的自动下载：

触发下载向量模型 (Embedding)：
```
qmd embed
```
触发下载生成扩写模型 (Query Expansion)与重排模型 (Rerank)：
```
qmd query --rerank "测试查询"
```

3. 检查下载状态 在终端执行上述命令并等待下载完成后，你可以前往缓存目录检查。正常情况下，该目录下应当包含 3 个已经下载完毕的模型文件：

ls ~/.cache/qmd/models

📦 安装指南

由于包含原生编译模块，请确保你的系统已安装 Node.js (推荐 v20+) 以及 git。

执行以下命令全局安装：

npm install -g @gmvp3/qmd-chinese

⚙️ OpenClaw 集成与配置将 QMD-Chinese 作为 OpenClaw 的本地记忆后端，请在 OpenClaw 的 Settings -> Memory 中参考以下截图进行精确配置：

基础挂载设置

Memory Backend: 必须选择 qmd。

QMD Binary: 你在命令行输入qmd有效的话，默认为空就行

Include Default Memory: 开启 (绿色)。

qmd1

检索模式与记忆留存 QMD Search Mode: 必须选择 query (此模式才会触发 Qwen2.5 扩写流水线)。

QMD Session Indexing: 开启 (绿色)，允许索引日常对话。

QMD Session Retention (days): 强烈建议设置为 30 或 60 天，定期清理无用废话，保持向量数据库的信噪比。

qmd2

⚠️ 【重要配置警告】：防超时配置 由于本地大模型（Qwen/BGE）首次加载到显存需要 5-10 秒的冷启动时间，而 OpenClaw 默认搜索超时仅为 4 秒（4000ms）。如果不修改此项，100% 会触发 fetch failed 或 timeout 报错。 请务必修改 ~/.openclaw/openclaw.json，在 memory.qmd 配置项下增加 limits.timeoutMs，设置如下：

"memory": {
  "backend": "qmd",
  "qmd": {
    "limits": {
      "timeoutMs": 120000
    }
  }
}

🛠️ CUDA 硬件加速状态验证与排错安装完成后，在终端运行以下命令检查运行状态： qmd status

✅ 成功的状态：如果你看到 Device 区域显示 GPU: cuda (offloading: yes) 并且正确识别了你的显卡型号（如下图的 RTX 5070 Ti），说明 CUDA 加速已完美开启！

cuda

❌ 失败的排错指南：如果显示使用的是 CPU 或者提示缺少 CUDA，请检查以下几点：

Cmake 是否缺失：底层的原生模块需要编译环境。请在终端执行 sudo apt-get install cmake build-essential (Ubuntu/Debian) 来安装必备工具。

驱动与 Toolkit：确保 WSL2 或 Linux 系统内已正确安装 NVIDIA 驱动及 CUDA Toolkit。

耐心等待编译：第一次 npm install 时，底层的 llama.cpp 需要根据你的显卡架构实时编译 CUDA 驱动代码，这可能会消耗几分钟到十几分钟的时间，请耐心等待编译完成。

🚀 QMD MCPorter: 极速冷启动优化 (MCP 模式)

如果你在使用中发现每次检索都需要几秒钟来加载模型（即“冷启动”太慢），开启 QMD MCP (Model Context Protocol) 模式可以将 QMD 保持在后台运行，从而实现毫秒级的瞬间响应。

配置步骤：

安装 MCP 管理器 (MCPorter) 在终端执行以下命令：
```
npm install -g mcporter
```
将 QMD 注册为 MCP 服务 让 MCPorter 知道如何启动 QMD：
```
mcporter config add qmd --command "qmd mcp"
```
在 OpenClaw 中开启集成 进入 OpenClaw 的 Settings -> AI与代理 -> QMD MCPorter，按照下图配置开启两个关键选项：
- QMD MCPorter Enabled: 开启 (绿色)。
- QMD MCPorter Start Daemon: 开启 (绿色)。

qmd-mcporter

验证运行状态：

配置完成后，当你第一次触发检索任务，QMD 就会在后台作为守护进程常驻。你可以通过以下命令验证它是否正在运行：

ps aux | grep qmd

成功的标志：如果你在输出中看到了包含 qmd.js mcp 的进程，说明 MCP 模式已生效，从此告别模型加载等待！

# 预期输出示例：
openclaw  1234  0.5  2.1  ... node /usr/local/bin/qmd.js mcp

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme