docmd-search · docmd search

面向文档的离线语义搜索引擎。向量嵌入在构建时使用 ONNX Runtime 在本地生成。浏览器客户端执行关键字匹配和整数向量余弦相似度计算——无需向云服务发送任何数据，也不向用户分发神经网络权重。

零配置 CLI

在任何目录中运行 npx docmd-search ./docs。开箱即用，无需设置、API 密钥或手动配置文件。

使用方式

docmd-search 既可以作为独立的命令行工具使用，也可以作为 docmd 文档站点的插件使用。

独立 CLI

运行 docmd-search ./my-folder 索引任何目录并直接在终端中搜索。添加 --ui 打开本地浏览器界面。

docmd 插件

在 docmd.config.js 中添加 semantic: true，以在构建站点时自动构建搜索索引。

架构概览

构建阶段 (Node.js)                      搜索阶段 (浏览器, <3KB)
───────────────────                     ──────────────────────────
 爬取 Markdown 文件                      加载 manifest.json
   → 标题感知切分                          → 加载 batches/000.json (立即搜索)
     → ONNX 向量嵌入                         → 在后台加载其余批次
       → Float32 → Int8 量化                 → BM25 关键字 + 余弦相似度打分
         → 积 / 三进制压缩                     → 显示排序后的搜索结果
           → 保存索引文件 (_docmd-search/)

在构建阶段，嵌入向量由你的计算机上的 ONNX Runtime 计算。浏览器客户端接收预先计算好的整数向量，并在本地计算词条匹配和向量得分。

核心特性

本地运行

所有向量嵌入均在本地使用 ONNX Runtime 生成。数据绝不出你的计算机，无需云端 API 密钥。

分批快速加载

首批索引加载完成后即可立即开始搜索。增量重新索引会检查修改时间，仅重新索引更改过的文件。

极小客户端运行时

浏览器运行时体积小于 3KB gzipped。运行时无需神经网络权重或沉重的 WASM 模块。

可断点续传构建

如果索引被打断，再次运行时将从上一个完成的批次恢复。输出的索引文件即使部分完成也可正常使用。

快速开始

独立 CLI

docmd 插件

# 全局安装
npm install -g docmd-search

# 安装嵌入依赖项（一次性设置）
npm install -g @huggingface/transformers onnxruntime-node

# 索引任何文件夹
docmd-search ./my-folder

# 启动浏览器预览
docmd-search ./my-folder --ui

# 在你的 docmd 项目仓库中
npm install docmd-search

在你的配置文件中启用语义搜索：

// docmd.config.js
export default {
  plugins: {
    search: {
      semantic: true,  // 激活 docmd-search 索引器
    }
  }
};

首次运行时，交互式提示将协助你选择嵌入模型。你的文档将被爬取，按标题切分为章节，生成嵌入向量，并保存到 _docmd-search/。

文档目录

页面	说明
快速开始	安装、首次运行与模型选择
配置说明	全局、项目与命令行配置选项
工作原理	架构、切分、量化与混合打分
CLI 命令行参考	命令行选项、Flag 与退出代码
程序化 API	用于自定义构建脚本的 Node.js API 方法
浏览器客户端	浏览器客户端集成 API 与打分逻辑

系统架构

docmd-search 和 docmd 是独立的工具，旨在无缝协同工作：

┌─────────────────────────────────────────────────────────────────────┐
│                        docmd-search (独立)                           │
│                                                                     │
│  CLI → 索引目录 → _docmd-search/ 批次 → 终端搜索                     │
│                              │                                      │
│                              │ --ui Flag                            │
│                              ▼                                      │
│                    启动 docmd 预览服务器                              │
│                    (docmd 负责托管 Web UI)                          │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                        docmd (文档引擎)                             │
│                                                                     │
│  配置 → 构建站点 → plugin-search 执行                                │
│                              │                                      │
│                              │ semantic: true                       │
│                              ▼                                      │
│                    运行 docmd-search 索引器                         │
│                    (生成 _docmd-search/ 资源包)                     │
└─────────────────────────────────────────────────────────────────────┘

当使用 --ui Flag 独立运行时：

docmd-search 构建搜索索引。
它生成指向 _docmd-search/ 的临时 docmd 配置。
它启动 docmd 作为本地预览服务器来显示搜索 UI。

当作为插件使用时 (semantic: true)：

docmd 在构建站点期间导入 docmd-search。
索引器将多批次 JSON 文件写入输出构建目录下的 _docmd-search/。
浏览器客户端直接搜索这些预构建的索引文件。