REA工具实战：用文本聚类与关键词提取，让海量资料自动整理成主题报告

如果你手头攒了几百篇资料、文档、会议记录，却始终没时间一篇篇看完；如果你发现自己收藏的内容越来越多，但真正用起来的时候又找不到重点在哪——那这篇分享应该对你有用。

我花了大概一个多月，做了一个叫 REA 的小工具。它不是那种大平台级的系统，就是跑在本地的命令行工具，核心功能一句话讲完：把一批乱七八糟的文本资料自动整理成结构化分析结果。从原始文档进去，到清洗、抽关键词、算相似度、聚类分组，最后吐给你一份带主题分布和关键词热点的报告。整个过程不需要联网，不依赖任何在线服务，所有数据留在本地。

这个项目解决的是内容检索和整理场景里很实际的一个痛点：资料太多之后，靠人工阅读已经跟不上节奏，靠关键字搜索又只能搜到“出现过”，搜不到“大概在讲什么”。REA 的思路是用“词语分布 + 聚类”的方式，把一堆散乱的文档压缩成几张表和几个主题标签，让人在面对大量文本时先看结论，再按需回溯原文。

适合谁来参考呢？如果你在做调研、写方案、整理行业信息、分析竞品资料，或者只是个人知识库越来越大但始终觉得“存了等于没读”，那这篇内容里提到的设计思路和代码逻辑，都可以直接搬过去改一改。接下来我会把 REA 的整体设计、核心模块、实操过程和踩坑记录全部摊开讲清楚，照着抄就行。

1. 项目起源与整体设计思路

1.1 为什么会做 REA：被资料淹没之后的自救

先交代一下背景。我在某个小组里长期要做行业信息跟踪，每周会固定收集几十篇公开文章、报告摘要、论坛讨论。早期这些料少，人工读完还能应付。但量一上来，问题就暴露了——真正重要的信息被埋在大量重复内容和废话里。我想找“上周大家都在讨论哪个方向”时，靠的是印象和运气，而不是一套可复用的方法。

我也试过用搜索工具解决，但搜索结果只会告诉你“关键词出现在哪些文档里”，不会告诉你“这些文档之间是什么关系”“哪几篇其实讲的是同一件事”。如果你面对的是一批资料而不是单个文档，关键词搜索的帮助就很有限。REA 的出发点就是把这个问题当作一个“降维”任务来做：先用词语抽取把文档转成一组特征向量，再用相似度聚类把内容相近的文章合并成主题组，最后用频率统计找出这段时间重点在聊什么。

这个名字是我起的，REA 是 Rapid Extraction & Analysis 三个单词的首字母。项目定位从一开始就定得很清楚：它是资料整理的前置过滤器，不是替代人工阅读的AI大脑。它的价值是帮你快速知道“这堆东西里面有哪些主题、哪些内容重复、哪些是这段时间被反复提及的”，而不是帮你读懂每一篇文章。

1.2 技术选型：为什么用 Python 标准库 + SQLite

REA 用 Python 实现，数据库用 SQLite，数据分析和报告输出靠 pandas 做完了大部分统计，可视化则直接写 HTML 文件，不依赖在线图表服务。技术栈本身非常朴素，没有任何花哨的组件。选这套组合的理由也简单：你能在任何一台装了 Python 3 的电脑上跑起来，不用配一堆环境。

设计上我刻意把它拆成了三个独立模块：文本清洗、特征抽取、聚类汇总。模块之间通过 JSON 文件传递中间结果。这么做的好处是，你不需要一次性把整条链路都跑通，调试哪一段就单独跑哪一段，坏在哪一步直接看中间产物就能定位。实际开发过程中这个决策帮了大忙，因为文本清洗和特征抽取这两块的调试循环是非常频繁的。

另外一个关键选择是：所有文档统一转成 UTF-8 编码的纯文本后再进入处理流程。无论原始文件是 PDF、Word 还是网页另存的文件，第一步都先变成 .txt。这个“先归一化”的思路看起来笨，但极大减少了后续步骤里遇到编码问题的概率。

1.3 工作流程图（不用图，用文字描述）

整个流程大致走五步：

1. 输入一批 .txt 文件，程序遍历目录，记录文件名、文件路径、最后修改时间。
2. 清洗：去头尾空白、合并多余换行、去掉无意义符号（但不删段落）。
3. 抽取：对每篇文档做词语切分，过滤停用词，统计词语频率，生成“文档-词频”矩阵。
4. 聚类：用 Jaccard 相似度计算文档两两之间的关系，设定阈值后把关系紧密的文档合并成组。
5. 输出：生成 JSON 数据文件 + Markdown 报告 + HTML 可视化页面。

如果只需处理少量文档，第五步的 Markdown 报告就够用了。量大或者需要反复调整阈值时，JSON 文件的价值就体现出来了：你可以拿它二次加工，也可以直接丢给其他程序继续处理。

2. 核心模块拆解与实现要点

2.1 文档接入与文本清洗：统一数据入口是第一道关

REA 面对的数据来源很杂，有的是从网页复制粘贴的，有的是扫描件转出来的，有的是老旧的 txt 文件。所以接入层的第一步就是编码探测和转换。我自己写了一个函数，读取文件的二进制内容后，依次尝试 UTF-8、GBK、GB18030 编码，解码成功就继续，全部失败则跳过该文件并记录错误日志。

这里有个细节值得说明：GB18030 这个编码很关键，它是 GBK 的超集，能覆盖绝大部分中文字符。很多老资料用 GBK，如果你只试 GB2312 和 UTF-8，通常会栽在生僻字上。考虑到要处理的历史文档可能来自各种年代，宁可多写两行编码兼容代码，也不要因为个别文件编码不对导致整批导入失败。

清洗层处理的内容包括：统一行尾符号、删除不可见控制字符、合并连续空行、把全角空格转成半角、删除网页残留的标签片段。注意，清洗不代表“压缩”，原始段落结构要尽量保留，因为后面做词语频率统计时不希望因为断句位置被改动而破坏词语切分。

清洗完后，每篇文档会输出成一个 jsonl 格式的中间文件，每行是一条记录，包含 doc_id、title、text、word_count、clean_time。看到中间文件里每条记录都很规整，基本可以判断这一关过了。

2.2 词语切分与热词抽取：不依赖在线服务也能做的中文处理方案

中文文本的词语切分本来是个老大难问题。REA 不接在线服务，也不装重量级的本地分词引擎，而是采用了一种在特定场景下够用的简化策略：基于词表和正则的匹配式切分。

具体做法是维护两个词表：一个是核心词表，放你所在领域里的专业词汇和常见短语；另一个是停用词表，放“的、了、和、是、我们、可以”这类没有实际信息量的词。处理时先做正向最大匹配，优先把词表里的词切出来，然后再对剩余文本按标点符号和虚词切分成短句片段。

这套方案的效果取决于词表质量。如果你处理的资料集中在某一两个领域，比如行业调研、产品竞品、技术选题，那花半天把核心词表补充到几百个词，热词抽取的准确率就已经很可观。比如“大语言模型”“私有化部署”“降本增效”如果预先进了词表，就不会被切得七零八落，而“降”、 “本”、“增”、“效”单独出现时没有意义，在结果里会被当成噪声过滤掉。

切分完之后对每一篇文档做词频统计，然后用 TF（词频）加权方式排序。为了后续聚类更稳定，我在这一步做了两个过滤：过滤掉只在一篇文档里出现过一次的词，过滤掉高频但低信息量的词。这些参数在实际调的时候很灵敏，后面会单独讲。

2.3 相似度计算与聚类：从文档到主题组

聚类的核心是文档相似度。REA 采用的方案是 Jaccard 相似度：把每篇文档的特征词集合看成一组，两两求交集大小除以并集大小，得到一个 0 到 1 之间的数值。数值越高，说明两篇文章在词语层面越相似。

举个例子：文档 A 的特征词是 {"模型", "训练", "数据", "算力"}，文档 B 的特征词是 {"模型", "推理", "数据", "成本"}。交集是 {"模型", "数据"}，并集是 {"模型", "训练", "数据", "算力", "推理", "成本"}，相似度就是 2/6 ≈ 0.33。这个值本身无所谓，关键是设定阈值之后它能不能正确区分“相关”和“不相关”。

聚类时，我按照相似度从高到低排序所有的文档对，把高于阈值且尚未归属任何组的文档逐步合并起来。处理完一轮之后，可能还有一批孤立文档不属于任何组，就单独归为“未聚类”。实际操作中，阈值调得越低，分组越大但主题越混杂；调得越高，分组越精细但碎片也越多。做第一版的时候我默认值是 0.35，效果还可以，但不同领域语料差异很大，用的时候需要自己试。

这里的一种常用做法是把阈值做成可配置参数，在运行时通过命令行传入，也可以每次改动后保存一份带参数的输出快照，方便对比不同阈值的效果。

2.4 数据结构与输出格式：让结果能看、能查、能二次用

REA 的数据存储用 SQLite，主要有三张表：

• documents：存文档基础信息和清洗后的文本。
• terms：存每篇文档的特征词和词频。
• clusters：存聚类结果，每一条记录包含 cluster_id、doc_ids、主题关键词、文档数。

这样设计的好处在于，查询“某个聚类下有哪些文档”或者“某个词语分布在哪些文档里”都是一条 SQL 的事，不需要在全量文本里从头扫描。你也可以在 REA 跑完之后，自己用其他工具直接连这个数据库做更细粒度的分析。

输出环节做了三重格式：

1. JSON：最完整的数据快照，供机器解析。
2. Markdown：人类可读的报告，包含主题组列表、各组关键词、文档清单。
3. HTML：在 Markdown 基础上加了一个简单的柱状图，直观显示各主题组的文档数量分布。

HTML 的柱状图我直接用 CSS 画，不引第三方库，打开就是本地文件，方便直接发内部协作群。

3. 实操过程：从零到可用，把 REA 跑起来

3.1 准备环境：不需要额外安装什么复杂的依赖

如果你要复现，环境要求很低：

• Python 3.8 以上（我用的是 3.10，理论上 3.6+ 也能跑）。
• 无需安装第三方库。所有功能我尽量用标准库实现，pandas 不是必需的，统计部分也可以直接写原生 Python 循环。

把项目目录结构准备好：

rea/ data/ raw/ # 放原始 txt 文件 clean/ # 放清洗后的 jsonl meta/ # 放临时中间结果 output/ # 放最终报告 rea.py # 主程序 config.json # 参数配置 wordlists/ core_words.txt # 核心词表 stop_words.txt # 停用词表

这是一个按“输入、中间产物、输出”三层分离的结构。如果中途某一步出问题，随时可以看中间产物定位问题，不会被一堆临时文件搞乱。

3.2 配置参数：第一次运行前的必调项

config.json 里我设计了几个核心参数，初次使用建议仔细核对：

这些参数我都有默认值，但说实话直接抄默认值跑出来的效果只能算“能看”，真正要贴合自己的语料，必须自己调一轮。

3.3 运行完整流程：一条命令跑到底

把一批文档放进 raw 目录后，执行：

python rea.py --input ./data/raw --config config.json

如果只想跑清洗和特征抽取，不聚类，可以加参数：

python rea.py --input ./data/raw --config config.json --step extract

如果想单独调试聚类：

python rea.py --input ./data/clean --config config.json --step cluster

跑完之后，output 目录下会多出三个文件：[时间戳]_report.json、[时间戳]_report.md、[时间戳]_report.html。

Markdown 报告的结构大致如下：

# 分析报告（共 156 篇文档，聚类为 8 个主题组） ## 主题组 1：私有化部署（12 篇） 关键词：私有化、合规、数据安全、本地化 文档：doc_001.txt、doc_034.txt、... ## 主题组 2：模型训练成本（9 篇） ...

看到这个结构，你基本就能知道这批资料大致聊了几个方向，哪些话题出现的频率高，哪些文档其实可以合并阅读。

3.4 输出结果怎么用：从报告到行动

生成报告不是终点，REA 最重要的使用方式是“人机配合”。我自己的用法是这么一套组合拳：

1. 先看 Markdown 报告的主题组列表，了解这批资料覆盖了哪些方向。
2. 点开文档数量较多的主题组，看关键词，判断这个主题是不是当前需要关注的重点。
3. 点到具体文档清单，挑两三篇最有代表性的原文精读。
4. 如果发现某个主题组文档数量特别少、关键词又不明确，就暂时搁置，不去逐篇读。

这套用法最大的收益是：和之前标记“每周必须读完所有资料”的状态比，阅读量其实下降了，但关键信息的抓取率和保留率反而高很多。

4. 常见问题与排查技巧实录

4.1 编码问题：文件读进来就乱码或直接报错

这个我在迭代前期遇到得最多。表现有两种：一种是程序报 UnicodeDecodeError，另一种是读出来全是黑色方块或乱码字符串。

排查思路：先看原始文件是不是真的 txt 格式。有些文件扩展名是 .txt，实际内容却是 HTML 或者带 BOM 的 UTF-16。最好在清洗层先按字节判断文件头，再决定解码方式。

实际经验教训：我在某个数据批次里碰到几十个文件全是乱码，排查到最后发现这批文件是从旧系统导出的，编码是 GB18030，但文件头没有声明。我的自动识别逻辑默认尝试 UTF-8，失败后跳到 GB18030，理论上能兜住，但其中一个文件里混入了几个不合法字节，直接解码失败。后来加了一行 errors="ignore"，把个别坏字节跳过，程序才顺利跑完。

所以清洗层有一个小原则：对解码错误不要太敏感，能跳过的就跳过，但要把跳过的信息记录到日志里。因为你真正关心的是整体统计结果，个别坏字不会让结论反转。

4.2 热词抽取结果“四不像”：全是单字和虚词

如果你跑出来的热词是一堆单字，大概率是词表没有覆盖当前领域。REA 的正向最大匹配切分在没有核心词表加持时，效果几乎等于按字符切分，因而会产生大量无意义的单字“词”。

解决方法有两个：

1. 扩充核心词表，把领域常见术语加进去。
2. 调高 min_word_len，过滤掉长度为 1 的词。

但要注意，只调高长度参数不能解决本质问题，因为双字词里照样可能出现“我们”“可以”“问题”这类停用词。所以真正该花时间的是维护停用词表。第一版跑完之后，我把各种报告里高频的噪声词全部收集起来，大概百来个，塞进 stop_words.txt 之后效果立刻就不一样了。

我也建议跑完第一遍之后，拿结果里的高频词列表反查原词表，看到哪些“意外词”出现了高频，就先把它们加进停用词表。词表是迭代出来的，不存在一次写对的说法。

4.3 聚类结果扎堆或稀碎：阈值得自己试

聚类阈值是 REA 里调试成本最高的一个参数。我自己的经验是：

• 阈值 0.5 以上：聚类非常保守，出来的主题组多、每组文档少，碎片化严重。
• 阈值 0.2 以下：文档全抱成一大团，主题组只剩一两个，关键词混杂。
• 初始建议 0.3 左右起步，每轮调整幅度控制在 0.05 以内，记录下每组数量和关键词变化。

还有一个容易踩坑的点：相似度计算的特征词如果数量太少，Jaccard 值往往会变得极端，不是 0 就是 1。所以特征词数量要足够，top_k_words 不要低于 15。

你可以在调试时给每轮跑批加一个备注参数，输出到文件名里，比如 report_035_20250113.md，这样“阈值 0.35 在 20250113 那批数据上的结果”一目了然，方便来回对比。

4.4 处理几千个文件时性能从几秒变几分钟

REA 早期处理 156 篇文档只要几秒钟，拿到 3000+ 篇后，纯 Python 的暴力两两计算开始变得缓慢。相似度计算是 O(n^2) 的复杂度，这个瓶颈无法回避。

我做了两个优化：

1. 特征词集合的 Jaccard 计算用集合操作替代循环，速度提升非常明显。
2. 先做一次粗过滤：如果两篇文档没有共同特征词，直接跳过相似度计算。因为在大部分语料里，一篇文档只会跟少数几篇文档相关，大部分两两组合都是零交集。

另一个思路是把相似度计算改成“先按核心词粗分桶”，只在桶内计算。比如先把文档按“含不含词 X”分桶，然后只计算同桶文档之间的相似度。这个方案会损失少量边界情况，但速度可以再上一个台阶。我这个版本做了第一版优化就够用了，如果你有更大的语料，得往这个方向再走一步。

4.5 结果重复和根因排查：为什么两次跑出来不一样

如果你两次运行结果不一致，先检查输入目录里是否有新增或者删除的文件。如果文件没变但结果变了，检查 config.json 里有没有随机类参数。REA 本身的处理是确定性的，但你如果改了停用词表或者阈值，结果自然不同。

这种情况我通常会建议在输出报告的文件名里加上输入文件的哈希值（前 8 位），这样每个输出都对应到一个确定的数据版本。排查“这个报告是拿哪份数据跑出来的”会变得特别快，不会出现翻着文件找旧版本的局面。

5. 延伸场景、改进方向与经验总结

5.1 复用场景：不只适用于调研资料

REA 虽然诞生于调研资料的整理需求，但核心思路可以迁移到不少其他领域。我实际见过的用法包括：

• 个人知识库管理：把每个月收藏的文章批量跑一遍，快速知道这个月关注的主题漂移到了哪里。
• 竞品动态分析：把一段时间内收集的竞品公告、版本发布说明聚合，看变化的集中点在哪里。
• 会议纪要与复盘：按季度导入会议纪要，聚类看哪些问题被反复提及，辅助复盘。
• 课程大纲 / 写作素材整理：对大量素材进行主题聚类，找选题或找遗漏。

所有场景的共同特征是：有一批数量较多但单篇信息量有限的文本，需要从“逐篇读”变成“按组读”。

5.2 可扩展方向：从词频走向语义

现在的 REA 本质上是基于符号共现的方法，它理解不了“成本”和“费用”是近义概念。如果你处理的是用词高度不统一的语料，比如不同团队写的文档，那这种方法的召回率会受限。

改进方向有三个：

1. 维护同义词表/映射表，在抽取阶段把同义词归并到标准词。
2. 引入词向量模型，将每篇文档映射为向量后再算余弦相似度，语义层面的聚类会更准。
3. 引入标题和段落位置权重，让出现在标题里的关键词权重更高。

我目前用的版本只实现了第一点，也就是同义词归并，其余两条路线的完整实现还在计划中。但如果你的场景对语义准确度要求没那么高，第一版效果已经足够支撑日常工作流。

5.3 我踩过的一些坑，值得再复述一遍

有几个坑我每次想都觉得自己当时挺傻的，写出来希望你们别再踩：

第一，清洗步骤的地位被严重低估。我早期把大量时间花在聚类参数上，结果输出一直不理想。后来发现问题是原始文本里残留大量 HTML 片段和“阅读原文”“点击查看”这类导航文字，它们成了高频“特征词”，污染了整个聚类结果。把清洗脚本写好之后，效果立刻变好。所以遇到聚类结果诡异，先看高频词列表里有没有明显特征词，有就先清洗。

第二，停用词表是越迭代越好的，但要控制膨胀。停用词表加到上千之后，也会引入风险——有些词在这个领域确实是停用词，换一个领域可能是核心词。如果你要跨领域用同一套配置，建议把停用词表拆成“通用基础版”和“领域定制版”，运行时可叠加。

第三，中间结果文件一定要保留。REA 每次跑完都会把清洗后和特征抽取后的中间文件留在 meta 目录。有一次我发现聚类不对劲，直接拿上一批的中间结果重跑聚类，省掉了重新清洗和抽取的时间。这也是我把 REA 拆成多步骤命令的原因——宁可多一条命令，也不要整个流程从头跑。

5.4 后续的规划与最后想说的话

REA 目前的版本足够我日常使用，但后续我会再打磨三个细节：把同义词表做成交互式更新工具，方便在跑完一遍之后直接把高频噪声词一键加入停用词表；给 HTML 报告加一个“点击关键词追溯原文”的功能，让报告能直接跳转到原始文档；另外就是把批量文件的增量处理做出来，新文件进来只需要增量算增量部分，不用每次全量重跑。

最后说一点个人体会。做 REA 这个工具的过程中，我最大的收获其实不是这个工具本身，而是想清楚了一件事：很多时候资料整理效率低，不是因为你整理得不够快，而是因为整理的方法一开始就错了——你试图精细读懂每一份材料，而真实需求只是先知道哪些值得读。REA 用词频和聚类粗糙地解决了“值得读”这个问题，虽然它笨，但它诚实。你在自己的项目里，如果也遇到类似的“重点到底在哪”的困惑，不妨先做一个粗糙但可用的过滤器，再把宝贵的注意力留给真正值得精读的那几篇。工具是小的，踩过的坑是真的，希望这篇东西对你有用。