1. 为什么要在 Node.js 里做本地 AI 前置预处理办公文档的本地 AI 处理最容易被低估的环节不是模型本身而是把一份几十页的 Word、PDF、Excel 拆成模型能吃的“小份”再决定哪些内容走硬规则、哪些内容交给模型。我最初做这套东西的时候想法很朴素Node.js 读文件调个本地模型接口把结果拼回去就完事了。结果第一版跑下来一份 80 页的产品需求文档光分片就花了 40 多秒模型调用排队排到天荒地老最后输出的摘要还把表格里的数字串行了。后来复盘才发现问题根本不在模型而在前置预处理这一层。Node.js 本地 AI 前置预处理模块说白了就是在文档进入模型之前用 Node.js 做三件事把文档拆成语义完整的片段、用 L0 自然语言硬规则做第一轮筛选和标注、再通过一个调度层决定哪些片段优先送进模型。这套东西做得好模型调用量能降一半以上响应速度翻倍做得不好模型再强也白搭。这篇文章适合两类人看一类是已经在本地部署了 AI 模型、想把它接进办公文档处理流程的开发者另一类是被文档分片和调度问题折磨过、想找一套可复现方案的技术负责人。我会把分片策略、L0 硬规则的设计、调度层的实现、以及我踩过的那些坑全部摊开讲清楚。代码以 Node.js 为主涉及少量配置和参数计算尽量做到你照着抄就能跑。2. 整体架构设计与核心思路拆解2.1 为什么前置预处理要独立成一个模块很多人会把文档解析、分片、规则判断、模型调用写在一个大函数里跑通是能跑通但一旦文档格式变了、规则要调整、模型换了整个函数就得重写。我吃过这个亏所以第二版直接把前置预处理抽成独立模块边界划得很清楚输入是原始文档路径或 Buffer输出是带元数据的片段数组和调度优先级中间不碰模型调用。这样设计的好处有三个。第一分片逻辑可以单独测试不用每次都启动模型第二L0 硬规则可以热更新改规则不用重启整个服务第三调度层可以独立扩展后面想加优先级队列、限流、重试都不会影响前面的解析逻辑。Node.js 的模块化机制在这里帮了大忙用require或import把三层拆开每层只暴露必要的接口。具体分层是这样的解析层负责读 Word、PDF、Excel、纯文本统一转成带段落标记的中间结构。分片层按语义边界切分控制单片长度保留上下文重叠。L0 规则层用自然语言硬规则做初筛打标签、定优先级。调度层根据优先级和资源状态决定片段进入模型的顺序。注意不要在这一层做任何模型推理哪怕只是调用一个本地小模型做分类。前置预处理的核心价值是“减负”不是“加活”。2.2 分片策略选型固定长度、语义边界还是混合分片策略直接决定后续模型效果。我试过三种方案最后选了混合策略。固定长度分片最简单按字符数或 token 数切比如每 500 字一片。优点是实现快缺点是经常把一句话、一个表格、一个列表从中间切断模型拿到半截内容输出质量直线下降。我实测过固定长度分片下模型对表格数据的理解错误率比语义分片高出 30% 以上。语义边界分片按段落、标题、列表项切保证每片内容完整。优点是语义连贯缺点是片段长度不均有的段落只有一句话有的章节几千字调度层不好统一处理。混合策略是我最终采用的先按语义边界切如果某个语义单元超过阈值比如 800 字再按句子边界二次切分如果连续多个小段落属于同一小节就合并到接近阈值再切。这样既保证语义完整又控制单片长度在合理区间。阈值怎么定我的经验是看模型上下文窗口和办公文档的平均段落长度。假设本地模型上下文是 4096 token中文大约 1 token 对应 1.5 到 2 个汉字那单片控制在 800 到 1200 字比较稳妥留出空间给提示词和输出。这个数字不是死的你可以根据实际模型调整。2.3 L0 自然语言硬规则的定位与边界L0 硬规则这个词听起来玄乎其实就是用自然语言写的、不依赖模型的确定性判断规则。比如“包含‘保密’字样的段落标记为高优先级”“表格数据单独成片”“页眉页脚直接丢弃”“连续空行超过三行视为章节分隔”。这些规则用正则、字符串匹配、简单统计就能实现不需要模型参与。为什么叫 L0因为它是整个处理流程的最底层在模型之前执行成本极低速度快结果确定。L0 规则做得好能过滤掉 20% 到 40% 的无效内容比如页眉页脚、重复的免责声明、空白段落。这些内容如果送进模型不仅浪费算力还可能干扰模型判断。但 L0 规则也有边界。它只能处理“形式化”的特征不能理解语义。比如“这段话说的是优点还是缺点”硬规则判断不了必须交给模型。所以 L0 的定位是筛选和标注不是理解和生成。把这两件事混在一起规则会越写越复杂最后变成一堆无法维护的正则表达式。2.4 调度层为什么不能简单用队列调度层最容易踩的坑就是直接用一个数组当队列先进先出。我第一版就是这么干的结果发现高优先级的片段比如包含关键决策的段落排在几百个低优先级片段后面模型半天才处理到。办公文档处理场景下用户往往只关心几个核心段落其他内容是背景信息如果调度层不区分优先级体验会很差。我的调度层设计参考了操作系统里的多级反馈队列思路但做了简化。片段按 L0 规则打上的优先级分成三档高、中、低。高优先级片段直接进快速通道中优先级进普通队列低优先级进延迟队列。调度器每次从快速通道取取空了再取普通队列普通队列空了才处理低优先级。同时加了一个简单的限流防止模型接口被瞬间打满。这个设计不复杂但效果很明显。实测下来用户感知到的“首屏结果”时间从平均 12 秒降到了 3 秒左右因为高优先级片段先被处理用户先看到关键内容后面的背景信息慢慢补。3. 核心细节解析与实操要点3.1 文档解析统一中间结构是关键Node.js 处理办公文档绕不开几个库mammoth处理 Wordpdf-parse或pdfjs-dist处理 PDFxlsx处理 Excel。这些库各有各的输出格式如果直接拿它们的原始输出往下走分片层会写得非常痛苦。我的做法是先统一成一种中间结构再进入分片层。中间结构长这样{ type: paragraph | heading | table | list | code, level: 1 | 2 | 3 | null, // 标题层级 text: 内容文本, meta: { page: 3, source: docx, style: Heading2 } }这个结构的好处是分片层不用关心文档原本是什么格式只需要按type和level做语义切分。比如遇到heading就开一个新片段遇到table就单独成片遇到连续paragraph就累积到阈值再切。解析 Word 的时候有个细节要注意mammoth默认会把样式信息丢掉只保留纯文本。如果你需要保留标题层级得用它的styleMap配置把Heading1、Heading2映射出来。我一开始没配结果所有标题都变成了普通段落分片层完全找不到语义边界切出来的片段乱七八糟。PDF 解析更麻烦pdf-parse对表格和分栏的支持很弱经常把两栏文字混在一起。我的经验是如果 PDF 是扫描件先走 OCR如果是电子版优先用pdfjs-dist按页提取文本再根据坐标信息判断段落边界。这一步没有银弹只能根据实际文档调。3.2 分片实现语义边界与长度控制的平衡分片的核心逻辑是遍历中间结构数组维护一个当前片段缓冲区遇到语义边界或长度超限就切分。伪代码大概是这样function splitIntoSegments(blocks, maxLen 1000, overlap 100) { const segments []; let buffer []; let bufferLen 0; for (const block of blocks) { if (block.type heading || block.type table) { if (bufferLen 0) { segments.push(flush(buffer)); buffer []; bufferLen 0; } segments.push(createSegment(block)); continue; } const blockLen block.text.length; if (bufferLen blockLen maxLen bufferLen 0) { segments.push(flush(buffer)); buffer takeOverlap(buffer, overlap); bufferLen buffer.reduce((sum, b) sum b.text.length, 0); } buffer.push(block); bufferLen blockLen; } if (bufferLen 0) segments.push(flush(buffer)); return segments; }这里有几个参数需要仔细调。maxLen是单片最大长度我设 1000 字对应大约 600 到 700 token留足空间给提示词。overlap是重叠长度设 100 字目的是让相邻片段有上下文衔接避免模型因为缺少前文而误解。重叠不能太大否则重复内容多浪费算力也不能太小否则上下文断裂。实操心得重叠部分建议取maxLen的 10% 到 15%。我试过 5%模型经常问“上文提到的那个方案是什么”试过 30%重复内容太多调度层去重很麻烦。10% 到 15% 是甜点区。还有一个坑是表格处理。表格绝对不能按长度切必须整表成片。如果表格太大超过maxLen我的做法是按行拆分但每片都带上表头否则模型看不懂列的含义。这个逻辑写起来不复杂但很容易漏漏了之后模型对表格数据的理解基本是灾难级的。3.3 L0 硬规则的设计与实现L0 规则我用一个独立的规则引擎来管规则用 JSON 描述方便热更新。每条规则包含匹配条件、动作和优先级。比如const rules [ { name: drop-header-footer, match: (block) block.meta.style Header || block.meta.style Footer, action: drop, priority: 100 }, { name: mark-confidential, match: (block) /保密|机密|内部资料/.test(block.text), action: tag, tag: high-priority, priority: 90 }, { name: table-standalone, match: (block) block.type table, action: isolate, priority: 80 } ];规则执行顺序按priority从高到低先匹配的先执行。drop直接丢弃tag打标签isolate强制单独成片。这样设计的好处是规则之间不会互相干扰新增规则只需要加一条 JSON不用改代码。L0 规则里最值得说的是优先级判定。办公文档里哪些内容应该优先送模型我的经验是三类包含决策性词汇的段落如“决定”“方案”“结论”、包含数字和指标的段落、包含“保密”“紧急”等标记的段落。这三类内容用正则就能识别打上高优先级标签调度层优先处理。但规则不能写太死。我一开始把“方案”这个词设成高优先级结果文档里“方案一”“方案二”这种列举也被标成高优先级调度层被塞了一堆其实不重要的内容。后来改成“决定采用”“最终方案”这种更具体的短语准确率才上来。规则要具体不要宽泛这是血泪教训。3.4 调度层的实现细节调度层我用了一个简单的优先级队列基于数组实现但加了权重和限流。核心逻辑是class Scheduler { constructor(concurrency 2) { this.queues { high: [], normal: [], low: [] }; this.concurrency concurrency; this.running 0; } enqueue(segment) { const level segment.priority || normal; this.queues[level].push(segment); this.tick(); } tick() { if (this.running this.concurrency) return; const segment this.dequeue(); if (!segment) return; this.running; processSegment(segment).finally(() { this.running--; this.tick(); }); } dequeue() { return this.queues.high.shift() || this.queues.normal.shift() || this.queues.low.shift(); } }concurrency控制并发数我设 2因为本地模型通常只能同时处理一两个请求设太高反而会排队。dequeue按高、中、低顺序取保证高优先级先处理。这里有个细节低优先级队列不能饿死。如果高优先级一直有内容进来低优先级永远排不上。我的做法是给低优先级加一个“老化”机制每处理 10 个高优先级片段强制取 1 个低优先级片段。这样既保证关键内容优先又不会让背景信息永远处理不到。注意调度层不要做重试逻辑。重试应该放在模型调用层调度层只负责排序和分发。混在一起会让调度逻辑变得难以调试。4. 实操过程与核心环节实现4.1 环境准备与依赖安装Node.js 版本我建议用 18 LTS 或 20 LTS这两个版本对 ESM 和顶层 await 支持稳定处理异步分片逻辑更顺手。安装步骤不复杂官网下载对应平台的安装包一路下一步就行。如果你在 Linux 服务器上部署用nvm管理版本更方便切换版本不用重装。核心依赖有这几个npm install mammoth pdf-parse xlsx npm install p-queue # 可选用于更复杂的调度mammoth处理 Wordpdf-parse处理 PDFxlsx处理 Excel。p-queue是可选的如果你不想自己写调度器可以用它但它的优先级支持比较弱复杂场景还是自己写更灵活。4.2 完整处理流程的代码实现把前面几层串起来主流程大概是这样const { parseDocument } require(./parser); const { splitIntoSegments } require(./splitter); const { applyL0Rules } require(./rules); const { Scheduler } require(./scheduler); async function preprocess(filePath) { const blocks await parseDocument(filePath); const segments splitIntoSegments(blocks, 1000, 120); const tagged segments.map(seg applyL0Rules(seg)); const scheduler new Scheduler(2); const results []; for (const seg of tagged) { if (seg.dropped) continue; scheduler.enqueue({ ...seg, onDone: (result) results.push(result) }); } await scheduler.drain(); return results; }parseDocument根据文件扩展名选择对应的解析器splitIntoSegments做语义分片applyL0Rules打标签和过滤Scheduler负责调度。每一层都可以单独测试比如你可以只跑分片层看切出来的片段是否合理不用启动模型。4.3 参数调优与实测数据参数调优我做了几轮对比测试用一份 60 页的产品文档做样本记录不同参数下的处理时间和模型调用次数。结果如下参数组合分片数模型调用次数总耗时首屏时间maxLen500, overlap5014214228s8smaxLen1000, overlap100787816s4smaxLen1500, overlap150525214s5smaxLen1000, overlap100 L0过滤616111s3s从数据看maxLen1000配合 L0 过滤是综合最优的。maxLen500分片太碎模型调用次数翻倍总耗时反而高。maxLen1500虽然分片少但单片内容多模型处理慢首屏时间反而上升。L0 过滤把无效片段砍掉后模型调用次数从 78 降到 61总耗时降了 30% 多。这个测试样本有限你的实际文档可能不一样但调参思路是一样的先保证语义完整再控制单片长度最后用 L0 规则砍无效内容。不要一上来就调模型参数前置预处理没做好模型调参是白费功夫。4.4 与本地模型的对接方式前置预处理模块的输出是片段数组每个片段带text、priority、meta。对接本地模型时我建议用 HTTP 接口而不是直接调模型进程。Node.js 起一个轻量 HTTP 服务模型侧用 Python 或其它语言起一个推理服务两边通过 JSON 通信。这样解耦的好处是模型换了、升级了Node.js 侧不用改。请求体大概是这样{ prompt: 请总结以下内容\n\n{segment.text}, max_tokens: 512, priority: high }模型侧收到请求后根据priority决定是否插队。如果模型服务本身不支持优先级可以在 Node.js 侧控制发送顺序调度层已经排好序了按顺序发就行。实操心得本地模型推理服务建议加一个请求队列不要让它直接暴露给 Node.js 并发调用。模型进程通常只能串行处理并发调用会导致显存溢出或响应超时。Node.js 侧控制并发数为 1 到 2 比较稳妥。5. 常见问题与排查技巧实录5.1 分片把表格切断了怎么办这是最常见的问题。表格被切断后模型拿到的片段缺少表头或部分行输出结果完全不可用。排查方法是检查分片逻辑里有没有对type table做特殊处理。如果没有表格会按普通段落累积超过maxLen就被切开。解决办法是在分片循环里加一个判断遇到表格块先 flush 当前缓冲区再把表格单独成片。如果表格本身超过maxLen按行拆分但每片都复制表头。这个逻辑不复杂但一定要写不写就是给自己挖坑。5.2 L0 规则误杀重要内容规则写得太宽泛会把重要内容过滤掉。比如用“备注”作为过滤关键词结果把“重要备注”也删了。排查方法是给规则加一个“白名单”机制匹配到过滤规则后再检查是否包含高优先级关键词如果包含就不删。我的做法是规则执行顺序调整先执行高优先级标记规则再执行过滤规则。过滤规则检查片段是否已被标记为高优先级如果是就跳过。这样即使规则写得宽泛也不会误杀关键内容。5.3 调度层高优先级片段被低优先级阻塞如果调度器实现有问题高优先级片段可能排在低优先级后面。排查方法是打印每次dequeue的结果看优先级顺序是否正确。常见原因是队列实现用了普通数组的push和shift但优先级判断逻辑写反了或者高优先级队列为空时没有正确 fallback。另一个原因是并发控制没做好。如果concurrency设成 1但高优先级片段在低优先级之后入队调度器可能已经开始处理低优先级了。解决办法是入队时立即触发tick并且在高优先级入队时检查是否有空闲槽位有就立即处理。5.4 模型返回结果与片段对应不上这个问题通常出在结果收集环节。如果多个片段并发处理返回顺序可能和发送顺序不一致。排查方法是给每个片段加唯一 ID结果返回时按 ID 匹配不要依赖数组顺序。我的做法是在enqueue时给片段加id模型返回时带上id收集结果时用 Map 按 ID 存储最后按原始顺序输出。这样即使并发处理结果也不会错位。5.5 常见问题速查表问题现象可能原因排查方法解决办法表格数据串行表格被分片切断检查分片逻辑是否对 table 特殊处理表格单独成片超长按行拆并带表头重要内容丢失L0 规则误杀打印被 drop 的片段调整规则顺序加白名单高优先级不优先调度器逻辑错误打印 dequeue 顺序修正优先级判断入队即触发 tick结果错位并发返回顺序不一致检查结果收集逻辑加唯一 ID按 ID 匹配处理速度慢分片太碎或无效内容多统计分片数和模型调用次数调大 maxLen加 L0 过滤5.6 独家避坑技巧第一个技巧分片前先做一次全局扫描统计文档里有多少表格、多少标题、多少页眉页脚。这样你可以预估分片数量和模型调用次数提前发现异常。比如一份 20 页文档预估出 500 个片段那肯定是分片逻辑有问题。第二个技巧L0 规则用配置文件管理不要硬编码。我一开始把规则写在代码里改一条规则要重新部署非常麻烦。后来改成 JSON 配置文件改完重启服务就行效率高很多。第三个技巧调度层加一个简单的监控输出记录每个片段的入队时间、出队时间、处理时间。这样出问题的时候你能快速定位是调度慢还是模型慢。我靠这个监控发现过一次模型服务响应时间突增的问题否则根本不知道瓶颈在哪。6. 性能优化与扩展方向6.1 分片层的性能优化分片层是纯计算Node.js 单线程处理大文档时可能成为瓶颈。我的优化方法是把分片逻辑放到 Worker Thread 里主线程只负责调度和 IO。这样分片和模型调用可以并行整体吞吐量提升明显。另一个优化是预编译正则。L0 规则里用了大量正则表达式如果每次匹配都重新编译性能损耗不小。把正则提前编译好存成常量匹配速度能快 20% 到 30%。6.2 调度层的扩展思路当前调度层是单机内存队列如果文档量很大可以考虑持久化队列比如用 Redis 或 SQLite 存片段调度器从队列里取。这样即使服务重启未处理的片段也不会丢。另一个扩展方向是动态并发控制。根据模型服务的响应时间动态调整concurrency响应快就多并发响应慢就降并发。这个逻辑不复杂但需要模型服务暴露健康检查接口。6.3 与本地 AI 代理的集成如果你在用本地 AI 代理助手前置预处理模块可以作为代理的一个 skill 接入。代理收到“整理这份文档”的指令后先调前置预处理模块做分片和过滤再把片段逐个送给模型最后汇总结果。这样代理的响应会更稳定不会因为文档太大而超时。集成的时候注意一点代理通常有自己的调度逻辑不要和前置预处理模块的调度层冲突。我的做法是前置预处理模块只负责分片和打标签调度完全交给代理避免两层调度互相干扰。6.4 后续可以尝试的方向一个方向是基于内容的动态分片。当前分片阈值是固定的如果文档里有一段特别重要的内容可以动态放宽阈值让它单独成片不和其他内容混在一起。这个需要结合 L0 规则做规则标记为高优先级的片段分片时给更大的长度预算。另一个方向是分片质量评估。切完片之后用一个轻量模型或规则评估每片的质量比如是否语义完整、是否包含关键信息。质量低的片段重新切分或合并。这个会增加一些开销但对模型输出质量提升明显。我在实际使用中发现前置预处理模块的价值会随着文档复杂度上升而放大。简单文档可能感觉不明显但一旦遇到几十页、格式混乱、表格密集的办公文档这套东西就是刚需。踩过的坑主要集中在分片边界和调度优先级上这两块调好了后面基本就是顺水推舟。
