把一堆PDF、Word、扫描件扔给本地大模型，结果没跑几步就报"上下文超限"，相信折腾过本地智能体的人都懂这种痛。最近我在办公文档自动化这个场景里，把"文档预处理 + 任务调度 + 长文本超限兜底"整条链路重新搭了一遍，实测下来效果稳定，今天就把它拆开来讲透。

这篇文章不聊云端API，也不涉及任何私有网络手段，而是聚焦一个纯本地方案：本地智能体如何承接真实的办公文档流程，如何设计文档预处理管线，又如何把长文本超限这个硬骨头通过分块、调度和降级策略啃下来。适合正在做本地RAG、办公自动化、私有知识库，或者被大模型上下文长度折磨到怀疑人生的朋友参考。

1. 先把这个全链路拆开看

1.1 一条文档处理链路要经过哪些环节

很多人一上来就直接调大模型接口，把整份合同、年报、会议纪要一股脑塞给智能体，然后坐等结果。一旦文档超过上下文窗口，整个任务直接死掉，哪怕只超了几百字也毫无办法。真正扛得住真实办公场景的链路，至少要有四个环节：

• 文档接入：收集 PDF、Word、Excel、扫描件等不同来源的原始文件。
• 预处理：把各种格式统一转成纯文本，清洗噪音内容，恢复目录结构，切分成可独立处理的小块。
• 模型调度：把切好的块按依赖关系交给本地大模型，而不是一次性全塞进去。
• 结果聚合：把各块的分析结果、抽取字段、摘要合并成最终输出。

我之前的错误就是把第二和第三步混为一谈，以为"让模型自己读全文就行"。实际上大模型面对超长文本时，注意力会被开头和结尾的段落拖走，中间部分经常被忽略。文档预处理看起来只是在给模型"喂饭"，实际上决定了任务能不能跑通、跑得好不好。

1.2 为什么必须"本地化"

办公场景里选择本地智能体，不是单纯的省钱或追潮流。我接手过几个实际项目后，最大的感受是：本地化的核心价值在于数据不出本机，同时可以拿到完全的调用自由度。

具体来说，本地化带来的直接好处有三点：

• 敏感文档不外流：合同、薪资表、内部技术文档这类内容，企业IT审计第一条就是不允许上传到外部服务。本地模型再怎么跑，数据始终留在磁盘和内存里。
• 无按量计费压力：本地跑模型只耗电，不耗token。文档批量预处理时，可能一个晚上要跑几千个文件，如果用按量付费API，成本会非常难看，而本地显卡能扛住。
• 可自由裁剪链路：本地部署时，模型、分块逻辑、调度脚本都是自己的，可以针对文档类型反复调优，甚至给某个特定步骤单独挂一个小模型做预处理，云端方案很难这么细。

另外，本地部署对硬件的要求也没有想象中那么高。纯办公文档预处理场景，处理文本的模型用7B到14B参数量就够了，配合16GB以上内存，普通工作站的CPU也能跑，不一定要顶级GPU。真正吃显存的是长上下文推理，这恰好是我们要用分块策略去规避的重点。

2. 文档预处理：最容易被低估的前半程

2.1 从 PDF / Word / 扫描件里稳定地把文本抠出来

办公文档最麻烦的不是格式多，而是“看起来是文本，实际上不是文本”。PDF里常有三种情况：有文字层的电子PDF、扫描成图片的纯图像PDF、表格和页眉页脚混排的复杂版式。Word文档则可能嵌入了批注、修订记录、文本框，直接读正文会被这些元数据污染。

我在实际项目中整理了一套比较稳的提取顺序：

1. PDF优先尝试文本层提取。用pdfplumber或者PyMuPDF直接读取内嵌文字，保留页码信息。这个阶段能拿到的就是干净文本。
2. 如果提取出的字数接近0，说明是扫描件，转用OCR通道。本地优先考虑PaddleOCR，中文识别率比Tesseract好不少。注意把扫描页面导出成300dpi的PNG再识别，分辨率低了错误率会成倍增长。
3. Word文档使用python-docx读取正文段落，必要时把表格用docx.table单独抽取，转成Markdown表格格式。
4. Excel文档转成"工作表名 + 行列坐标 + 单元格内容"的结构化文本，避免直接to_csv丢失公式逻辑。

这里有一个我踩过的坑：PDF提取出来的文本，经常伴有奇怪的断行和空格。比如"本 公司 将于 2024 年 1 月 1 日起执行新规"，每两个字符之间都被插入了不可见文本节点。解决方法是先按字符密度做一次粘连判断，把异常稀疏的行重新合并，再做常规清洗。

2.2 清洗是给大模型“减负”的关键操作

清洗这一步直接影响到后面分块的质量。我见过很多人的清洗只做了strip()和去空白，结果模型把页眉页脚、页码、"第X页共Y页"、水印文字都当成正文理解，最后生成的分析结论里莫名其妙混入“机密文件”字样。

我的清洗规则可以分成三层，实用优先：

• 第一层：结构噪音。去掉页眉页脚、页码、目录页、重复的标题行。办公文档的页脚往往包含公司名称、版权声明和页码，这些属于版面元素而非正文。
• 第二层：内容噪音。去掉空行、非法字符、连续标点、乱码替换符。扫描件OCR出来的文本尤其需要这一步，比如“□”和“■”之类的占位符。
• 第三层：语义噪音。检测并删除重复段落。很多制度文件会把同一段注意事项贴在每章末尾，如果不去重，分块后同一个结论会被反复引用，浪费上下文空间且干扰抽取结果。

清洗时还要注意保留文档内的小标题层级。办公文档的章节目录是天然的语义边界，后续分块如果依据这些标题来切，效果远好于按固定字数硬切。我的做法是在清洗阶段先识别各级标题，输出成带有“H1/H2/H3”标记的结构化文本，这样分块器就能按结构树来切割。

为了方便调试，我会把每份文档的清洗结果输出成一张“清洗前vs清洗后字数和关键内容对比表”，跑完批量任务后扫一眼就能看出哪些规则过于激进、哪些又没生效。

这个表的逻辑是把清洗比转化成可观测的指标，避免预处理变成“玄学”。

3. 硬骨头在长文本：超限问题怎么治

3.1 超限的本质不是“字太多”

刚开始遇到"context length exceeded"这类报错时，我的第一反应是“换个更大上下文的模型”。换了大模型之后确实能多撑一段，但很快又碰到两个新问题：更长的上下文不仅推理更慢，而且质量下降明显。后来我才反应过来，超限的本质其实是上下文窗口与任务需要的文本量不匹配，而不是字太多。

拿本地部署的模型举例，量化后的7B模型常见上下文是8K到32K。我手上处理的办公文档动辄上百页，年报类文档能到20万字。哪怕上下文再翻一倍，也装不下这类文档的全量内容。而且就算硬塞进去，模型对中间部分的注意力会显著衰减，真正有效的信息密度反而下降。这个现象在长上下文模型上一样存在，只是程度不同。

所以正确思路不是“让模型读长文”，而是“让模型不需要读长文也能给出准确结果”。这句话听起来像绕口令，但做起来很实在：把长文档切块后，要么逐块抽取再合并，要么只检索关键块再让模型分析。

3.2 分块策略：把长文本切成能消化的段落

分块策略是整套链路里回报率最高的一步。我试验过固定字符切块、滑动窗口切块、按语义切块三种方式，最终保留的是“结合结构标记的语义切块”。

具体操作是：

• 先按H1/H2/H3标题切分，把文档拆成段落树。
• 每个段落树的叶子节点对应一个最小语义块，一般控制在500到1000个中文字符。
• 如果某个章节特别长，没有次级标题，再用「段落完整性优先 + 最大长度兜底」的方式继续切，优先在句号、分号处切断。

切块的时候要留一点重叠，比如上一块的末尾80个字符和下一块的开头保留重合。这样做的原因是：很多信息点在段落交界处，例如“根据上述条款，乙方需承担……”这句话的“上述条款”指向前文，如果切块时把“指代”和“被指代内容”分开，后续检索就会遗漏关键信息。

切块之后还要做一块元数据管理。每块除了正文内容，还要带上文档ID、章节路径、页码、块序号。这样后续调度时，一旦某块分析失败，可以快速定位并重跑该块，而不是重新处理整份文档。

这里给出一个简化的切块代码思路，我已经在实际流程中使用过，可以直观参考：

def split_by_structure(cleaned_doc, max_chars=800, overlap=80): blocks = [] current_block = "" for node in cleaned_doc.structure: # 结构树节点 if len(current_block) + len(node.text) > max_chars: # 超过上限，先把当前块落盘，再开新块 blocks.append({ "id": f"block-{len(blocks)+1}", "path": node.path, "page": node.page, "content": current_block + node.text[:overlap] }) current_block = node.text[overlap:] else: current_block += node.text if current_block: blocks.append({ "id": f"block-{len(blocks)+1}", "path": node.path, "page": node.page, "content": current_block }) return blocks

这段代码没有把模型调进来参与切块，因为切块逻辑应该是确定的、可复现的，不能被模型输出扰动。真正需要模型介入的地方是后面的摘要和抽取阶段。

3.3 摘要压缩与关键信息优先

分块解决了“模型能不能读”的问题，但有时候任务需求不是逐块分析，而是要对整份文档做综述或评价。比如“这份合同的违约责任条款都有哪些变化”，这种问题如果只检索单一文本块，容易漏掉跨章节的信息。

这时我采用两层摘要策略：

• 第一层：按章节做摘要。每个章节块单独送给模型，生成300字以内的章节摘要，约等于给文档做了“目录摘要”。
• 第二层：把所有章节摘要合并，再送给模型一次，生成全文级摘要或结论。

这么做的好处是，最终送到模型手里的全文摘要远远小于原文，但又保留了主干信息。代价是信息会有蒸发，因此摘要只用于综述类任务，不用于细节抽取。细节抽取任务还是要走分块检索路线。

检索路线我用的是本地向量库，把每一块的embedding存进去，任务查询进来之后先检索Top-K最相关的块，再把候选块按原始顺序拼接成一个小型上下文。K值我通常取5到8，这样上下文里既有相关性又有连续性。需要说明的是，本地部署时的embedding模型可以选择比较轻量的版本，中文场景下效果也足够稳定。

4. 任务调度：把预处理结果变成一条流水线

4.1 调度框架选型与任务模型设计

预处理做完，文档变成了带元数据的分块集合，接下来就是调度环节。调度要回答三个问题：任务依赖怎么描述、并发怎么控制、失败怎么重跑。

我最初图省事，直接用Python脚本按顺序跑。文档少的时候看起来没问题，但一旦批量处理几百份合同，中间某一块卡住或崩溃，整个流程就得从头再来。于是我把任务模型重新设计了一下，把每个“块”定义为一个独立任务单元，任务ID就是块ID，而不是整份文档ID。

任务依赖方面，我把流程拆成了“提取 -> 清洗 -> 切块 -> 分析/摘要 -> 聚合”五个阶段。前三个阶段是纯本地IO，不依赖模型，跑得快；第四阶段开始调用本地大模型，是耗时大户；聚合阶段只在所有分析任务完成后执行一次。

调度框架我没有引入重量级分布式系统，而是直接用APScheduler或cron配合一个任务状态表。任务状态表记录每个块的任务状态：pending、running、success、failed、retrying。这个表用SQLite存就够了，单机场景完全没有必要上Redis。

任务状态表的好处是天然支持断点续跑。比如昨晚批量处理到第17份合同的时候机器断电，重启后只需要查询 failed 和 pending 的任务，把已完成的跳过，继续跑剩下的即可。

4.2 重试、并发与断点续跑的实战细节

并发控制这里有个很容易犯的错误：以为本地模型推理是CPU密集，就盲目增大并发数。实测下来，本地大模型在做推理时，多进程并发如果调度不当，反而会因为显存/内存争抢导致OOM或速度骤降。

我常用的方案是：

• 模型服务化之后用单实例多线程方式接受请求，通过请求队列控制并发数。
• 如果模型是直接通过Python脚本调用的，就用ThreadPoolExecutor(max_workers=2)这样的低成本并发，不要上来就开8个worker。
• 纯预处理阶段（提取、清洗、切块）可以放开并发，IO密集的PDF解析用ProcessPoolExecutor效果更好。
• 每份文档设置任务级超时，单块分析超过90秒就标记为失败，不阻塞后续任务。

重试策略不是无限重试。我的经验是：每块最多重试2次，且重试时间要递增。如果同一块连续失败3次，大概率是这一块内容有问题，比如模型对某种特殊排版产生了幻觉，重试再多也救不回来。此时应该人工介入或进入降级通道。

降级通道是我在这条链路里最有心得的设计之一。所谓降级，就是当某个块连续重试失败时，自动把该块内容进一步压缩或分割，再回填到队列里重跑。如果二次分割后仍然失败，就把它从“必须成功”任务中剔除，但会在最终结果里生成“该章节解析失败”的提示，而不是让整个任务失败。办公自动化场景里，完整任务失败的成本远高于单块失败，这种降级机制能保证一台机器无人值守时也能完成任务。

调度阶段的代码示意如下，核心是状态机转移：

pending -> running -> success |-> failed -> retrying -> running |-> failed -> downgrade -> pending

状态转移我用一张配置表来控制，不允许非法跳转，避免出现“任务还在running却已经被标记为success”的脏数据。

5. 常见问题与排查实录

5.1 高频踩坑清单

整套链路跑起来之后，我遇到过的问题远比想象中多。这里整理几个最高频的坑，按出现概率排序：

1. PDF文本层有字，但是乱序提取。常见于双栏版式，左栏没读完直接跳到右栏。解决思路是提取时开启layout=True参数保留坐标，再按坐标排序，而不是按流式顺序读取。

2. Word文档里出现重复段落。生成docx时前端编辑器产生的冗余结构，清洗阶段没去重的话，模型会把同一段条款当成两个不同条款来解析，导致抽取结果重复。建议在清洗后用集合方式对完全重复的段落去重。

3. 本地模型输出不稳定。同一文本块，第一次抽取出12个关键字段，第二次只抽出9个。解决方法是把输出格式改成JSON Schema约束，并且设置温度参数为0。如果模型支持，尽量用结构化生成，否则在后处理阶段做字段缺失重试。

4. 长文本分块后，章节意思断裂。明明切在句号处，但前后块还是缺了上下文。原因是中文省略号、破折号后面跟着引号的边界情况没有处理。切块正则要多补充这些边界符。

5. 任务队列积压导致内存爆炸。无界队列在批量处理时特别危险，建议用有界队列，满了之后让生产者等待，而不是无限堆积任务对象。

5.2 实战排查流程参考

如果整套链路跑完后结果奇差，不要慌，按下面的顺序排查：

• 先看清洗后的文本文案，是不是乱序或丢失关键字段。这一步出问题，后面所有环节都白搭。
• 再看分块结果，切出来的块有没有跨章节拼接，有没有内容重复。
• 接着看检索召回，对每个任务查询人工检验Top-5召回块是否真的包含答案。召回不对，分析就一定不对。
• 最后才看模型本身。模型生成长度和风格问题可以调prompt模板，模型输出字段缺失再考虑换小模型做特定步骤。

我发现一个规律：80%以上的“模型智障”问题，根源都在预处理和检索阶段，而不是模型参数。把文档结构梳理好了，哪怕模型参数量不大，也能给出可靠输出。反过来，结构混乱的文本喂给大模型，再好的模型也会被误导。

给一个具体的排查案例。之前一份年报分析任务，模型输出里出现了“2023年度亏损”的结论，但实际年报显示盈利。排查后发现，清洗阶段把表格转文本时，数值列“利润总额”旁边的两个空格被当成列分隔符，导致“-”负号被错误拆分，变成了亏损。这个问题在分块阶段又因为语义块的标题是“2023年度经营分析”，检索时优先命中，最终模型读到的是被清洗规则破坏的错误数据。修复清洗规则后，输出立刻恢复正常。

所以说，调试本地智能体，第一原则永远是：先怀疑数据，再怀疑模型。

6. 我的实操复盘与扩展建议

最后说两句我个人在实际操作中的体会。

这套全链路方案真正跑通之后，最值钱的一段不是某个模型有多能打，而是**“文档预处理 + 任务调度 + 长文本降级”形成了一个可复制的方法论**。无论以后模型换成更大上下文的版本，还是更轻量的蒸馏模型，都不需要推翻重来。只要预处理保持结构完整，调度层能够稳定重试，超限问题就有兜底方案。

如果你准备在自己项目里落地这套思路，我的建议是不要一上来就追求功能全覆盖。先挑一类最常处理的文档，比如合同或者会议纪要，把整个管道跑通，确认每个环节都有日志和状态可查，再逐步扩展文档类型。前两周的痛苦是值得的，一旦管道稳定，后续新增文档类型只需要加清洗规则和切块模板，边际成本很低。

我最近还在试验把预处理阶段的识别结果做成可视化目录，方便人工确认哪些文档需要人工复核。这个扩展方向虽然不是核心链路的一部分，但对团队协作和审计很有帮助。后续如果再深入，我可能会单独写一篇关于“文档结构树可视化”的文章。

这套东西听起来复杂，落地的过程其实就是不断跟脏数据搏斗的过程。能有耐心把每一步都做扎实，你会发现自己对本地智能体、对办公文档本身的理解，都会有完全不一样的感觉。