最近在帮团队搭一套本地智能体处理办公文档的流水线过程中踩了不少坑最典型的一个就是把一份几十页的PDF或者长篇Word直接丢给本地模型几乎百分之百报上下文超限。一开始我以为换个更大上下文窗口的模型就行后来发现根本不是模型的问题而是我喂给模型的“料”本身就有问题。把这个问题拆开揉碎之后我把整套链路从文档解析、文本清洗、语义分块到任务调度、结果汇总全部打通了现在处理一份上百页的项目文档也能稳稳跑完不爆上下文、不卡死、不丢内容。这篇文章就把这套“本地智能体 办公文档预处理 任务调度”的全链路实战经验完整记录下来包括每一环为什么这么做、参数怎么定、代码怎么写、哪些坑必须避开。适合正在折腾本地部署模型、有办公文档批量处理需求、以及被长文本超限折磨过的朋友参考。1. 为什么本地智能体一碰长文档就翻车三个绕不开的硬限制本地部署的大语言模型和云端API模型最大的区别不只是“要不要联网”而是整个推理过程受本地硬件资源的物理约束。长文档处理这件事恰恰把这种约束放到了最大。如果你不理解这里面的底层逻辑后面无论怎么调提示词、换模型都治标不治本。1.1 上下文窗口不是“无限缓存”而是“物理内存”很多人对上下文窗口的理解是“模型最多能记住多少字”其实更准确的类比应该是“模型工作台上能摊开多少纸”。每摊开一张纸模型就需要在内存里维护这张纸内容的中间状态在Transformer架构里这个中间状态叫KV Cache。Token数量越多KV Cache占用的显存就直线上升。本地环境下显存是有限的。一张24GB显存的显卡跑一个7B参数的量化模型上下文拉到32K时KV Cache可能就吃掉好几个GB如果拉到128K显存直接见底推理速度也会慢到让人怀疑人生。所以本地智能体面对长文档时的第一个限制不是模型“不愿意”看长文本而是“物理上装不下、跑不动”。我实测下来在单卡24GB环境下跑Qwen系列7B量化版把上下文开到32K去处理一份完整PDF推理速度比8K上下文慢了三倍以上而且中间一旦遇到文档里特别长的段落还会偶发显存溢出。所以真正稳妥的做法不是追求“一口气全塞进去”而是把长文本拆成模型能轻松消化的块配合调度机制按需喂入。1.2 办公文档超限的真相不是“字数多”而是“噪声多”第二个限制往往被忽略办公文档解析出来的原始文本和你在屏幕上看到的“干净文档”完全是两回事。一份20页的Word文档可能有封面、目录、页眉页脚、表格、批注、超链接、尾注一份PDF甚至可能是扫描件OCR识别出来之后还会附带大量识别错误和分页符。这些乱七八糟的东西全部加在一起Token消耗量可能比你预想的多出40%到60%。我自己做过一次统计一份正文约8000字的项目申报书用默认方式提取纯文本后字符数变成了约13000字多出来的大部分是目录每行都带页码、页眉页脚重复出现的项目名称、表格里挤成一团的单元格内容。这些噪声直接吃掉了模型的上下文空间真正有用的信息还没塞进去窗口就满了。所以解决长文本超限第一优先级不是“换更大窗口的模型”而是“把文本洗干净”。把噪声去掉之后同样的上下文窗口能装下的有效信息量会大幅提升。这也是整套链路里投入产出比最高的一步。1.3 任务调度为什么绕不开单次不能处理那就分多次哪怕文本洗干净了一份真正长的文档比如上百页的行业报告、技术手册拆成块之后仍然可能超过上下文窗口的总容量。这时候唯一的出路就是“拆分成多次任务分步处理”。但分多次处理又带来新问题上一次任务的结果怎么传递给下一次每次任务之间的状态怎么维护全部串行执行会不会太慢这就是任务调度要解决的。你可以把调度器理解成一个排队叫号系统——文档被切成若干块后变成一组任务调度器按顺序把它们分配给模型执行并把前一步的结果汇总、压缩、传递给下一步。这一步做不好会出现两个典型翻车现场一是所有块一股脑并发提交给模型结果显存直接爆掉二是串行处理时上下文越滚越长到后面照样超限。所以调度的核心不是“排队”这么简单而是“排队 上下文管理 结果回收”三位一体。2. 文档预处理三板斧提取、清洗、分块这是整套链路里最花时间、也最值得花时间的部分。预处理做得好后面所有环节都顺做得粗糙模型回答的质量会断崖式下降。我在实际操作中把它拆成四个步骤格式解析、噪声清洗、语义分块、长文分层。2.1 第一步不同格式的文档怎么抽出“能用的纯文本”办公文档最常见的格式就是Word、PDF、PPT、Excel四大类。每种格式的解析工具和坑都不一样我分别说一下自己用过之后留下的方案。Word文档docx推荐用python-docx底层解析的是XML结构能保留段落和表格的基本层级。注意不要直接用python-docx把每个段落append到一个字符串就完事尽量把“段落级别”的信息保留下来后续分块时需要用到。对于老版的doc格式python-docx不支持可以先用LibreOffice转成docx再处理实测转换质量稳定。PDF文档分两种。文本型PDF直接从Word导出的用pdfplumber解析效果最好因为它能保留文字的坐标信息方便后续做页眉页脚过滤。扫描型PDF则需要OCR推荐PaddleOCR中文识别准确率在开源方案里属于第一梯队而且支持本地离线部署。扫描件走OCR这条路速度会比较慢我一般是先批量转成图片再用多进程并行识别。PPT和Excel相对简单。PPT用python-pptx按“幻灯片 → 形状 → 文本框”的层级遍历注意合并同一页里的文本框不然一段内容会被拆得七零八落。Excel用openpyxl读取重点是表格转文本的方式——直接把单元格按行拼接成TSV格式可以让模型更容易理解行列关系。2.2 第二步清洗规则把Token用在刀刃上文本提取出来之后至少要过一遍清洗流程。我总结了一套通用规则按顺序执行删除页眉页脚。页眉页脚通常是页码、文档标题、公司名称的重复可以用正则匹配页码模式也可以用pdfplumber的坐标信息按区域裁剪。坐标裁剪更精准但不同文档的版式差异大规则要保守一些。剔除目录区。目录的特征是“标题文字 点线 页码”可以用正则匹配行尾的纯数字并且这些行集中出现在文档前几页时整体删掉。压缩连续空白。把连续的换行和空格统一替换为单换行避免表格解析后出现大量空行。清理特殊字符。全角空格、不间断空格、零宽字符这些不可见字符在解析时经常混入需要统一替换掉。保留表格结构。不要直接把表格拍平成无格式文本建议转成Markdown表格格式能够显著提升模型对行列关系的理解。清洗代码写起来不难关键是规则要克制。我见过有人用非常激进的规则清洗结果把正文里的“3.5 节”这种带点线的正常内容也误删了。建议清洗之后打印几页结果人工抽查确认误删率在可接受范围内。2.3 第三步按语义分块而不是按字数硬切分块是预处理里技术含量最高的一步。很多人图省事按固定字符数比如每500字符切一块直接切片这会导致同一个段落、同一个论点被拦腰切断模型处理每一块时都缺少上下文最终汇总时也会出现信息断层。我采用的分块策略是“标题感知 段落合并”。先用正则识别文档里的标题行通常满足“短行 无句号结尾 层级编号”这些特征把文档切成若干个语义块一个标题下若内容太长再按段落边界做二次切分。分块参数上我的经验值是目标块大小控制在800到1200 Token重叠区域150到200 Token。Token估算对中文大约1个汉字≈1到1.5 Token对英文1个单词≈1.3 Token。换算成字符数中文文本一块大约1500到2000字符。重叠区域的意义在于切块边界处若有跨块信息模型在下一块开始时还能看到上一块结尾的部分内容避免信息在边界处丢失。2.4 第四步文档太长时先做“目录摘要”再按需加载当文档拆出来的块数量超过20个时就算每块只有1000 Token全部塞进上下文也接近窗口上限了。这时候我的做法是“两级加载”第一级先让模型快速浏览每块的标题和首段生成一份全文概要第二级根据概要定位真正需要细读的块只把这些块送入模型做深度处理。这和人的阅读习惯很像——拿到一本书先翻目录找到关键章节再精读而不是从第一页一字不差地读到最后一页。实现上我会为长文档专门生成一个“分块索引表”包含块序号、标题、起始页、预估Token数、一句话摘要。后续所有任务调度都基于这个索引表进行模型可以根据问题精准定位需要读取的块大幅降低上下文压力。3. 任务调度排队、喂料、回收结果的关键设计预处理把文档变成了“块”接下来要设计一套调度机制决定这些块什么时候送进模型、送进去之后怎么管理上下文、处理完的结果怎么回收汇总。这部分做不好前面所有工作都会白费。3.1 为什么不建议所有块一次性并发提交我一开始图省事把拆好的块全部丢进线程池一次性并发提交给模型。结果很惨显存直接被打满推理进程卡死最后不得不杀进程重来。后来我才想明白本地模型和云端API不一样云端可以靠横向扩展扛并发本地单卡就只有那么多显存并发一高KV Cache会把显存瞬间吃干。本地环境更稳妥的方案是“单卡单任务”也就是同时只跑一个推理任务。如果你的显存足够大比如两张卡以上可以开两个并发但一定要给显存留出至少20%的余量防止碎片化导致OOM。我现在的默认配置是最大并发数设为显存容量的保守值宁可排队也不能并发过高。3.2 串行处理 上下文裁剪让上下文永远不膨胀串行处理时最容易犯的错误是上一个块的输出直接作为下一个块的输入导致上下文越滚越长处理到十几块之后又超限了。正确的做法是“裁剪式串行”——每一轮任务只保留三部分系统提示固定不变、全局摘要前几轮结果的压缩、当前块内容。上一轮的完整输出处理完后立即丢弃只把提炼出的摘要留下来。全局摘要是这套机制的核心。每一轮处理完当前块从模型输出里提取关键信息更新全局摘要。持续更新的摘要相当于对整个文档的“动态记忆”模型回答后续问题时虽然看不到全文但能通过摘要掌握前面已经看过的内容。这个方式可以保证上下文窗口占用始终稳定在“系统提示 摘要 当前块”这三个区段不会无限膨胀。3.3 用队列模型管理任务状态调度器的内部结构我用了经典的生产者-消费者模型。生产者负责从预处理模块接收分块结果拆成独立任务放进队列消费者从队列取任务调用本地模型执行处理完成后记录结果状态。每个任务至少要维护这几个状态pending等待处理、running正在推理、summarized已生成摘要、done全部完成、failed失败待重试。我用一张任务表来管理字段包括任务ID、文档ID、块序号、块内容路径、状态、重试次数、起始时间、结束时间、Token消耗。这张表既是调度器的运行依据也是后续排查问题的重要依据。实现层面任务量不大时没必要引入Celery这种重框架Python标准库的queue.Queue加concurrent.futures的ThreadPoolExecutor就够了。处理上万块的场景才需要考虑Redis队列和持久化我目前这个量级用标准库很稳。3.4 调度参数怎么调并发、超时、重试的推荐基准调度器的核心参数有三个并发度、单任务超时时间、失败重试次数。我给一组自己实测下来比较稳的基准值大家可以参考再根据自己机器的实际情况调整并发度24GB显存跑7B量化模型建议设为132GB显存可以尝试224GB跑小模型3B级别可以尝试2。单任务超时根据块的Token数动态计算按模型实际输出速度预留50%余量。比如模型每秒输出20个Token目标输出500 Token的任务超时设为40秒左右。失败重试默认重试2次重试之间退避等待10秒。连续失败3次的任务标记为failed移到错误队列不阻塞后续任务。还有一个小技巧调度器里记录每个任务的Token消耗。这个数据不仅方便统计成本还能在排查问题时发现“某个块为什么特别慢”——通常是因为块里含有大量模型难以处理的复杂表格或代码片段。4. 把预处理和调度串成一条产线全链路视角前面每一环单独拎出来都是基础功夫真正让它发挥价值的是把它们串成一条完整的产线。这部分我就讲讲全链路是怎么组织的以及每一层之间如何解耦、如何缓存、如何保证可追溯。4.1 一条清晰的数据流从原始文档到最终答案我的流水线按这个顺序跑文档入库 → 格式识别 → 文本提取 → 噪声清洗 → 语义分块 → 生成索引 → 任务队列 → 调度执行 → 结果汇总 → 输出落盘。每一层的输入输出都是“落盘数据”而不是内存对象。解析结果存成JSON分块结果存成JSONL任务状态存成SQLite表。这么做的好处是某一层挂了前面已经处理好的结果不会丢重启后可以直接从断点继续不用重新解析整份文档。数据形态上我统一用JSON传递。比如一个分块记录的JSON包含doc_id、chunk_id、chapter_path章节路径、content清洗后的文本、char_count字符数、token_estimateToken估算、source_page来源页码、parent_title所属标题。这套字段在后续做RAG检索、结果回溯时都很有用。4.2 模块解耦的关键每一层都做缓存重复解析是最大的时间浪费。同样一份Word文档如果只是改了问题的措辞没必要重新解析重跑全链路。所以我在每一层都加了缓存解析缓存以文档的MD5为键缓存提取出的原始文本。清洗缓存以原始文本的MD5为键缓存清洗后的纯净文本。分块缓存以清洗文本的MD5为键缓存分块结果和索引表。命中的层直接跳过后续操作整体耗时可以从几十分钟降到十几秒。这个优化在实际使用中体验提升非常明显尤其是反复调试提示词、调参数的时候不用每次都从头解析。4.3 从“处理完就扔”到“可追溯可复现”全链路还有一个常被忽视的要求——可追溯。我见过有人跑完一轮任务只拿到最终答案中间每块模型输出了什么、为什么最终答案是这么汇总的完全不透明。这种“黑盒式”处理在调试阶段会让人非常痛苦。所以我把每块的处理结果都原样落盘和任务记录关联起来。最终答案生成时也附带一份“溯源清单”标明哪些块参与了本次回答的汇总每块的摘要分别是什么。这样后续如果有输出质量问题的反馈可以快速定位是哪个块的信息被错误理解而不是对着一个最终结果瞎猜。5. 实战中踩过的坑与排查思路这部分是硬经验的集合。我把跑这套链路过程中遇到的典型问题、排查方法和最终解法整理成了一份速查表并补充几个容易被忽视的细节建议收藏备用。5.1 常见问题速查表问题现象根本原因解决办法解析出的PDF文本全是乱码扫描型PDF未走OCR直接提取了底层编码改用PaddleOCR做识别不要依赖pdfplumber分块后模型回答内容断裂按照固定字符数硬切切断了语义段落改用标题感知 段落边界合并的分块策略每块单独看都对汇总时前后矛盾丢弃了前块摘要模型缺少全局信息引入全局摘要机制随处理进度持续更新处理到一半显存溢出并发度设置过高KV Cache吃满显存改为单任务串行留出至少20%显存余量同一个信息在回答中反复出现分块重叠区域过大多处包含相同内容重叠区域控制在150 Token以内提示词里注明“忽略重复内容”文档几轮就超限但单块明明很小未做上下文裁剪历史输出不断累积改用“系统提示 全局摘要 当前块”三段式喂入任务跑到一半进程被杀全白跑没有中间结果落盘没有断点恢复每块结果及时落盘任务状态写SQLite支持重启续跑5.2 三个容易忽视但影响很大的细节第一个是换行符。Windows的文本文件经常带\r\n而Unix环境只认\n解析后混在一起会影响正则匹配的准确性。建议在清洗第一步就把\r\n统一替换为\n。第二个是表格的转换方式。把Excel或Word表格转成纯文本时如果直接拼接单元格模型很难理解行列关系。改成Markdown表格格式之后我实测模型对表格内容的回答准确率明显提升原因是Markdown保留了表头和行列分隔的显式标记。第三个是Token估算不能只看字符数。中文字符、英文单词、数字、代码片段的Token密度完全不同。我一个比较懒但实用的估算公式是字符数除以2再乘以1.2的安全系数。比如一块文本有3000字符预估Token约1800略有富余用于判断是否会超限足够用了。5.3 别忘了输出长度也是限制最后提一个很隐蔽的问题长文本处理不只有“输入超限”还有“输出超限”。当你让模型对一份长文档做全文总结时即使输入的每个块都控制好了模型生成的总结也可能超过max_tokens的设定值导致输出被截断。我的处理办法是“分段生成 合并摘要”。比如要求模型对十个章节分别生成200字以内的要点再把十个要点合并成最终摘要。这样单次生成长度可控不会触发输出截断同时最终摘要的信息密度反而更高——因为每个章节都经过独立提炼合并时不会遗漏重点。最后分享一点自己的经验整套链路跑通之后我最深的体会是在本地智能体落地这件事上预处理才是真正的门槛。模型能力再强喂进去的是解析糟糕、噪声成堆、切块随意的文本它也发挥不出来反过来把文档预处理和任务调度的基本功做扎实了很多所谓的“长文本难题”其实自己就消失了。我给团队定的流程很简单新文档进来先走解析和清洗看一眼清洗后的Token统计再决定是直接处理还是走“先摘要后细读”的两级加载。这套流程跑了几个月稳定性很高几乎没有再被上下文超限卡过。后续我准备再把分块结果接进本地向量库做一轮RAG增强让“先摘要后细读”升级成“先检索后阅读”进一步降低无效Token的消耗。等实测出效果再单独写一篇。