> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Minsearch：我的轻量RAG检索库
- URL: https://www.hubwiz.com/blog/minisearch-my-lightweight-rag-retreival-library/
- Published: 2026-06-08T13:54:08.000Z
- Updated: 2026-06-08T13:54:08.000Z
- Description: 一个小型进程内 Python 库如何替代了我教学用的 RAG 笔记本中的 Elasticsearch。
- Author: admin
- Tags: LIBRARY, #Import 2026-10-14 14:41

两年前，我正在筹备 [LLM Zoomcamp](https://github.com/DataTalksClub/llm-zoomcamp/tree/main?ref=hubwiz.com) 的首次开课，这是我关于构建 LLM 应用的免费课程。第一期主要聚焦于 RAG。我当时也在就同一主题举办工作坊。

搜索（即检索）是 RAG 中最重要的组成部分之一。我需要一种方式来教授它，但又不想要求参与者安装 Docker 或 Elasticsearch。

于是我构建了 [minsearch](https://github.com/alexeygrigorev/minsearch?ref=hubwiz.com)：一个小型的进程内 Python 搜索库。它最初只是我在笔记本中教授检索所需的最小工具，后来随着课程示例的演进而不断发展。

在本文中，我将分享：

- 为什么 Elasticsearch 在这种场景下过于笨重
- 第一个版本是如何工作的
- 它如何成为一个 PyPI 包
- 为什么我添加了可追加索引和向量搜索
- 我如何利用 Claude 来加速它
- 什么时候 minsearch 是正确的工具

![](https://www.hubwiz.com/blog/content/images/2026/06/https-3A-2F-2Fsubstack-post-media.s3.amazonaws.com-2Fpublic-2Fimages-2F327e7b76-3c70-4765-97a6-144b8d903ff2_1764x1080.png)

## 1、为什么 Elasticsearch 过于笨重

在 LLM Zoomcamp 的首次开课中，我需要向参与者展示如何索引一个小型数据集、提交查询并检索相关文档。通常是几千篇文档，有时更少。大多数示例在笔记本中运行，有时在 Google Colab 上，使用 GPU 上的开源 LLM。而在笔记本中工作是我创建 minsearch 作为更复杂搜索引擎轻量级替代方案的主要动机。

对于正常的生产系统，我可能会选择 [Elasticsearch](https://github.com/elastic/elasticsearch?ref=hubwiz.com)。它功能强大，而且我很熟悉。但对于工作坊笔记本来说，它太重了。它需要服务器、Docker、配置以及各种运维细节，而这些都不是课程的重点。

在课程或工作坊的环境中，所有东西都应该在一个笔记本内运行。我寻找过一个可以在与笔记本相同的 Python 进程中进行足够好的词法搜索的小型 Python 库，但没有找到合适的。

当时，我已经从事文本处理和搜索工作很长时间了，所以自己构建一个小型进程内搜索库并不困难。即使在那时——当编码代理还远不如现在强大时——我也可以向聊天助手描述我想要什么，获取代码，然后要求做一些修正。

![](https://www.hubwiz.com/blog/content/images/2026/06/https-3A-2F-2Fsubstack-post-media.s3.amazonaws.com-2Fpublic-2Fimages-2F0604a422-a8d0-4562-8f65-05bf3a2be890_2048x904.png)

LLM Zoomcamp 首次开课的检索模块，围绕 minsearch 构建。

## 2、第一个版本

[第一个实现](https://github.com/alexeygrigorev/minsearch/tree/62ddbe9bc4adbc38cfd14114a2128fdf3b8e0110?ref=hubwiz.com) 是一个单独的 Python 文件。

![](https://www.hubwiz.com/blog/content/images/2026/06/https-3A-2F-2Fsubstack-post-media.s3.amazonaws.com-2Fpublic-2Fimages-2F3fc70f54-aa46-4a85-9206-80192452418e_1968x1100.png)

它只有一个类 `Index`，搜索采用的就是基于 TF-IDF 的词袋模型。

它的工作原理如下：

1. 为每个文本字段拟合一个 TF-IDF 向量化器
2. 使用相同的向量化器转换查询
3. 将矩阵相乘以获得文档分数
4. 将所有文本字段的分数相加
5. 按分数对文档排序

在教学中，我使用了免费课程 Zoomcamps 的 FAQ 作为示例。一篇典型的文档包含问题、答案、章节、课程名称和一些元数据。

这已经需要比纯文本搜索更多的功能了。问题字段中的匹配应该比答案字段中的匹配权重更高。有时我只想要来自某一门课程的结果。所以第一个版本就有了字段加权（boosting）和关键词过滤功能。

这使得 minsearch 适合教学使用。它的实现足够小，学习者可以理解，但又包含了我真实课程示例所需的全部要素：文本搜索、过滤和加权。

基本用法如下：

```
from minsearch import Index
index = Index(
    text_fields=["question", "answer"],
    keyword_fields=["course"]
)
index.fit(docs)
results = index.search("can I join the course?")

```

我还在名为"[构建你自己的搜索引擎](https://github.com/alexeygrigorev/build-your-own-search-engine?ref=hubwiz.com)"的工作坊中分享了如何构建它。该工作坊的第一个版本大约在两年前推出，最初是 DataTalks.Club 的一个演讲。后来我更新了它以包含更新的库版本，并将其作为 [AI Shipping Labs 工作坊库](https://aishippinglabs.com/workshops/?ref=hubwiz.com)中的[结构化教程](https://aishippinglabs.com/workshops/2026-05-14-build-your-own-search-engine?ref=hubwiz.com)发布。

如果你想了解 minsearch 内部的工作原理，那个工作坊是最好的参考。

## 3、从文件到包

起初，人们直接下载那个单独的 Python 文件，这在我需要发布更改之前一直没问题。

每次我修复一些东西或添加功能时，课程参与者都必须重新下载文件。在 LLM Zoomcamp 中，我们通常用 `wget` 来下载。对于一个笔记本来说还好，但对于一个我不断修改的库来说就不太合适了。

于是我把它正确地打包，[发布到 PyPI](https://pypi.org/project/minsearch/?ref=hubwiz.com)，现在人们可以用 `uv` 或 `pip` 安装它：

```
uv add minsearch

```

第一个发布的版本是 [0.0.1](https://pypi.org/project/minsearch/0.0.1/?ref=hubwiz.com)。截至撰写本文时，当前版本是 `0.1.0`。

![](https://www.hubwiz.com/blog/content/images/2026/06/https-3A-2F-2Fsubstack-post-media.s3.amazonaws.com-2Fpublic-2Fimages-2F43434ae6-4904-4a30-baa6-eb67c8584deb_2048x1201.png)

## 4、我在哪里使用它

我现在在多个课程和工作坊中使用 minsearch：

- [LLM Zoomcamp](https://github.com/DataTalksClub/llm-zoomcamp?ref=hubwiz.com)
- [AI Hero](https://aishippinglabs.com/courses/aihero?ref=hubwiz.com)
- [AI Engineering Buildcamp](https://maven.com/alexey-grigorev/from-rag-to-agents?ref=hubwiz.com)

我在教学之外也使用它，用于个人和 DataTalks.Club 项目。一个例子是 [DataTalks.Club FAQ 系统](https://github.com/DataTalksClub/faq?ref=hubwiz.com)，自动化系统读取 GitHub issues 并创建 FAQ 条目。在添加新问题之前，它会使用 minsearch 检查是否已存在类似问题。

我在 [从 Google Docs 到 DataTalks.Club 课程的自动化 FAQ 系统](https://alexeyondata.substack.com/p/from-google-docs-to-an-automated) 一文中介绍过它：

自动化系统加载 FAQ，构建索引，搜索它，然后在一个 Python 进程中继续执行。

这仍然是我使用 minsearch 的主要原因，但随着课程示例的变化，这个库也需要不断成长。

## 5、实现倒排索引和向量搜索

可追加索引是在后来出现的，当时我开始准备 LLM Zoomcamp 的第二轮，并添加了关于 Agent 的模块。

### 5.1 实现倒排索引

我想展示 Agent 可以做的不只是搜索现有文档，比如将数据添加回索引并修改它。原始索引对这种操作支持得不好。它是为简单场景构建的：创建索引、搜索它，然后在笔记本结束时丢弃。

为了允许 Agent 修改索引，我实现了一种新的索引类型：`AppendableIndex`。它是一个倒排索引，保留了相同的 `fit` 和 `search` 方法，但它还允许你一次追加一篇文档。

![](https://www.hubwiz.com/blog/content/images/2026/06/https-3A-2F-2Fsubstack-post-media.s3.amazonaws.com-2Fpublic-2Fimages-2Fcd9be2f0-3ed7-4326-b63f-0c99f066c147_2038x906.png)

### 5.2 添加向量搜索

向量搜索后来也因为类似的原因被加入。我已经在"构建你自己的搜索引擎"中教授过它，但它最初并不是库的一部分。最终，我也把它加了进来。

![](https://www.hubwiz.com/blog/content/images/2026/06/https-3A-2F-2Fsubstack-post-media.s3.amazonaws.com-2Fpublic-2Fimages-2F9e88c4a0-9bd3-4538-9d6d-a8b852bbc0b9_2002x992.png)

`VectorSearch` 基于预计算的嵌入工作，并通过余弦相似度对结果排序。它并不是要取代完整的向量数据库。它是一个用于本地示例的简单工具，我的主要用例是在课程和工作坊中解释搜索概念。

### 5.3 三种索引类型和高亮

如今该库有三种主要的索引类型：

- `Index`：使用 scikit-learn 的基本 TF-IDF 索引
- `AppendableIndex`：允许后续添加文档的倒排索引实现
- `VectorSearch`：基于预计算向量的余弦相似度搜索

相同的过滤模型适用于所有三种类型。你可以按精确关键词匹配、数值范围和日期范围进行过滤。关键词字段现在是可选的，因为并非每个搜索示例都需要过滤。

现在还有高亮功能。它从搜索结果中提取片段，并标记查询词匹配的位置。动机是我们开始拥有越来越多的 Agent，我意识到对于 Agent 来说，最好模仿人类的查看方式。

人类搜索的方式是查看片段——例如在 Google 搜索中——然后根据我们看到的内容决定是否要查看一篇文章。对于 Agent，我认为如果它们能首先看到高亮的片段，然后基于这些片段决定是否查看整个页面以获取详细信息，效果会更好。

我不把 minsearch 看作一个大型基础设施项目。它之所以成长，是因为示例不断需要更多实用的功能。

## 6、使用 Claude Code 加速 minsearch

我越来越多地使用可追加索引，最终注意到一个问题：它比简单索引慢得多。

起初我选择了忽略。可追加索引做了更多工作，而且数据集很小。但在某个时刻，它甚至对我来说也太慢了，于是我决定对其进行基准测试。

第一次基准测试显示，可追加索引的索引速度大约慢 14 倍，搜索速度慢 27 倍。

我请 Claude 来看看，它发现了效率低下的原因。可追加索引在每次搜索时都重新计算 token 和分数，而简单索引依赖于 scikit-learn 的优化批量操作。

这是我第一次使用 AI 助手来基准测试和优化类似的东西。

我给了 Claude 一个清晰的循环：

1. 对 Simple Wikipedia 进行基准测试并保存基线
2. 修改代码
3. 检查结果是否仍与基线匹配
4. 比较速度

然后我让它运行，大约每小时检查一次，同时我继续准备课程材料。经过几轮后，优化后的可追加索引的搜索速度比基于 scikit-learn 的索引快了 20 到 76 倍。在更大的数据集上，差距更大。

完整的基准测试报告在这里：[benchmark/BENCHMARK\_WRITEUP.md](https://github.com/alexeygrigorev/minsearch/blob/main/benchmark/BENCHMARK%5FWRITEUP.md?ref=hubwiz.com)。

## 7、什么时候 Minsearch 是正确的工具

Minsearch 适合以下场景：

- 你有小型或中型数据集
- 你需要在笔记本、课程、原型或小型自动化中进行搜索
- 所有东西可以在一个 Python 进程中运行
- 你正在索引最多几千篇文档

最佳适用范围是 10,000 篇文档以内。在这个规模下，索引速度快，搜索便捷，你无需搭建额外的基础设施就能获得一个有用的检索层。

当有足够的纯文本可供搜索时，效果最好。课程 FAQ、工作坊数据集、文档页面和小型内部文档集合都属于这种情况。

超出这个范围，minsearch 就不再是合适的工具了。

如果你有更大的本地数据集但仍想要轻量级方案，请改用 [SQLiteSearch](https://github.com/alexeygrigorev/sqlitesearch?ref=hubwiz.com)。我正是为这种情况构建了它，并在 [我如何构建 SQLiteSearch](https://alexeyondata.substack.com/p/how-i-built-sqlitesearch-a-lightweight) 一文中写了相关介绍。

对于更大的系统，请使用真正的搜索引擎或向量数据库。

---

原文链接: [Minsearch: The Small Search Library Behind My RAG Workshops and Courses](https://alexeyondata.substack.com/p/minsearch-the-small-search-library)

汇智网翻译整理，转载请标明出处