问题

传统的全文搜索完全依赖于精确的关键词匹配。如果用户搜索“身份验证”，但页面仅使用“OAuth2”或“登录”等术语，标准关键词搜索引擎将无法找到它。这迫使撰写人员进行不自然的关键词堆砌，并在读者无法找到所需内容时使其感到沮丧。

为什么它很重要

现代开发人员期望能够理解意图、同义词和上下文的自然语言界面。实现服务器端语义搜索通常需要设置复杂的架构，如向量数据库（例如 Pinecone 或 pgvector）、托管模型并构建 API，这增加了维护开销和每月托管成本，并引入了安全和隐私问题。

方法

使用 docmd 原生的语义搜索插件。它采用高度优化的浏览器运行时，完全在客户端运行。它在构建时使用本地 Hugging Face 模型管道生成结构化的向量分块索引，然后使用混合 BM25 关键词频率和向量余弦相似度对匹配项进行重排序。没有任何数据会被发送到第三方 API。

实现

1. 在配置中启用语义搜索

在 docmd.config.json 中添加 search 插件选项。将 semantic 配置为 true 并启用 showConfidence，以在搜索结果中直观地展示语义匹配的置信度徽章：

{
  "plugins": {
    "search": {
      "semantic": true,
      "showConfidence": true
    }
  }
}

2. 选择正确的嵌入模型

docmd 既支持轻量级的仅限英语的模型，也支持全面的多语言模型。您可以使用 docmd-search --settings 更新模型配置，或进行显式定义：

3. 在 CI/CD 中预构建索引

为了避免用户首次加载时在浏览器中产生计算开销，请在构建或 CI/CD 流程中使用 CLI 预先生成搜索分块：

# 预构建语义搜索索引
npx docmd-search --build

# 随后运行 docmd 构建
npx @docmd/core build

这将在 .docmd-search/ 目录中生成高度优化的静态 Vecto-JSON 分块文件。当用户进行搜索时，客户端会在后台渐进式加载这些分块，从而使 UI 保持即时响应。

权衡

首次加载资源体积

客户端向量嵌入要求浏览器在首次搜索时下载 WebAssembly 运行时以及预训练 of ONNX 模型文件。尽管这些资源会被持久化缓存到浏览器的 Cache Storage 中，但在较慢的网络连接下，首次加载的搜索延迟可能会稍高（约 1-2 秒的延迟）。

搜索质量与传输体积

选择如 LaBSE 等较大的模型可提供出色的多语言质量，但会导致下载体积增加。对于标准的国际化文档网站，paraphrase-multilingual-MiniLM-L12-v2 模型是搜索精度与网络传输体积之间的推荐最佳平衡点。