1. 项目背景与整体设计思路

接手这个项目的时候，我其实挺高兴的，因为公司终于想通了：与其把几百份办公文档直接丢给大模型，不如先做一个本地AI前置预处理模块，把这些格式混乱的DOCX、PDF、XLSX整理成结构化的分片，再由一个可配置的调度层决定每片内容该走哪条处理管线。这套东西做完，后面文档检索、知识问答、自动归档跑起来就顺多了。

真正上手之后才发现，分片和调度这两件事看起来简单，做起来全是细节。本来想着无非是读文件、切文本、写规则，结果从Node.js版本选型到分片策略参数，再到自然语言规则匹配的边界情况，每一步都踩了坑。这篇文章就当作一次完整复盘，把我踩过的坑和最终方案记录下来，给正在做类似事情的兄弟一个参考。

1.1 为什么需要前置预处理

先说场景。公司内部有一个文档知识库，里面有销售合同、财务报销单、技术方案、会议纪要，各种格式都有。之前我们直接把原始文件喂给本地AI做问答，效果很糟糕，主要体现在三个方面：

第一个问题是文件格式没法直接读。PDF里有扫描件，DOCX里有文本框和批注，XLSX里多表头嵌套。大模型不是万能的，给它一个二进制PDF，它根本读不出里面的文字。第二个问题是上下文窗口不够用。一份上百页的技术方案，转成纯文本可能有几十万token，本地部署的模型根本装不下，强制塞进去要么报错要么答非所问。第三个问题是输出质量不稳定。同样的文档，这次问答能答上来，下次问同一个问题，结果可能是错的，因为喂进去的上下文每次都不一样，模型没有稳定的依据。

所以我们需要在入口处加一层处理：先把各种格式统一转成纯文本，再按语义结构和长度约束切成合适的分片，最后通过一套规则来决定每片内容交给哪条下游处理管线。这一层就是前置预处理，它是整个本地AI应用的地基。地基不牢，上面做得再好也白搭。

1.2 技术选型与架构拆解

技术栈选型上，我们用了Node.js作为主框架。为什么不用Python？坦白说这个项目里后续有很多队列调度、HTTP接口、WebSocket实时推送的需求，Node.js在这块天然合适，而且团队里熟悉JavaScript的人更多，维护成本低。Node.js 18.20.4 LTS是我们最终锁定的版本，后来也实测过Node.js 22.12+，性能确实更好，但18的稳定性在服务器上更稳妥，生产环境我们不敢随便追新。

架构上分成了三个模块：

• 文件接入层：负责监听文件夹变化、接收上传请求，把DOCX、PDF、XLSX等格式统一转换为文本内容。
• 分片引擎：对文本做语义分析和长度控制，切成一个个独立的分片单元，保留标题层级和段落上下文。
• L0规则调度：用自然语言定义匹配条件，编译成可执行的检查函数，决定每个分片走什么处理逻辑。

模块之间通过消息队列解耦。文件接入层产出原始文本，分片引擎消费后产出分片，规则调度消费分片后派发到下游。每个模块独立部署，互不影响，这样出问题的时候可以单独重启某个模块，不用整个链路一起挂。

2. 文档分片引擎的实现细节

分片是整个预处理流程的核心环节，也是最容易翻车的地方。切得太粗，分片里塞满无关内容，浪费上下文窗口；切得太细，把一句话硬生生切成两半，语义上下文丢失，检索质量直线下降。这里我直接说一下最终采用的方案和调整过程。

2.1 多格式统一转换

分片的前提是拿到干净的纯文本。这里我踩了一个大坑：不同格式的文件，提取文本的方式完全不同，不能想当然地统一处理。

DOCX文件我们用mammoth这个库，它能把Word文档转换成HTML或者纯文本。实测下来mammoth对docx的段落、标题、表格支持得不错，但有个坑是它默认不会提取页眉页脚里的内容，如果文档里页眉包含关键信息（比如合同编号），这部分会直接被丢掉。解决办法是读docx底层XML，把页眉页脚的文本手动拼回来。

PDF文件我们用pdf-parse，这个库底层依赖pdf.js，对文本型PDF效果不错。但遇到扫描件就只能认栽，pdf-parse返回的文本几乎是空的。这时候需要引入OCR，我暂时接了一个本地OCR服务，识别速度还算能接受，一张A4纸大概1秒左右。另外pdf-parse拿到的是原始PDF页面顺序文本，经常出现段落断行，需要做行合并处理，不然切出来的分片里全是散落的行。

XLSX文件用SheetJS读取，这个库功能很强，但要注意单元格类型。很多Excel里的日期是以Serial Number存储的，比如44562代表2022年1月1日，直接读出来是数字，丢给AI它会以为这是金额或者编号。所以读取之后必须强制做一次类型转换，把序号转成”YYYY-MM-DD”格式。

把这些格式都归一为纯文本之后，我会额外保留一个元数据结构，存入文件名、文件类型、页数、段落数，这些信息后面规则调度会用到，不能丢。

2.2 分片策略：先用硬规则切，再用滑动窗口补充

拿到一段长文本，怎么切成合适的分片？最开始我想得很简单，按固定长度切，比如每1024个字符一刀切下去。结果很快发现，这种暴力切法会把一个完整的表格拆碎，还会把标题和正文分到两个分片里，让下游模型完全摸不着头脑。

后来我改成了两层策略。第一层是按文档结构的硬规则切：遍历文本里的标题标记（markdown风格的#号标题，或者识别到的文档章节），把每个二级标题下的一块内容作为一个大区块。第二层再对这个大区块做长度约束，如果超过某个阈值，就用滑动窗口从段落边界处切成多个子块。

这里最关键的参数是分片长度。我做过一组对比测试，结果如下：

从数据上看，2048字符左右分片是最均衡的，既保证了语义完整度，也保证了检索命中率。再长的话，单分片里包含的主题太多，反而不利于精确匹配。需要注意的是，这个长度是纯文本的字数，不是token数。如果我们用的模型上下文窗口是8K token，那么一个中文分片2048字符大概相当于2000到2500个token，加上后续问题拼接，大概留一半的余量是安全的。

2.3 分片过程中容易忽略的边界处理

分片边界处理是一个水很深的地方，很多问题跑起来才发现。第一个是编码问题。从DOCX或者PDF里提取出来的文本，有时候会夹杂特殊字符，比如不间断空格（\u00A0）、零宽空格（\u200B），这些字符不影响显示，但在按长度切分时会被算成一个字符，导致分片末尾经常出现残缺的半个单词。我后来加了清洗函数，把所有不可见字符全部剔除。

第二个是表格处理。分片引擎在切分包含表格的文本时，最稳妥的做法是把表格整体保留在同一个分片内，不拆行。如果表格的内容超过了单分片长度限制，宁可把上限临时调大，也不要从表格中间切断，否则下游解析出来的表格数据是碎的。

第三个是标题归属。如果一个二级标题下面只有一个很短的段落，比如三五行字，那这个区块内容太薄，单独作为一个分片比较浪费。这时候要把这个区块和下一个相邻区块合并，等整体长度够了再切分。这种合并逻辑看似简单，但实际判断起来很绕，需要同时考虑文本结构和长度两个条件。

3. L0自然语言硬规则调度引擎

文档分片只是第一步，切完之后怎么处理和调度才是真正的重头戏。传统做法是写一堆if/else判断，比如”如果分片包含发票关键词就走A管线，如果包含合同关键词就走B管线”。这种方法写起来简单，但后续规则一多就变成一坨叉叉，改一处要连带看几十处。所以这次我换了一种思路，用自然语言定义规则，再用一个轻量级引擎去解析执行。

3.1 什么是L0硬规则

L0这个概念是我自己定义的，意思是”Level 0”，即最底层、不可协商的执行规则。它有两个特点。

第一，规则用自然语言描述，非技术人员也能看懂。比如一条规则可以写成：“如果分片文本中包含发票、编号、金额字样，并且包含日期格式，则该分片进入财务表格提取管线”。这样的描述，业务同事看了也能判断对不对，不像是看代码那样一头雾水。

第二，规则一旦定义，执行时必须完全按照规则来，不容许大模型自由发挥。这是L0和软提示（prompt）的本质区别。软提示只是一种建议，模型可以灵活理解；L0规则是硬性条件，匹配就是匹配，不匹配就是不匹配，不存在”大概符合”。

3.2 规则引擎的解析与执行流程

规则引擎的实现分为编译期和运行期两个阶段。编译期读取一份YAML格式的规则文件，把它转换成可执行的匹配函数放在内存里。转换的过程其实不复杂：把自然语言里的关键词拆出来，翻译成正则表达式或者数组匹配条件。运行期拿着分片的文本和元数据，按优先级顺序跑匹配函数，命中哪条就走哪条管线。

下面是一段精简后的规则文件示例：

rules: - id: finance-invoice priority: 100 keywords: ["发票", "编号", "金额", "税率"] regex: ["\\d{4}[-/]\\d{1,2}[-/]\\d{1,2}", "￥?\\d+(\\.\\d{2})?"] pipeline: finance_extractor fallback: general_split - id: contract-agreement priority: 90 keywords: ["合同", "甲方", "乙方", "签署日期"] regex: ["甲方[:：]\\s*\\S+", "乙方[:：]\\s*\\S+"] pipeline: contract_analyzer fallback: general_split - id: meeting-minutes priority: 80 keywords: ["会议纪要", "参会人", "决议", "行动计划"] regex: [] pipeline: minutes_sumarizer fallback: general_split

每个规则包含id、优先级、关键词、正则表达式、下游管线和兜底管线。匹配顺序是按priority从高到低，先匹配finance-invoice，再匹配contract-agreement。为什么优先级这么重要？因为一份销售合同里往往同时包含金额和甲方乙方两个特征，如果不控制顺序，它会被同时派发到财务和合同两个管线，造成重复处理。所以只能选一个优先级最高的作为主派发结果。

执行流程上，输入一个分片，先跑一遍关键词匹配。关键词匹配有两种模式，一种是全词包含，一种是任意词命中。同一规则里多个关键词，我默认用全词包含，也就是所有关键词都出现才认为命中。这个阈值可以在规则文件里调整。

3.3 执行性能优化与兜底策略

自然语言规则匹配，说到底就是字符串匹配和正则匹配的组合。问题在于，当规则数量达到几十条时，每个分片都要跑一遍全量匹配，性能撑不住。我在实测中统计了一下，一个包含五万字的大型文档，分片引擎产出大约30个分片，规则引擎在单台8核服务器上跑一次全量调度，居然要花将近40秒。瓶颈主要出在正则表达式上。

优化思路是给规则加一层快速淘汰机制。在跑正则之前，先做一个低成本的关键词布隆过滤器，分片文本里如果连规则里最低频的关键词都没出现，就直接跳过这条规则。实测下来，优化后调度时间从40秒降到了5秒左右，这个提升相当可观。更极端的场景还可以把已编译的规则函数用worker_threads做并行执行，但我暂时还没到这个量级，先记录一下。

兜底策略也很重要。任何规则都匹配不上的分片，不能被丢弃，必须有一条默认管线接住。默认管线做的事情是切分长度检查，如果长度适中就直接归档，长度超标就再做一次细分。这个兜底管线在规则文件里用fallback字段指定，每个规则都可以配置不同的兜底终点，防止某个管线转储的数据不完整。

4. 踩坑记录与排查实战

整个开发过程里，踩过的坑能写满一页纸。有些问题找了一圈文档没有现成答案，最后还是靠读源码和打日志猜出来的。这里挑几个最有代表性的记录下来，给后来的人省点时间。

4.1 大文件处理导致内存占用暴涨

项目刚上测试环境的时候，一碰上几十MB的PDF文档，进程的内存占用直接飙到1.5GB以上，有时候还会触发OOM（Out Of Memory）崩溃。排查后发现原因有两个。

第一，pdf-parse在处理大文件时，是在内存里一次性构建整个PDF对象树，导致内存开销过大。解决方案是加一个文件大小上限，超过30MB的文件先转成PDF页面级小文件，再逐页解析。第二个原因是我们自己的分片引擎把所有分片都保存在内存数组中，等着调度引擎消费。这个设计在文档量小的时候没问题，但分片数量一多，内存就炸了。后来我改成生产者-消费者模式：分片引擎产出一个分片就立即推送给调度引擎消费，不积压不过夜，内存占用马上就降下来了。

4.2 DOCX里隐藏的批注和修订记录

Word文档里经常会带有批注和修订记录，这些内容在页面上未必直接显示，但确实存在于DOCX包结构里。用mammoth提取文本时默认不含批注，我还觉得没问题。结果有一次财务提交了一份报销说明，正文里没有写审核意见，但批注里写了三条重要意见。下游AI问答系统检索的时候完全没有这些信息，导致回答内容不完整。

解决方案是解压docx文件，手动解析comments.xml和revisions.xml，把批注按顺序插入到对应段落的末尾。最后得到文本里会出现”[批注]审核人：李某某，意见：发票日期与原单不符”，这种处理方式最直观，后续规则调度也可以直接识别”批注”这个标记。

4.3 正则表达式在Unicode上的兼容性问题

JavaScript正则表达式对Unicode的处理有一个细节，很容易被忽略。比如匹配中文范围时，用普通正则[a-zA-Z]只能匹配英文字母，中文需要加上\u4e00-\u9fa5范围。但问题是不同来源的文本可能包含全角英文字符（如ＡＢＣ，是全角不是半角），用\u4e00-\u9fa5匹配不到。后来我统一先做一个全角转半角的预处理，把所有全角字符转换成半角，再跑正则。别小看这一步，它能解决大量规则匹配不上的问题。

还有一个更隐蔽的坑：正则表达式末尾没有加u标志，在处理像�这样的代理对字符时会出现乱码匹配。规则里涉及emoji或者生僻字时，一定要给正则在结尾加上u标志，并用\p{Script=Han}替代传统的Unicode范围匹配。

4.4 规则优先级导致的分片“错杀”

规则调度最怕的其实不是匹配不上，而是匹配错了。我们线上出现过一次事故：一份技术方案文档里引用了竞争对手的合同编号，结果被finance-invoice规则命中，误送入财务提取管线。好在财务管线有校验逻辑，发现数据异常后自动回退到general_split管线，没有造成大的影响。

排查后确认，问题的根源在于规则匹配只看关键词，不看上下文语义。一条硬规则命中率太高，就会把不该匹配的内容卷进来。解决方法是给规则增加更多约束条件，除了关键词，还要看周围文本的结构。比如匹配合同条款时，要求行首必须有数字编号（第1条、第2条），匹配发票时要求同时出现日期和金额两种模式。这种多维度的条件组合，能大幅降低误匹配率。

5. 性能调优与稳定性加固

前面提到了不少性能问题，但真正要把这个模块跑在生产环境，还需要更系统的调优手段。我这里把相关的性能测试方法和稳定性策略都整理出来，算是给这个项目画一个阶段性的句号。

5.1 分片与调度的性能测量方法

性能调优不能靠感觉，必须有一份可复现的测试基准。我用Node.js内置的process.hrtime.bigint()来记录每个处理阶段的耗时，把结果输出为JSON，再统一汇总到日志系统。测试数据是精心准备的，包含五份不同格式的文档：一份50页PDF技术方案、一份30页DOCX合同、一份50000行的XLSX数据表、一份带扫描件的PDF、一份纯文本Markdown。

测试结果如下表所示：

从表格可以清楚看到，扫描PDF的文本提取耗时占大头，主要花在OCR识别上。其余流程整体可控，生产环境建议加一个超时控制，单文件总处理时间超过5分钟直接报警。这个超时值可以根据自己的服务器算力调整。

5.2 稳定性策略：失败重试与降级

任何预处理模块都必须考虑失败场景，不能因为某个文件处理不了就阻塞整个队列。我用了一个简单的重试机制：文本提取失败重试两次，每次间隔1秒，如果还是失败，就把文件标记为failed，并记录失败原因，推送到人工处理队列。

降级策略也要提前设计好。比如OCR服务挂了，扫描件无法识别，此时不应该整体崩溃，而应使用一个占位文本”[扫描件，文本提取失败]”暂存，保证后续流程不断。这个占位文本在问题排查和人工干预时非常有用，能快速定位是哪一类文件出了问题。

另外Node.js本身是单线程模型，文件读取和文本解析这类CPU密集型任务如果占用主线程，会导致后续HTTP请求被阻塞。我在实际部署中把文本解析拆成了worker_threads独立线程池，主线程只负责调度和返回结果。用了这个方案之后，接口响应时间从平均800ms降到了150ms，体感提升非常明显。

5.3 从测试到上线的最后一公里

上线前我还做过一件事：把所有的规则和分片参数固化成一份配置项，放在环境变量里管理。不同场景可以通过环境变量快速调整，不需要改代码重新发布。比如测试环境分片长度设1280，生产环境设2048，模型能力升级后还能动态调。

经历过这一轮开发，我最大的感触是：分片和调度引擎看起来是通用组件，但每个业务场景都有自己的特殊坑。Node.js生态让这个模块开发起来确实快，但性能瓶颈和边界问题并不会因为语言而消失。文档分片没有银弹，规则调度也不是越复杂越好，适合自己的业务场景才是最好的方案。

我个人现在的做法是，在每次调整参数后都把分片结果抽样出来人工检查一次，确认没有切碎标题、没有遗漏关键信息，再增量更新到线上配置。这个习惯帮我避免了至少三次线上问题。如果你也在做类似的事情，建议参考这个思路，先本地跑通再上生产，每一步都留出人工校验的余地。