直连 AI 之前我低估了文档预处理这道工序直到被本地模型反复折腾到没脾气。先说背景。我在做一套完全跑在本地的文档问答系统模型用的开源大模型7B 级别负责读企业内部的 Word、PDF、Excel然后回答某某制度第三版改了啥这张表去年Q2的数据是多少这类问题。最初图省事直接把文档提取成纯文本往模型上下文里一塞就完事。结果第一天就被打脸一份 80 页的制度文件提取出的纯文本超过 15 万字符本地模型上下文窗口根本接不住直接报错就算硬塞进去模型回答也是前言不搭后语完全抓不住第几章第几条这种结构信息。于是我做了一个 Node.js 写的前置预处理模块专门负责把办公文档切成适合模型消费的块并加了一层所谓的 L0 自然语言硬规则调度决定每块文本怎么切、切完怎么送、哪些块根本不送。这篇文章就是把整个过程的思路和踩过的坑完整复盘一遍。适合谁看如果你的本地 AI 应用要处理真实办公文档而你现在还在提取文本 - 直接拼接 - 丢给模型这条路上那这篇基本就是帮你在下一个坑前面踩刹车。1. 直连 AI 的效果惨案办公文档预处理为什么躲不掉1.1 Token 超限不是配置问题是数学问题很多人以为上下文窗口超了调大参数就行。本地部署过模型就明白窗口大小受显存和推理引擎限制7B 模型开 32K 上下文KV Cache 就能吃掉几个 GB 显存再往上加生成速度肉眼可见地变慢。而一份真实办公文档有多夸张我统计过手头 200 份文档纯文本平均长度是 6.2 万字符最大的是一份带附件的项目验收报告24 万字符。哪怕 32K 窗口硬撑也就够塞正文的零头。更隐蔽的问题在 token 换算。纯英文文档一个 token 大概对应 4 个字符但中文文档一个汉字在多数 tokenizer 里接近一个 token三个 GB 级文本就是几十万 token。所以在预处理阶段分词器、字符数、token 上限之间必须做一次统一换算否则你设的每片 2000 字符在模型侧可能已经超窗。1.2 结构信息丢失模型读到的是一堆没有骨架的字符直连的第二个问题是对文档结构的破坏。直接用正则或者简单 split 去分段标题层级、表格关系、列表嵌套、页眉页脚全部拍平。模型拿到这种没有标题层级、没有表格行列关系的扁平文本只能靠语感猜这一段是在说制度条款那一段是在说执行流程。如果文档里有一张 5 列 20 行的对比表转成纯文本后关系完全丢失模型甚至会把列头当成句子去理解。我后来做了一个实验同一份 20 页的合同A 版本是纯文本直连B 版本是经过结构化分片后再送模型。问违约责任在第几条、具体怎么约定A 版本从第 17 页找了一段相关文字但没给条款号B 版本直接定位到第十一条 违约责任连子项都列全了。差别就在结构保留。1.3 大对象混入上下文一个表格毁掉整轮问答还有一种情况比超限更恶心就是文档里嵌了一张超宽表格。比如 Excel 导出的 PDF 里有一张 30 列的数据表文本提取出来后单行就有几千字符。直连模型时这一行就会把上下文里其他有效信息的相对权重全部稀释模型注意力全都扑在那一堆数字上问什么都答不上来。预处理模块在这里承担的是一个路由角色普通段落等价于给模型看超大表格走单独通道抽摘要、按列拆分、或者干脆不送图片/扫描页走 OCR 分支或标记跳过。这些决策不能靠模型来完成成本太高速度太慢就用规则来定。这就引出了 L0 层的定位。2. L0 硬规则调度系统划分边界、定义规则、确定优先级2.1 L0/L1/L2 分层的思路别让大模型干小模型的活在我这套设计里文档处理分成三层。L0 层是纯代码规则不加载任何模型只做确定性操作解析文档、分片、标记类型、判断是否超长、判断是否为表格/代码块。特点是快、可复现、能审计。L1 层用小型模型比如 embedding 或文本分类模型做语义粗筛决定某一块文本和当前问题是否相关这一层是半智能。L2 层才是大模型深度推理做实际问答或者总结。L0 的定位就是守门员在上模型之前把决策面缩小。所有能用规则给定的边界绝不劳烦模型。比如标题下第一段属于正文表格列数和行数超过阈值就拆分句子不完整就不进入切片这些逻辑写成硬规则比任何提示词都稳定。2.2 我的 L0 规则集和优先级仲裁这里把我实际沉淀下来的规则清单列一份分成四类结构规则、切片规则、保护规则、路由规则。规则类别规则名具体逻辑优先级结构规则标题锚点识别 h1-h6 和 Word 标题样式作为块的天然边界最高结构规则表格整体块表格无论大小默认不拆分整表为一个块最高结构规则列表聚拢同一层级连续列表项合并为一个逻辑块高切片规则章节切片两个相邻标题之间的内容合并成一个候选块高切片规则字符上限单块字符数不超过 maxChars默认 1800中切片规则句子保护切分点必须落在句号/分号/换行符之后绝不在句中切中保护规则代码块保护代码片段、脚本、命令行内容禁止切片最高保护规则术语表保护连续名词解释的对句不拆分中路由规则超大对象超过 maxChars 2 倍的对象单独走摘要通道最高路由规则图片页标记无文本页记为 placeholder不进入切片队列中为什么要设优先级因为冲突是常态。一个表格 20 行 * 8 列、撑满 A4 纸按不拆分规则它是一个整体块但它又远超 maxChars。这时候必须有一个仲裁顺序先看路由规则是不是超大对象是就直接走摘要通道不再纠结切不切如果不走摘要再看结构规则是表格整体块此时允许打破字符上限但记录一个 warning最后才轮到字符上限规则。仲裁顺序写死不会今天切明天不切。2.3 为什么规则必须硬确定性优先于聪明有人问我规则这么写死遇到没见过的文档结构怎么办我的回答是没见过的结构宁可切得粗糙一点也不要让预处理行为变得不可预测。硬规则的价值有三个第一可调试。某天模型回答效果差了你能一条一条回放规则精确到哪一行代码把文本切成这个样子的如果上了模型智能分片答案无法复现排查就变成了玄学。第二可压测。规则确定后我能拿 1000 份文档离线跑分片统计分片失败率、切割点命中率、超长块比例每个指标都能量化。第三成本为零。L0 层不加载模型100 份文档分片只要几百毫秒而用大模型做一次分片决策动辄几秒。预处理是高频操作每条文档进来都要跑用规则是唯一经济上成立的方案。3. Node.js 流水线实现从原始文件到结构化分片的代码路径3.1 解析选型mammoth、pdf-parse、exceljs 的组合方案整个流水线第一步是把 office 二进制解析成结构化中间格式。我在 Node.js 生态里对比过几个库最终组合是docxmammoth。它能把 .docx 转成 HTML保留 h1-h6、table、p、li 这些标签。比 extractRawText 直接给纯文本强太多因为标题层级还在。pdfpdf-parse。轻量好集成但要注意它按页输出文本页与页之间不会自动加分隔标记需要自己补。扫描版 PDF 它基本无能为力我这边另用 OCR 服务兜底。xlsxexceljs。用于读 .xlsx按工作表 行 列组织成二维数组转成统一的表格块。pptx直接放弃了文本级解析用 pptx-parser 提取文本但只做标题和正文分离。解析完统一输出为中间格式结构大概是这样{ type: doc, title: 2024年度项目管理规范, blocks: [ { type: heading, level: 1, text: 第一章 总则 }, { type: paragraph, text: 为进一步规范项目管理流程…… }, { type: heading, level: 2, text: 1.1 项目立项 }, { type: table, rows: [[字段, 说明], [...] ] }, { type: list, items: [项一, 项二] }, ] }3.2 分片器核心实现标题锚点 句子保护 上限收敛拿到中间格式后进入分片器。我的实现思路是三步走先按标题生成候选块再对超长块做二次拆分最后校验句子完整性和上限。第一步按标题锚点切块。遍历 blocks遇到 heading 就开一个新块把后续内容塞进去直到遇到下一个 heading。function cutByHeadings(blocks) { const chunks []; let current { heading: null, body: [] }; for (const block of blocks) { if (block.type heading) { if (current.body.length) { chunks.push(current); } current { heading: block, body: [] }; } else { current.body.push(block); } } if (current.body.length) { chunks.push(current); } return chunks; }第二步处理超长块。单个候选块连续长度超过 maxChars并且内部有多个段落时按段落边界切只有一段超长按标点位置句号、分号、换行找最近切点。function splitLongBody(bodyText, maxChars) { const sentences bodyText.split(/(?[。\n])/); const result []; let buf ; for (const sent of sentences) { if ((buf sent).length maxChars buf.length 0) { result.push(buf); buf sent; } else { buf sent; } } if (buf.length) result.push(buf); return result; }第三步校验规则。这里有个细节split 用的正则里用到了 JS 的 lookbehindNode.js 8 以上支持没问题但注意正则表达式别写复杂到影响超大文本性能。我当时在 20MB 的日志型文档上跑lookbehind 加中文标点V8 卡了近半秒后来换成先按 \n 分段再按标点补判断速度快一个量级。3.3 规则引擎仲裁一个函数把规则变成决策矩阵分片过程中最麻烦的其实是规则的仲裁顺序。我把决策逻辑收拢成一个函数输入候选块输出处理策略normal / split / summary / skip。function routeCandidate(candidate, ctx) { const charLen candidate.text.length; // 1. 路由规则优先 if (candidate.type img-placeholder) return skip; if (charLen ctx.maxChars * 2) return summary; // 2. 保护规则 if (candidate.type code || candidate.type table) { if (charLen ctx.maxChars) { ctx.warnings.push(oversize-${candidate.type}:${candidate.heading}); } return normal; } // 3. 切片规则 if (charLen ctx.maxChars) return split; return normal; }实际生产代码比这个长不少但核心思想就是这个决策必须线性、可预测。每一份文档的每个块最终落在四种策略中的一种全部记录下来方便后面验证。4. 我被文档烦得最多的六个坑逐案复盘排查链路这一章价值可能比前面所有设计都大。因为我踩过的这些坑全部是看起来没问题但模型就是答不对的隐形杀手。4.1 坑一mammoth 提取的层级样式丢失标题全变成正文第一版我直接调 mammoth 的 extractRawText代码简单输出是纯文本。跑下来发现Word 里用标题1/标题2样式的标题提取后和其他段落没有区别我的分片逻辑完全找不到锚点。换 convertToHtml 之后HTML 里的 h1-h6 标签把层级带出来了。但新问题跟着来有些同事的文档标题是用超大字号手动排的没有用 Word 样式。mammoth 对这种情况不会输出 h 标签标题又丢了。排查链路先抽查 10 份问题文档的 HTML 输出发现样式标题能识别手动大字号标题识别不了。最终两个兜底一起上一是正则匹配第[一二三四五六七八九十百千]章第[0-9]条这类模式强制提升为 heading二是对字体大小超过正文 1.5 倍的段落在 HTML 解析里做启发式判断提升为 heading。启发式会引入误判但宁可多切几块也不能让标题混在正文里。4.2 坑二PDF 页面边界把表格劈成两半扫描版 PDF 是 OCR 的问题这还好发现。真正阴险的是表格恰好跨页的 PDF。比如某个采购清单表头在第 3 页表体一部分在第 4 页。pdf-parse 按页返回文本我的分片逻辑把第 3 页末尾和第 4 页开头各当成独立段落结果表格被劈成两半列头信息和数据行完全分离。修复办法是给 pdf-parse 的原始输出加一层边界页粘连逻辑检测当前页末尾和下一页开头是否构成完整表格行。表格行特征很简单用以回车结尾但中间有多个连续空格或制表符和下一页开头仍是多列形态来判断。具体实现是维护一个 pendingLine如果上一页的最后一行以|或连续 2 个以上空格结尾就与下一页首行拼接。这个规则让表格碎片恢复率从 61% 提升到 93%。剩下的 7% 是极端情况我直接标记为table-fragment不进模型。4.3 坑三并发分片时内存暴涨Node 进程被 OOM预处理模块上线初期我图性能用 Promise.all 一次性把整个目录 100 份文档全部并发解析。结果 Node 进程内存直接飙到 2GB小服务器直接被 OOM killer 干掉。排查链路很短内存 profile 一开就发现pdf-parse 对单份大型 PDF 的文本对象持有时间是解析期的十几倍mammoth 的 HTML 字符串也没及时释放加上并发 100 份堆内存直接爆。解决没有用复杂方案改成异步并发限流一次最多 6 个文件用 p-limit 或者自己写个计数器都行。核心是每处理完一份文档把大字符串引用置空主动请求 GC。实测内存峰值从 2GB 降到 400MB处理总耗时反而没怎么增加因为瓶颈本来就在磁盘 IO。4.4 坑四固定 maxChars 切中文把句子腰斩这个坑很典型。一开始我把 maxChars 设成 1500代码按字符数硬切。模型问答的效果非常差去翻分片日志才发现大量切片落在句子中间比如根据《合同-法》第三条的规定被切成了根据《合同 法》第三条规定。模型拿到的单块内容语义残缺回答质量全废。修复有两个点。第一切分位置必须落在标点后标点集合配置成可扩展中文句号、逗号、分号、换行、分号加右括号。第二对《这类特殊字符做保护切点之前如果存在未闭合的《就继续往前找句号。这个规则很朴素但让句子断裂率从 12% 降到 0.3%。4.5 坑五规则优先级写反超大表格走错了通道仲裁顺序我在第二版调过一次就是因为一个 300 行的大表。最初路由规则排在切片规则后面结果大表被判断为超长 - split进入拆分逻辑。但表格一旦拆行后面的问答就彻底乱套比如第三季度合计这一行被拆没了模型回答查不到第三季度数据。把路由规则超大对象进摘要通道提到最前面之后大表不再拆分单独交给摘要生成问题消失。这件事给我的教训是规则的优先级必须写在文档里每次改规则先看仲裁序列表不要凭感觉加新规则。4.6 坑六Windows 路径和中文文件名的编码问题最后一个是纯 Node.js 的环境坑。公司内部很多人用 Windows 分享文档文件路径带中文 空格比如D:\项目文件\2024年 制度 汇总.docx。Node 18 在 Windows 下一般没大问题但我在 Linux 部署机上收到这些文件时文件名乱码、路径解析失败。排查时发现是上传环节把文件名用成了 UTF-8 之外的编码。统一在接收文件入口处做一次名称规范化转成 UTF-8 NFC 形式并把路径里的空格和特殊字符做安全替换。虽然不算文档解析的坑但在真实办公环境里这种问题比技术问题更频繁。5. 分片质量的验证方式与一次真实的调参过程5.1 不走模型评分我用四个量化指标验收分片质量很难主观判断我没调大模型来打分而是定了四个硬指标离线验收时直接跑指标定义及格线超限块占比单块字符数超过 maxChars 的块数 / 总块数 2%句子断裂率切断位置在句中的块数 / 总块数 1%结构保留率分片中含 heading 的块数 / 总块数 80%路由准确率系统判定路由策略与人工判定一致的比例 95%这套指标统计下来整体稳定在超限块 1.2%句子断裂率 0.3%结构保留率 92%路由准确率 96%。5.2 一次带着数据说话的调参过程上线后第三周不断有用户反馈问制度文档时模型经常答出过时内容。我去查分片日志发现一个规律最新版本制度文档里同一个章节会被切成两块第一块是新版内容第二块是附录里粘贴的旧版条款。模型拿到两个块分不清谁新谁旧。排查到根因是分片时没有任何版本元信息被标记。我在 L0 规则里加了一条如果文档内容中出现修订版本号生效日期废止等关键词自动填充一个 version_meta 字段并把块头部注入本文档版本号2024V3这样的上下文前缀。这样模型每块都能看到版本信息。改完一周后同一个问题的误答率降了一半以上。这次让我意识到L0 规则要不停从业务反馈里倒推迭代而不是上线就完事。5.3 我对这套方案的整体评价从第一次被本地模型上下文窗口打脸到 L0 硬规则调度跑通前后大概三周。现在这套模块每天处理几十份真实办公文档稳定运行没有一次因为预处理问题导致模型报错。Node.js 在这个场景下的表现超出我预期异步 IO 处理文档解析很顺手mammoth 和 pdf-parse 生态够成熟唯一的短板是深度办公格式比如复杂嵌套表格、宏文档需要自己二次处理但这是任何语言都要面对的事。最后分享一个建议如果你也在做本地 AI 办公文档相关的项目先别急着调 prompt 或者换模型把输入侧的分片和规则做好收益往往比你想象的更大。而 L0 规则迭代最好的素材就是每一次模型答错的案例——把它们攒下来反推是哪条规则漏了比再调十个提示词都管用。
直连 AI 之前我低估了文档预处理这道工序直到被本地模型反复折腾到没脾气。先说背景。我在做一套完全跑在本地的文档问答系统模型用的开源大模型7B 级别负责读企业内部的 Word、PDF、Excel然后回答某某制度第三版改了啥这张表去年Q2的数据是多少这类问题。最初图省事直接把文档提取成纯文本往模型上下文里一塞就完事。结果第一天就被打脸一份 80 页的制度文件提取出的纯文本超过 15 万字符本地模型上下文窗口根本接不住直接报错就算硬塞进去模型回答也是前言不搭后语完全抓不住第几章第几条这种结构信息。于是我做了一个 Node.js 写的前置预处理模块专门负责把办公文档切成适合模型消费的块并加了一层所谓的 L0 自然语言硬规则调度决定每块文本怎么切、切完怎么送、哪些块根本不送。这篇文章就是把整个过程的思路和踩过的坑完整复盘一遍。适合谁看如果你的本地 AI 应用要处理真实办公文档而你现在还在提取文本 - 直接拼接 - 丢给模型这条路上那这篇基本就是帮你在下一个坑前面踩刹车。1. 直连 AI 的效果惨案办公文档预处理为什么躲不掉1.1 Token 超限不是配置问题是数学问题很多人以为上下文窗口超了调大参数就行。本地部署过模型就明白窗口大小受显存和推理引擎限制7B 模型开 32K 上下文KV Cache 就能吃掉几个 GB 显存再往上加生成速度肉眼可见地变慢。而一份真实办公文档有多夸张我统计过手头 200 份文档纯文本平均长度是 6.2 万字符最大的是一份带附件的项目验收报告24 万字符。哪怕 32K 窗口硬撑也就够塞正文的零头。更隐蔽的问题在 token 换算。纯英文文档一个 token 大概对应 4 个字符但中文文档一个汉字在多数 tokenizer 里接近一个 token三个 GB 级文本就是几十万 token。所以在预处理阶段分词器、字符数、token 上限之间必须做一次统一换算否则你设的每片 2000 字符在模型侧可能已经超窗。1.2 结构信息丢失模型读到的是一堆没有骨架的字符直连的第二个问题是对文档结构的破坏。直接用正则或者简单 split 去分段标题层级、表格关系、列表嵌套、页眉页脚全部拍平。模型拿到这种没有标题层级、没有表格行列关系的扁平文本只能靠语感猜这一段是在说制度条款那一段是在说执行流程。如果文档里有一张 5 列 20 行的对比表转成纯文本后关系完全丢失模型甚至会把列头当成句子去理解。我后来做了一个实验同一份 20 页的合同A 版本是纯文本直连B 版本是经过结构化分片后再送模型。问违约责任在第几条、具体怎么约定A 版本从第 17 页找了一段相关文字但没给条款号B 版本直接定位到第十一条 违约责任连子项都列全了。差别就在结构保留。1.3 大对象混入上下文一个表格毁掉整轮问答还有一种情况比超限更恶心就是文档里嵌了一张超宽表格。比如 Excel 导出的 PDF 里有一张 30 列的数据表文本提取出来后单行就有几千字符。直连模型时这一行就会把上下文里其他有效信息的相对权重全部稀释模型注意力全都扑在那一堆数字上问什么都答不上来。预处理模块在这里承担的是一个路由角色普通段落等价于给模型看超大表格走单独通道抽摘要、按列拆分、或者干脆不送图片/扫描页走 OCR 分支或标记跳过。这些决策不能靠模型来完成成本太高速度太慢就用规则来定。这就引出了 L0 层的定位。2. L0 硬规则调度系统划分边界、定义规则、确定优先级2.1 L0/L1/L2 分层的思路别让大模型干小模型的活在我这套设计里文档处理分成三层。L0 层是纯代码规则不加载任何模型只做确定性操作解析文档、分片、标记类型、判断是否超长、判断是否为表格/代码块。特点是快、可复现、能审计。L1 层用小型模型比如 embedding 或文本分类模型做语义粗筛决定某一块文本和当前问题是否相关这一层是半智能。L2 层才是大模型深度推理做实际问答或者总结。L0 的定位就是守门员在上模型之前把决策面缩小。所有能用规则给定的边界绝不劳烦模型。比如标题下第一段属于正文表格列数和行数超过阈值就拆分句子不完整就不进入切片这些逻辑写成硬规则比任何提示词都稳定。2.2 我的 L0 规则集和优先级仲裁这里把我实际沉淀下来的规则清单列一份分成四类结构规则、切片规则、保护规则、路由规则。规则类别规则名具体逻辑优先级结构规则标题锚点识别 h1-h6 和 Word 标题样式作为块的天然边界最高结构规则表格整体块表格无论大小默认不拆分整表为一个块最高结构规则列表聚拢同一层级连续列表项合并为一个逻辑块高切片规则章节切片两个相邻标题之间的内容合并成一个候选块高切片规则字符上限单块字符数不超过 maxChars默认 1800中切片规则句子保护切分点必须落在句号/分号/换行符之后绝不在句中切中保护规则代码块保护代码片段、脚本、命令行内容禁止切片最高保护规则术语表保护连续名词解释的对句不拆分中路由规则超大对象超过 maxChars 2 倍的对象单独走摘要通道最高路由规则图片页标记无文本页记为 placeholder不进入切片队列中为什么要设优先级因为冲突是常态。一个表格 20 行 * 8 列、撑满 A4 纸按不拆分规则它是一个整体块但它又远超 maxChars。这时候必须有一个仲裁顺序先看路由规则是不是超大对象是就直接走摘要通道不再纠结切不切如果不走摘要再看结构规则是表格整体块此时允许打破字符上限但记录一个 warning最后才轮到字符上限规则。仲裁顺序写死不会今天切明天不切。2.3 为什么规则必须硬确定性优先于聪明有人问我规则这么写死遇到没见过的文档结构怎么办我的回答是没见过的结构宁可切得粗糙一点也不要让预处理行为变得不可预测。硬规则的价值有三个第一可调试。某天模型回答效果差了你能一条一条回放规则精确到哪一行代码把文本切成这个样子的如果上了模型智能分片答案无法复现排查就变成了玄学。第二可压测。规则确定后我能拿 1000 份文档离线跑分片统计分片失败率、切割点命中率、超长块比例每个指标都能量化。第三成本为零。L0 层不加载模型100 份文档分片只要几百毫秒而用大模型做一次分片决策动辄几秒。预处理是高频操作每条文档进来都要跑用规则是唯一经济上成立的方案。3. Node.js 流水线实现从原始文件到结构化分片的代码路径3.1 解析选型mammoth、pdf-parse、exceljs 的组合方案整个流水线第一步是把 office 二进制解析成结构化中间格式。我在 Node.js 生态里对比过几个库最终组合是docxmammoth。它能把 .docx 转成 HTML保留 h1-h6、table、p、li 这些标签。比 extractRawText 直接给纯文本强太多因为标题层级还在。pdfpdf-parse。轻量好集成但要注意它按页输出文本页与页之间不会自动加分隔标记需要自己补。扫描版 PDF 它基本无能为力我这边另用 OCR 服务兜底。xlsxexceljs。用于读 .xlsx按工作表 行 列组织成二维数组转成统一的表格块。pptx直接放弃了文本级解析用 pptx-parser 提取文本但只做标题和正文分离。解析完统一输出为中间格式结构大概是这样{ type: doc, title: 2024年度项目管理规范, blocks: [ { type: heading, level: 1, text: 第一章 总则 }, { type: paragraph, text: 为进一步规范项目管理流程…… }, { type: heading, level: 2, text: 1.1 项目立项 }, { type: table, rows: [[字段, 说明], [...] ] }, { type: list, items: [项一, 项二] }, ] }3.2 分片器核心实现标题锚点 句子保护 上限收敛拿到中间格式后进入分片器。我的实现思路是三步走先按标题生成候选块再对超长块做二次拆分最后校验句子完整性和上限。第一步按标题锚点切块。遍历 blocks遇到 heading 就开一个新块把后续内容塞进去直到遇到下一个 heading。function cutByHeadings(blocks) { const chunks []; let current { heading: null, body: [] }; for (const block of blocks) { if (block.type heading) { if (current.body.length) { chunks.push(current); } current { heading: block, body: [] }; } else { current.body.push(block); } } if (current.body.length) { chunks.push(current); } return chunks; }第二步处理超长块。单个候选块连续长度超过 maxChars并且内部有多个段落时按段落边界切只有一段超长按标点位置句号、分号、换行找最近切点。function splitLongBody(bodyText, maxChars) { const sentences bodyText.split(/(?[。\n])/); const result []; let buf ; for (const sent of sentences) { if ((buf sent).length maxChars buf.length 0) { result.push(buf); buf sent; } else { buf sent; } } if (buf.length) result.push(buf); return result; }第三步校验规则。这里有个细节split 用的正则里用到了 JS 的 lookbehindNode.js 8 以上支持没问题但注意正则表达式别写复杂到影响超大文本性能。我当时在 20MB 的日志型文档上跑lookbehind 加中文标点V8 卡了近半秒后来换成先按 \n 分段再按标点补判断速度快一个量级。3.3 规则引擎仲裁一个函数把规则变成决策矩阵分片过程中最麻烦的其实是规则的仲裁顺序。我把决策逻辑收拢成一个函数输入候选块输出处理策略normal / split / summary / skip。function routeCandidate(candidate, ctx) { const charLen candidate.text.length; // 1. 路由规则优先 if (candidate.type img-placeholder) return skip; if (charLen ctx.maxChars * 2) return summary; // 2. 保护规则 if (candidate.type code || candidate.type table) { if (charLen ctx.maxChars) { ctx.warnings.push(oversize-${candidate.type}:${candidate.heading}); } return normal; } // 3. 切片规则 if (charLen ctx.maxChars) return split; return normal; }实际生产代码比这个长不少但核心思想就是这个决策必须线性、可预测。每一份文档的每个块最终落在四种策略中的一种全部记录下来方便后面验证。4. 我被文档烦得最多的六个坑逐案复盘排查链路这一章价值可能比前面所有设计都大。因为我踩过的这些坑全部是看起来没问题但模型就是答不对的隐形杀手。4.1 坑一mammoth 提取的层级样式丢失标题全变成正文第一版我直接调 mammoth 的 extractRawText代码简单输出是纯文本。跑下来发现Word 里用标题1/标题2样式的标题提取后和其他段落没有区别我的分片逻辑完全找不到锚点。换 convertToHtml 之后HTML 里的 h1-h6 标签把层级带出来了。但新问题跟着来有些同事的文档标题是用超大字号手动排的没有用 Word 样式。mammoth 对这种情况不会输出 h 标签标题又丢了。排查链路先抽查 10 份问题文档的 HTML 输出发现样式标题能识别手动大字号标题识别不了。最终两个兜底一起上一是正则匹配第[一二三四五六七八九十百千]章第[0-9]条这类模式强制提升为 heading二是对字体大小超过正文 1.5 倍的段落在 HTML 解析里做启发式判断提升为 heading。启发式会引入误判但宁可多切几块也不能让标题混在正文里。4.2 坑二PDF 页面边界把表格劈成两半扫描版 PDF 是 OCR 的问题这还好发现。真正阴险的是表格恰好跨页的 PDF。比如某个采购清单表头在第 3 页表体一部分在第 4 页。pdf-parse 按页返回文本我的分片逻辑把第 3 页末尾和第 4 页开头各当成独立段落结果表格被劈成两半列头信息和数据行完全分离。修复办法是给 pdf-parse 的原始输出加一层边界页粘连逻辑检测当前页末尾和下一页开头是否构成完整表格行。表格行特征很简单用以回车结尾但中间有多个连续空格或制表符和下一页开头仍是多列形态来判断。具体实现是维护一个 pendingLine如果上一页的最后一行以|或连续 2 个以上空格结尾就与下一页首行拼接。这个规则让表格碎片恢复率从 61% 提升到 93%。剩下的 7% 是极端情况我直接标记为table-fragment不进模型。4.3 坑三并发分片时内存暴涨Node 进程被 OOM预处理模块上线初期我图性能用 Promise.all 一次性把整个目录 100 份文档全部并发解析。结果 Node 进程内存直接飙到 2GB小服务器直接被 OOM killer 干掉。排查链路很短内存 profile 一开就发现pdf-parse 对单份大型 PDF 的文本对象持有时间是解析期的十几倍mammoth 的 HTML 字符串也没及时释放加上并发 100 份堆内存直接爆。解决没有用复杂方案改成异步并发限流一次最多 6 个文件用 p-limit 或者自己写个计数器都行。核心是每处理完一份文档把大字符串引用置空主动请求 GC。实测内存峰值从 2GB 降到 400MB处理总耗时反而没怎么增加因为瓶颈本来就在磁盘 IO。4.4 坑四固定 maxChars 切中文把句子腰斩这个坑很典型。一开始我把 maxChars 设成 1500代码按字符数硬切。模型问答的效果非常差去翻分片日志才发现大量切片落在句子中间比如根据《合同-法》第三条的规定被切成了根据《合同 法》第三条规定。模型拿到的单块内容语义残缺回答质量全废。修复有两个点。第一切分位置必须落在标点后标点集合配置成可扩展中文句号、逗号、分号、换行、分号加右括号。第二对《这类特殊字符做保护切点之前如果存在未闭合的《就继续往前找句号。这个规则很朴素但让句子断裂率从 12% 降到 0.3%。4.5 坑五规则优先级写反超大表格走错了通道仲裁顺序我在第二版调过一次就是因为一个 300 行的大表。最初路由规则排在切片规则后面结果大表被判断为超长 - split进入拆分逻辑。但表格一旦拆行后面的问答就彻底乱套比如第三季度合计这一行被拆没了模型回答查不到第三季度数据。把路由规则超大对象进摘要通道提到最前面之后大表不再拆分单独交给摘要生成问题消失。这件事给我的教训是规则的优先级必须写在文档里每次改规则先看仲裁序列表不要凭感觉加新规则。4.6 坑六Windows 路径和中文文件名的编码问题最后一个是纯 Node.js 的环境坑。公司内部很多人用 Windows 分享文档文件路径带中文 空格比如D:\项目文件\2024年 制度 汇总.docx。Node 18 在 Windows 下一般没大问题但我在 Linux 部署机上收到这些文件时文件名乱码、路径解析失败。排查时发现是上传环节把文件名用成了 UTF-8 之外的编码。统一在接收文件入口处做一次名称规范化转成 UTF-8 NFC 形式并把路径里的空格和特殊字符做安全替换。虽然不算文档解析的坑但在真实办公环境里这种问题比技术问题更频繁。5. 分片质量的验证方式与一次真实的调参过程5.1 不走模型评分我用四个量化指标验收分片质量很难主观判断我没调大模型来打分而是定了四个硬指标离线验收时直接跑指标定义及格线超限块占比单块字符数超过 maxChars 的块数 / 总块数 2%句子断裂率切断位置在句中的块数 / 总块数 1%结构保留率分片中含 heading 的块数 / 总块数 80%路由准确率系统判定路由策略与人工判定一致的比例 95%这套指标统计下来整体稳定在超限块 1.2%句子断裂率 0.3%结构保留率 92%路由准确率 96%。5.2 一次带着数据说话的调参过程上线后第三周不断有用户反馈问制度文档时模型经常答出过时内容。我去查分片日志发现一个规律最新版本制度文档里同一个章节会被切成两块第一块是新版内容第二块是附录里粘贴的旧版条款。模型拿到两个块分不清谁新谁旧。排查到根因是分片时没有任何版本元信息被标记。我在 L0 规则里加了一条如果文档内容中出现修订版本号生效日期废止等关键词自动填充一个 version_meta 字段并把块头部注入本文档版本号2024V3这样的上下文前缀。这样模型每块都能看到版本信息。改完一周后同一个问题的误答率降了一半以上。这次让我意识到L0 规则要不停从业务反馈里倒推迭代而不是上线就完事。5.3 我对这套方案的整体评价从第一次被本地模型上下文窗口打脸到 L0 硬规则调度跑通前后大概三周。现在这套模块每天处理几十份真实办公文档稳定运行没有一次因为预处理问题导致模型报错。Node.js 在这个场景下的表现超出我预期异步 IO 处理文档解析很顺手mammoth 和 pdf-parse 生态够成熟唯一的短板是深度办公格式比如复杂嵌套表格、宏文档需要自己二次处理但这是任何语言都要面对的事。最后分享一个建议如果你也在做本地 AI 办公文档相关的项目先别急着调 prompt 或者换模型把输入侧的分片和规则做好收益往往比你想象的更大。而 L0 规则迭代最好的素材就是每一次模型答错的案例——把它们攒下来反推是哪条规则漏了比再调十个提示词都管用。
