Semantra

https://user-images.githubusercontent.com/306095/233867821-601db8b0-19c6-4bae-8e93-720b324dc199.mov

Semantra 是一款用于语义化文档搜索的多功能工具。它通过理解查询的含义来进行搜索，而不仅仅是基于文本匹配。

该工具运行在命令行界面，能够分析您计算机上指定的文本和 PDF 文件，并启动一个本地的 Web 搜索应用，供您交互式地查询这些文件。Semantra 的目标是让运行一个专门的语义搜索引擎变得简单、友好、可配置，并且私密安全。

Semantra 专为那些需要在海量信息中寻找关键线索的人设计——例如：记者在截止日期前梳理泄露文件、研究人员在论文中寻找洞见、学生通过主题查询来深入阅读文献、历史学家跨书籍关联事件等。

资源

• 教程：轻松入门 Semantra 的指南——从安装工具到实际操作示例，帮助您快速上手。
• 指南：关于如何更高效使用 Semantra 的实用指导。
• 概念：解释 Semantra 工作原理的一些核心概念。
• 使用 Web 界面：Semantra Web 应用的使用参考。

本页面提供了 Semantra 的概览及功能参考。此外，还提供其他语言版本：Semantra en español、Semantra 中文说明。

安装

请确保已安装 Python >= 3.9。

安装 Semantra 最简便的方式是使用 pipx。如果您尚未安装 pipx，请运行以下命令：

python3 -m pip install --user pipx

或者，如果您已安装 Homebrew，可以直接运行：

brew install pipx

安装完 pipx 后，请执行：

python3 -m pipx ensurepath

打开一个新的终端窗口，以使 pipx 设置的新路径生效。然后运行：

python3 -m pipx install semantra

这将把 Semantra 安装到您的系统路径中。您应该能够在终端中运行 semantra 并看到输出。

注意：如果上述步骤无法正常工作，或者您希望进行更精细的安装，也可以在虚拟环境中安装 Semantra（但请注意，只有在激活虚拟环境时才能使用）：

python3 -m venv venv
source venv/bin/activate
pip install semantra

使用

Semantra 处理的是存储在您本地计算机上的文档集合——可以是文本文件或 PDF 文件。

最简单的用法是针对单个文档运行 Semantra：

semantra doc.pdf

您也可以同时处理多个文档：

semantra report.pdf book.txt

Semantra 需要一些时间来处理输入的文档。这一过程仅需对每个文档执行一次，后续再次运行时几乎无需额外时间。

处理完成后，Semantra 将启动一个本地 Web 服务器，默认地址为 localhost:8080。在该网页上，您可以交互式地对传入的文档进行语义查询。

快速提示：

首次运行 Semantra 时，可能需要下载一个本地机器学习模型，这通常会耗费几分钟时间以及数百 MB 的硬盘空间。该模型可用于处理您提供的文档。您可以自定义使用的模型，但默认模型在速度、轻量级和效果之间取得了很好的平衡。

如果您希望快速处理文档，而不占用本地计算资源，并且不介意付费或将数据共享给外部服务，可以使用 OpenAI 的嵌入模型。

Web 应用快速导览

首次进入 Semantra 的 Web 界面时，您将看到如下界面：

在搜索框中输入内容即可开始语义查询。按下 Enter 键或点击搜索图标以执行查询。

搜索结果将按相关性顺序显示在左侧窗格中：

黄色评分表示相关性，范围为 0 到 1.00。分数在 0.50 左右表示高度匹配。较浅的棕色高亮区域会覆盖在搜索结果上，突出显示与您的查询最相关的部分。

点击某个搜索结果的文本，即可跳转到对应文档中的相关内容：

点击搜索结果旁边的加号/减号按钮，可以对该结果进行正向或负向标记。重新运行查询时，这些附加的查询参数将会生效：

最后，您还可以在查询文本中使用加号/减号来添加或移除关键词，从而精确塑造语义含义：

如需深入了解 Web 应用的操作流程，请参阅 教程 或 Web 应用参考。

核心概念

使用语义搜索引擎与传统的精确文本匹配算法有着本质的不同。

首先，无论查询多么无关紧要，总会返回搜索结果。尽管得分可能很低，但结果永远不会完全消失。这是因为语义搜索结合查询算术，往往能在细微的分数差异中发现有用的信息。搜索结果始终按相关性排序，每份文档仅显示前 10 条结果，因此低分结果会被自动过滤掉。

另一个区别在于，即使您查询的内容直接出现在文档中，Semantra 也不一定会找到精确的文本匹配。从根本上讲，这是因为同一个词语在不同上下文中可能具有不同的含义，例如“leaves”既可以指树叶，也可以表示“离开”。Semantra 所使用的嵌入模型会将您输入的所有文本和查询转换为一串数字序列，以便进行数学比较，而在这种情况下，精确的子字符串匹配并不总是重要的。更多关于嵌入技术的信息，请参阅 嵌入概念文档。

命令行参考

semantra [OPTIONS] [FILENAME(S)]...

选项

• --model [openai|minilm|mpnet|sgpt|sgpt-1.3B]: 预设用于嵌入的模型。更多信息请参阅模型指南（默认：mpnet）
• --transformer-model TEXT: 自定义 Hugging Face 转换器模型名称，用于嵌入（--model 和 --transformer-model 只能指定其中一个）。更多信息请参阅模型指南
• --windows TEXT: 要提取的嵌入窗口。以逗号分隔的列表格式为“大小[_偏移量=0][_回溯=0]”。例如，窗口大小为 128、偏移量为 0、回溯为 16（128_0_16）会将文档以 128 个标记的块进行嵌入，这些块之间有 16 个标记的重叠部分。搜索时仅使用第一个窗口。更多信息请参阅窗口概念文档（默认：128_0_16）
• --encoding: 用于读取文本文件的编码方式 [默认：utf-8]
• --no-server: 不启动 UI 服务器（仅执行处理）
• --port INTEGER: 嵌入服务器使用的端口（默认：8080）
• --host TEXT: 嵌入服务器使用的主机地址（默认：127.0.0.1）
• --pool-size INTEGER: 请求中最多可聚合的嵌入标记数
• --pool-count INTEGER: 请求中最多可聚合的嵌入数量
• --doc-token-pre TEXT: 在转换器模型中每个文档前添加的标记（默认：无）
• --doc-token-post TEXT: 在转换器模型中每个文档后添加的标记（默认：无）
• --query-token-pre TEXT: 在转换器模型中每个查询前添加的标记（默认：无）
• --query-token-post TEXT: 在转换器模型中每个查询后添加的标记（默认：无）
• --num-results INTEGER: 每个文件的查询结果（邻居）数量（默认：10）
• --annoy: 使用 Annoy 进行近似 kNN 查询（查询速度更快，但准确性略有降低）；若设置为 false，则使用精确的穷举 kNN（默认：True）
• --num-annoy-trees INTEGER: 使用 Annoy 进行近似 kNN 时的树的数量（默认：100）
• --svm: 使用 SVM 而不是任何类型的 kNN 进行查询（速度较慢，且仅适用于对称模型）
• --svm-c FLOAT: SVM 正则化参数；值越高，对错误预测的惩罚越大（默认：1.0）
• --explain-split-count INTEGER: 用于解释查询时，给定窗口上要进行的分割次数（默认：9）
• --explain-split-divide INTEGER: 将窗口大小除以该因子，以得到每次分割的长度，用于解释查询（默认：6）
• --num-explain-highlights INTEGER: 解释查询时要高亮显示的分割结果数量（默认：2）
• --force: 即使已缓存也强制执行
• --silent: 不打印进度信息
• --no-confirm: 处理 OpenAI 数据时，不显示费用并请求确认
• --version: 打印版本并退出
• --list-models: 列出预设模型并退出
• --show-semantra-dir: 打印 Semantra 将用于存储处理文件的目录并退出
• --semantra-dir PATH: 存储 Semantra 文件的目录
• --help: 显示此消息并退出

常见问题

它可以使用 ChatGPT 吗？

不可以，这也是设计上的考量。

Semantra 不使用任何生成式模型，如 ChatGPT。它仅用于语义查询文本，不会在基础上添加任何层来尝试解释、总结或合成结果。生成式语言模型有时会产生表面上看似合理但实际上不准确的信息，这会将验证的责任转嫁给用户。Semantra 将原始资料视为唯一的真理来源，并致力于证明，在更简单的嵌入模型之上结合人工参与的搜索体验，对用户来说更为实用。

开发

Python 应用程序位于 src/semantra/semantra.py，并作为标准的 Python 命令行项目，通过 pyproject.toml 进行管理。

本地 Web 应用程序使用 Svelte 编写，并作为标准的 npm 应用程序进行管理。

要开发 Web 应用程序，请进入 client 目录并运行 npm install。

要构建 Web 应用程序，运行 npm run build。要在监听模式下构建 Web 应用程序并在发生更改时自动重新构建，运行 npm run build:watch。

贡献

该应用程序目前仍处于早期阶段，但我们欢迎贡献。如有任何 bug 或功能请求，请随时提交 issue。

Semantra 快速上手指南

Semantra 是一款命令行工具，用于对本地文档（文本或 PDF）进行语义搜索。它不依赖简单的关键词匹配，而是通过理解含义来检索内容，非常适合需要从大量资料中快速定位信息的开发者、研究人员和记者。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows (需配置 Python 环境)
• Python 版本：>= 3.9
• 包管理工具：推荐安装 pipx 以隔离应用环境（可选，但推荐）

国内加速建议： 如果直接安装较慢，建议配置国内 PyPI 镜像源（如清华源或阿里源）。

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

方法一：使用 pipx 安装（推荐）

这种方式会将 Semantra 安装在独立的虚拟环境中，避免污染全局 Python 环境。

1. 安装 pipx (如果尚未安装)：

   python3 -m pip install --user pipx
   python3 -m pipx ensurepath
   

   注：执行完 ensurepath 后，可能需要重启终端或新开一个终端窗口使路径生效。

2. 安装 Semantra：

   python3 -m pipx install semantra
   

方法二：使用虚拟环境安装

如果您更喜欢手动管理虚拟环境：

python3 -m venv venv
source venv/bin/activate  # Windows 用户请使用: venv\Scripts\activate
pip install semantra

安装完成后，在终端输入 semantra --help 验证是否安装成功。

基本使用

Semantra 的工作流程是：分析本地文件 -> 启动本地 Web 服务 -> 在浏览器中进行交互式语义搜索。

1. 搜索单个文档

对单个 PDF 或文本文件进行语义分析并启动搜索界面：

semantra doc.pdf

2. 搜索多个文档

同时分析多个文件（支持混合格式）：

semantra report.pdf book.txt notes.md

3. 开始搜索

• 等待处理：首次运行时，Semantra 会自动下载默认的机器学习模型（约几百 MB），并对文档进行向量化处理。此过程仅需执行一次，后续搜索将是瞬时的。
• 访问界面：处理完成后，工具会自动在浏览器打开 http://localhost:8080（或手动访问该地址）。
• 执行查询：
  • 在搜索框输入自然语言问题（例如：“关于气候变化的主要观点”）。
  • 系统会按相关性排序显示结果，并用高亮标出文档中最相关的片段。
  • 点击结果可直接跳转到原文对应位置。

高级技巧提示

• 正负反馈：在搜索结果旁点击 + 或 - 按钮，可以告诉系统哪些结果是相关或不相关的，从而优化后续搜索。
• 语义运算：在查询词前加 + 或 - 可以微调搜索意图（例如：+经济 -战争 表示查找与经济相关但与战争无关的内容）。

---

更多详细配置（如更换 OpenAI 模型、调整分词窗口等）请参考官方文档中的 Guides 部分。