离线本地全文检索工具实践：倒排索引、增量更新与中文分词

1. 先把“艾非”这个名字背后的事情想明白

“艾非”第一次出现在我的草稿本上时，旁边只有一行潦草的字：“把散在四五个地方的东西拢成一个能搜的整体。”那会儿我刚接手一堆历史资料，格式混杂，命名混乱，散落在三个盘、两个移动硬盘和一个旧笔记本的备份目录里。找一个关键词，得开四五个窗口逐个翻，翻完还不确定有没有漏。于是我给这套要自己动手搭的小系统起了个代号叫“艾非”——没有特别含义，就是需要一个短、好记、不会跟现有软件重名的称呼，方便写脚本时打日志、建目录、起进程。

这套东西到底能干什么？一句话说清楚：它盯住若干你指定的目录，把里面能读的文本抽出来，建一份本地索引，然后你敲一个词，它在一秒内告诉你哪几个文件、在第几段、命中了几次。它解决的问题很具体——资料量大到靠记忆和文件夹层级管不住，但又没大到需要上重型方案。适合谁？适合那些有一堆自己的文档、代码片段、会议记录、读书笔记，愿意花一个周末把它跑起来，之后长期受益的人。完全不懂编程的读者看到这里可能会犹豫，我的建议是先看第 4 章的操作记录，那部分我把每一步都拆开了；有基础的同学可以直接跳到第 3 章的实现细节。

我对“艾非”的定位从头到尾没有变过：一个不需要联网、不需要常驻服务的本地索引工具。它不是一个产品，没有界面可以炫耀，但它每天帮我省下的时间非常可观。下面我把整个从想法到跑通的过程摊开讲，包括那些我当时判断错的、返工重写的部分。

1.1 三条硬需求是从哪来的

动手之前我强迫自己先写需求，不写代码。这一步看起来浪费时间，实际省了大量返工。我列了很多条，最后删到只剩三条，因为它们互相之间是有拉扯的，必须提前排优先级。

第一条是离线可用。资料里有一部分是不方便往外传的，所以整个流程不能依赖任何在线接口，断网状态下必须完全正常。这条直接砍掉了一大批“调个在线服务做语义检索”的方案，看起来很先进，但对我不适用。

第二条是增量更新要快。我的资料目录每天都会变，如果每次都要全量重扫，哪怕只花三分钟，人也会烦，烦了就会忘记跑，忘记了索引就过期，过期了就不敢信。这条把“单文件全量重建”的方案否掉了。

第三条是结果要能解释。我不想只看到一个文件名列表，我要知道命中的上下文，最好能直接看到命中的那几十个字。这条决定了存储层不能只存文件名和路径，必须存位置信息。

三条摆在一起，方案空间其实已经被压缩得很小了：本地嵌入式存储 + 位置级倒排 + 基于修改时间的增量触发。后面所有的技术选择，基本都是这三条的推论。

1.2 为什么最后没做成一个常驻的网页服务

我承认一开始是想做成网页的。浏览器打开一个地址，输入框一敲，结果出来，体验很好。我甚至写了个原型，跑起来了。但用了两天我就放弃了，原因有三个，说出来都很朴素。

第一个原因是启动成本。网页服务要跑起来，得有个进程常驻。我这台机器平时开着几十个窗口，再加一个后台服务，内存不紧张，但我心里一直有个“它在跑”的负担。查东西本来是随手的事，结果变成“先确认服务还在不在”，这就本末倒置了。

第二个原因是端口和权限的麻烦。本机端口偶尔会撞，撞了就得改配置；改了配置脚本里写死的那一串又得跟着改。这种小事一次两次没关系，反复出现就很消耗耐心。

第三个原因更关键：我实际的使用场景是“在终端里敲一行”。我大部分时间待在命令行里，翻文件、跑脚本、看日志。让我切到浏览器、点输入框、敲词、回车，这一套动作比在终端敲一行命令慢得多。工具要顺着手走，不能让人绕路。

所以最终形态是一个命令行程序加一个可以选的交互模式，没有服务，没有端口，跑完就退出。这个决定是整个项目里最省钱的一个决定，因为它省掉了整整一层的状态管理、进程守护和错误恢复代码。

1.3 三个必须提前定下来的取舍

第一个取舍：存不存原文。存原文的好处是检索结果可以直接展示上下文，不用回头读文件；坏处是索引体积翻倍，且原文里有内容变更时容易出现“索引里的旧文”和“磁盘上的新文件”不一致。我最后选择了不存全文，只存片段——每个命中点前后各截一段，长度写死在配置里。这样体积可控，且片段跟着索引一起更新，不会出现陈旧内容。

第二个取舍：分词做到什么程度。中文不切词基本没法搜，切得太细又会产生大量无意义碎片。我的做法是主词典 + 二元兜底：词典里有的按词典切，词典里没有的按相邻两字切一份作为补充词条。这样新词、专有名词不会漏，代价是索引会比纯词典方案大一些，实测在可接受范围内。

第三个取舍：索引放在哪。放在原目录里会被误删、会被同步工具带走；放在系统临时目录会被清理；最后我选了用户主目录下一个固定的隐藏目录，路径写在配置文件里，可覆盖。这一条看着琐碎，但我第一版就是放在了资料目录里，结果某次整理文件的时候连索引带数据一起挪了位置，所有绝对路径全失效，白重建了一次。

提示：凡是“能被用户随手移动或删除”的位置，都不要拿来放索引。这是我在这个项目里交的第一笔学费。

2. “艾非”的整体结构：拆成四层，每层只干一件事

结构上我没有搞什么复杂的分层架构，就是四个功能块串起来，块之间的接口就是文件或者数据表，简单到一眼能看完。之所以坚持这么切，是因为这种个人工具最怕“改一个地方牵连一大片”——我没有精力维护优雅的抽象，我需要的是坏了能五分钟定位。

四层分别是：采集层负责发现文件、判断有没有变；解析层负责把各种格式压成纯文本；存储与索引层负责把文本切成词条、写进本地库；检索层负责读出来、打分、排序、展示。下面逐个说清楚每一层我为什么这么设计。

2.1 采集层：只认目录，不认来源

采集层最简单的做法是“遍历目录树，挑出符合扩展名的文件”。我加了两样东西让它更实用。

第一样是忽略规则。有些目录是绝对不该进去的，比如版本控制目录、依赖包目录、缓存目录、临时文件目录。这些地方文件多、体积大、内容重复，进去扫一遍既慢又脏。我用一个纯文本的忽略清单，一行一条，语法尽量简单到不需要学习成本——支持前缀匹配和简单的通配就够了。

第二样是变更判定的双保险。只比修改时间不够可靠，因为批量复制、解压、恢复备份都可能让修改时间失真；只算内容哈希又太慢。我的做法是先比“大小 + 修改时间”，这两个有一个变了才去算哈希，哈希相同就跳过。两级判定把 90% 以上的无谓读取挡在了门外，剩下真正需要重新解析的文件其实很少。

这里有个细节值得单说：修改时间的精度。不同文件系统的时间精度不一样，有的到秒，有的到纳秒。我第一版存的是浮点秒，结果出现了“文件刚写完，索引认为它没变”的情况——因为写入和扫描落在同一秒内。后来我把比较逻辑改成允许一个很小的容差，并且对于“修改时间比索引构建时间还新”的文件一律重扫，这个问题才彻底消失。

2.2 解析层：把各种格式压成纯文本

解析层是整个项目里最“脏”的部分，因为格式太多了。我的策略是分派 + 降级：按扩展名分派到不同的抽取函数，抽不出来就降级。

纯文本类（txt、md、csv、日志）直接按编码猜测读，猜错了换一种编码再试，最多试三种。这一步看着简单，实际上编码猜错是后面所有乱码问题的源头，我在第 5 章会专门讲。

结构化文本类（json、xml、yaml）我的做法是直接当文本读，不做语法解析。原因很实际：我不需要理解结构，我只需要搜到里面的字。强行解析反而会因为格式错误整个文件读不出来，得不偿失。

二进制文档类需要调用外部工具转成文本，这部分我单独放在一个子命令里，不放在主流程。主流程只处理纯文本，保证快；需要转换的走异步，慢慢来。这个拆分让主流程的耗时稳定在一个可预测的范围内，不会因为混进来一个巨型文档就卡住十分钟。

还有一个容易被忽略的点：大小上限。我设了一个单文件上限，超过的直接跳过并记一条日志。不设这个上限的后果我经历过——一个几百兆的日志文件差点把内存吃满，机器卡死，只能强制结束进程。

2.3 存储与索引层：一个文件装下全部

存储我选了嵌入式关系库，也就是一个文件搞定，不需要额外进程，不需要账号密码，拷走就能用。这个选择的理由很直接：我的数据量在这个工具的适用范围内（几万个文件量级），完全不需要独立的数据库服务；而单文件的好处是备份和迁移就是复制一个文件。

表结构我压到了最少的四张：

postings里的位置串我是把位置压成一串变长整数存的，没有拆成多行。这么做的好处是查询时候一次读出来就能算邻近度，坏处是不能按位置单独更新——但这在增量场景下不是问题，因为一个文件变了就整体重写它的记录。这条是我从“精确归一化”改回“适度冗余”的一个典型例子，理论上的第三范式在这里换不来任何实际收益。

索引体积我做了一个实测：约 2 万个文件、平均每个 4KB 左右纯文本、总量约 80MB 的语料，建完之后库文件约 190MB 到 230MB 之间浮动。膨胀系数大约 2.4 到 2.9 倍，主要来自词条字典和位置信息。这个量级对本地磁盘完全不是问题，但如果你的语料是几百 GB，就得考虑分库或者砍掉位置信息了。

2.4 检索层：打分比排序更重要

检索这一层，很多人以为难点在查得快，其实真正的难点在排得对。查得快靠索引结构，排得对靠打分公式。

我用的是经典的词频-逆文档频率思路，做了两处改动。第一处是长度归一化：长文件天然词多，不归一化的话长文件永远排前面，短小精悍的笔记永远排在后面。第二处是字段加权：文件名和标题里出现的词，权重给得比正文高，因为标题命中通常意味着主题相关。

还有一个很实用的调整：同一文件内多处命中，分数不线性累加。第一次命中权重给满，后面的命中权重递减。原因很简单，一个文件里同一个词出现一百次，往往说明它是个无关紧要的重复词，而不是它特别相关。

结果展示我也做了取舍。默认只显示前若干条，每条给出行号、片段、和分数。片段要以命中词为中心截取，而不是从头截取——这点小细节直接决定了好不好用。

3. 核心实现：从目录监听到能搜出东西

这一章是实操密度最高的部分。我尽量把代码贴到能直接跑的程度，同时解释每一段为什么这么写。所有实现只用标准库，不引入第三方依赖，这样你在任何一台装了运行环境的机器上都能复现，不用处理版本冲突。

3.1 文件发现与两级去重

扫描的核心逻辑是：走一遍目录树，对每个候选文件先做廉价判断，再做昂贵判断。廉价判断是大小和修改时间，昂贵判断是内容哈希。下面这段是骨架：

import os, hashlib, time SKIP_DIRS = {".git", "node_modules", "__pycache__", ".cache", "tmp"} MAX_BYTES = 8 * 1024 * 1024 def walk_targets(root, exts): for dirpath, dirnames, filenames in os.walk(root): dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS] for name in filenames: if os.path.splitext(name)[1].lower() not in exts: continue full = os.path.join(dirpath, name) try: st = os.stat(full) except OSError: continue if st.st_size > MAX_BYTES or st.st_size == 0: continue yield full, st def quick_hash(path, limit=65536): h = hashlib.blake2b(digest_size=16) with open(path, "rb") as f: h.update(f.read(limit)) return h.hexdigest()

注意digest_size=16这个参数。我用的是 128 位的摘要，碰撞概率在这个数据量级下可以忽略，而十六进制长度只有 32 个字符，比 64 字符的全长摘要省一半存储。这是一个典型的“够用就好”的取舍，如果你要处理上千万文件，再考虑换成长摘要。

quick_hash只读前 64KB，这是个有意的妥协。很多文件的前 64KB 就足以区分，而完整读取一个大文件的开销是前者的几十倍。我把这个函数只用在“大小和时间都相同、需要二次确认”的场景，不用于首次建库。

3.2 文本抽取与编码容错

纯文本抽取最难的不是读，是猜对编码。我的策略是有限尝试 + 兜底不失败：

ENCODINGS = ("utf-8", "utf-8-sig", "gb18030", "utf-16") def read_text(path): with open(path, "rb") as f: raw = f.read() if b"\x00" in raw[:4096]: return None # 疑似二进制，主流程跳过 for enc in ENCODINGS: try: return raw.decode(enc) except (UnicodeDecodeError, LookupError): continue return raw.decode("utf-8", errors="replace")

最后那行errors="replace"是兜底，保证永远不抛异常。代价是极端情况下会有替换字符，但索引里有几个坏字符，远比整个文件抽不出来要好。这个思路贯穿了整个项目：主流程永远不因为单个文件失败而中断，失败记日志，继续下一个。

b"\x00"那个判断也很重要。有些二进制文件扩展名看着像文本，直接解码会得到一堆乱码，进了索引就是纯噪声。前 4KB 里出现空字节，基本可以判定不是纯文本。

3.3 分词：词典优先，二元兜底

分词我没用现成组件，原因有两个：一是标准库没有；二是引进来要处理词典文件和版本，反而更麻烦。我自己写了个最长匹配，加二元补充：

def tokenize(text, lexicon, max_len=6): out = [] i, n = 0, len(text) while i < n: if not is_word_char(text[i]): i += 1 continue matched = None for L in range(min(max_len, n - i), 1, -1): frag = text[i:i + L] if frag in lexicon: matched = frag i += L break if matched: out.append(matched) else: # 二元兜底：把相邻两字也当词条 if i + 1 < n and is_word_char(text[i + 1]): out.append(text[i:i + 2]) out.append(text[i]) i += 1 return out

max_len=6这个上限是我调出来的。设太小，长的专有名词切不中；设太大，每处理一个字都要往回退着匹配，复杂度上去了。测下来的经验值是：中文场景 5 到 7 之间比较平衡，我取 6。英文和数字走同一套逻辑，效果尚可，因为英文单词在词典里通常也是整体词条。

二元兜底是我最满意的一个设计。它让系统面对新词、缩写、拼写变体都有兜底能力，不用维护庞大的词表。代价是索引膨胀，实测大约多出 30% 到 40% 的词条。这个代价我接受。

3.4 内存与体积的预算计算

这一节讲参数，因为参数不对，后面全是坑。

先算单次解析的内存峰值。设单文件上限为 8MB，解码成字符串后，如果是双字节字符，内存占用约 16MB，加上中间切片的临时对象，峰值大约是这个的 3 到 4 倍。也就是说单文件处理时，峰值大概在 50MB 到 70MB 之间。这个量级不需要做流式处理，整读整处理就行。如果你的上限设成 200MB，峰值会到 1.5GB 以上，那就必须改成流式切块了。

再算写入批大小。逐条提交的话，每条都要一次磁盘同步，效率极低。我把写入按批累积，每批 500 到 2000 条提交一次。批太大，出错回滚的代价高；批太小，同步开销占比高。取 1000 是个稳妥值，实测吞吐比逐条提交快一个数量级。

最后算检索时的结果截断。倒排表里一个高频词可能对应上万个文档，全取出来打分再排序是浪费。我的做法是先在倒排表里按文档频率从低到高处理，累计到一定数量后提前终止。参数上我把候选集上限设成 5000，超过就截断。这个参数会影响召回率，设太小会漏掉真正的结果。5000 这个值是我拿自己的语料反复试出来的，你的语料如果更大，可以往上调。

3.5 打分与结果呈现

打分公式我简化成了三段：

def score(tf, df, total_docs, doc_len, avg_len, in_title, k1=1.2, b=0.75): import math if df <= 0 or total_docs <= 0: return 0.0 idf = math.log(1 + (total_docs - df + 0.5) / (df + 0.5)) norm = 1 - b + b * (doc_len / max(avg_len, 1)) base = idf * (tf * (k1 + 1)) / (tf + k1 * norm) return base * (2.0 if in_title else 1.0)

k1控制词频饱和的速度，b控制长度归一化的强度。这两个是经典参数，k1=1.2、b=0.75是常用起点，我基本没改，因为改了收益不大，反而要多调一轮。真正带来明显提升的是标题加权那个 2.0 的倍数，它让主题命中的文件稳定浮上来。

结果展示上我用了三段式：第一行给文件名和分数，第二行给命中的行号，第三行给片段。片段截取函数要处理边界情况，比如命中点在文件开头或者结尾附近，不能让切片越界。

4. 完整实操：从空目录到第一次搜出结果

这一章按时间顺序写，你可以照着做一遍。我尽量写得像操作记录，包括我中途停下来想的地方。

4.1 目录约定与配置文件

我先建了三个目录：数据根目录、索引目录、日志目录。数据根目录下按大类分子目录，索引和日志放在主目录下的固定隐藏目录。配置文件我用了最简单的键值格式，一行一条，用等号分隔，支持注释。好处是人能读能改，坏处是不能嵌套——但我确实不需要嵌套。

配置文件里我写了这几项：数据根目录列表（可以多个）、索引文件路径、扩展名白名单、忽略目录清单、单文件大小上限、检索默认返回条数、片段长度。每一项都给了默认值，这样配置文件删了也能跑，只是用默认行为。

注意：路径一律写绝对路径。相对路径在不同工作目录下启动会指向不同位置，这个坑我踩过两次，第二次是因为定时任务的工作目录和我手动执行时不一样。

4.2 首次全量扫描的完整过程

第一次跑全量，我做了三件事来保证结果可信。

第一，先跑一次空转。空转模式只遍历、只统计，不写库。三分钟我就知道了：候选文件多少个、被忽略规则挡掉多少个、超限多少个、按扩展名分布是什么样的。这组数字直接告诉我后面建库大概要多久、库大概多大。这个习惯强烈建议保留，任何批量操作前先看一眼统计。

第二，开详细日志。日志按文件记录一行：路径、大小、状态（新增/跳过/超限/失败）。跑完我抽了几十条看，发现有一批文件状态是“失败”，一看路径，是文件名里有特殊字符导致的读取问题，修了之后重跑。

第三，分批跑，跑完核对条数。全量跑完后，我直接数了一遍数据库里的记录数，和空转统计的候选数对比。差值是失败数加上被规则二次过滤的数量，这两个数字日志里都有，对得上才算过关。这一步看着多余，但它保证了“索引是完整的”这个前提，不然后面搜索结果少了你都不知道是真没有还是没建进去。

4.3 增量更新：幂等是唯一的要求

增量更新我只提一个硬要求：幂等。同一批变更，跑一次和跑三次，结果必须完全一样。做到这一点的方法是“以文件为单位的整体替换”——一个文件变了，先删它的所有倒排记录，再按新内容重新写入，全程放在一个事务里。

为什么强调事务？因为我遇到过一次断电（更准确说是系统自动重启）。那次之后库里有几个文件的记录是“删了一半”，搜索这些文件会返回残缺结果。加上事务之后，任何中断都会整体回滚，不会留下半截数据。

还有一个边界情况：文件被删除或改名。删除要清掉记录，改名在文件系统看来是“删一个、加一个”，靠哈希去重能识别出来是同一个文件，但路径变了必须更新。我的处理是先按哈希查有没有现成记录，有就把路径更新过去，省掉一次重新解析。资料整理期间我改过几百个文件名，这个优化让那次重建的时间从十几分钟压到了一分钟以内。

4.4 定时任务与日志轮转

定时任务我做得很克制，只用系统自带的任务机制，每天固定时间跑一次增量。这里有两个参数要想清楚。

执行时间。选在自己不用机器的时间段，避免抢占。我选的是凌晨，代价是出问题要第二天才知道。所以我额外加了一个“手动触发”的子命令，任何时候都能补跑。

日志轮转。不轮转的日志会无限长大，我见过日志文件把磁盘吃满的情况。我的做法是按大小轮转，单文件上限设 10MB，最多保留 5 份。算下来日志占用上限是 60MB，可控。这个上限不是拍脑袋的，是按“一天的正常日志大约多少行、一行大约多少字节”估出来的。

# 手动触发一次增量，并把日志写到固定位置 ./run_index update >> ~/.local/state/afei/run.log 2>&1

5. 问题排查实录：我踩过的那些坑

这一章是我最想写的部分，因为绝大多数教程都会跳过它，而它恰恰是实际落地时花时间最多的地方。

5.1 常见问题速查表

这张表里的每一条我都真实遇到过，其中“索引体积异常膨胀”那条最隐蔽。当时库文件从 200MB 涨到了 1.4GB，我以为是谁塞了大文件，查了半天发现是兜底逻辑把每个单字都当成了词条，而单字在所有文档里几乎都出现，倒排表被撑爆了。解决办法很简单：单字词条只保留在位置信息里，不单独建倒排，体积立刻回到正常。

5.2 三个印象最深的坑

第一个坑是符号链接导致的死循环。我的资料目录里有个链接指回了上层目录，遍历的时候形成了环，进程直接跑飞。修法是记录已访问的真实路径，遇到重复直接跳过。这个坑教育我：任何递归遍历都必须有环检测，不管你觉得可能性多低。

第二个坑是文件在扫描过程中被改动。一边建索引一边有同步工具在往里写文件，读到的内容是半个文件，哈希算出来对不上，下次又重扫，反复折腾。我的处理是读之前和读之后各取一次大小和时间，两次不一致就跳过本次，等下一轮。这个“读前读后各看一眼”的模式后来我在很多地方都用上了，成本极低，收益很大。

第三个坑是结果排序完全不合理。早期版本里，一个包含大量重复内容的文件永远排第一，因为它词频最高。我加了长度归一化之后好了一些，但真正解决问题的是“同文件内重复命中递减权重”。这个改动只有几行代码，效果立竿见影，我当天就感觉到了差别。

6. 关于“艾非”后续还能怎么长，以及我的一点体会

这个东西做到现在，功能上已经很稳定了，但我脑子里还挂着几件事。第一件是把解析层和主流程彻底解耦，让二进制文档也能进主流，办法是转成文本之后走同一套入库逻辑，主流程不感知来源。第二件是给检索加一个“按目录过滤”的能力，因为我经常只想在某一个子目录里找，现在的做法是搜完再肉眼筛，效率低。第三件是把片段长度做成按结果动态调整，短的给两行，长的给五行，这个纯粹是使用体验上的打磨。

不过我得承认，我大概率不会马上去做这几件事。这个工具最大的价值在于它已经能用了，而不是它能变得多强。我见过太多自己给自己做的工具，功能一路加，最后复杂到不敢改，反而废掉了。“艾非”从一开始就只有一个目标：让我在十秒内找到东西。这个目标现在已经达成了。

如果让我给准备动手的人一句实话，那就是：别一上来就想架构。先把“扫描一个目录、抽文本、建索引、搜出来”这条最短路径跑通，哪怕代码只有一百行、哪怕全写在同一个文件里。跑通之后你会自动发现哪里难受，那个“难受”才是真实的需求，比你在纸上想出来的需求准得多。我第一次跑通的那个版本，索引是直接写在内存里的，退出就没了，但它让我当天就验证了分词方案和打分方案是否可行，后面所有的工程优化都建立在那次验证之上。

还有一个小技巧分享一下：无论你用什么方案，都留一个“只统计不写入”的开关。这个东西的开销只有几行代码，但它在排查问题时能帮你把“数据问题”和“逻辑问题”干脆利落地分开，省下的时间远超编写成本。我在后面几轮迭代里，几乎每次改动都是先跑统计模式看一眼分布，确认没异常再动真格的。