本地智能体跑业务文档的时候最烦人的不是模型本身能力不够而是长文本超限这道隐形天花板。合同、技术方案、尽调报告随便一拉就是几万字直接塞给大模型轻则截断丢信息重则直接报错白跑一趟。我最近在做的这个本地智能体项目就是围绕这个问题把整条链路打通文档预处理、任务调度、上下文管理、兜底策略一套走下来长文本不再靠“硬塞”而是靠“拆得对、调得顺”。这篇文章把我踩过的坑和验证过的方案都整理出来给正在做智能体落地的人做个参考。1. 项目概述这个全链路到底要解决什么问题1.1 长文本超限本地智能体绕不开的拦路虎大模型的上下文窗口是有限的哪怕是号称支持百万 token 的模型在实际本地部署场景里也会因为显存、推理速度、注意力机制开销等因素不可能真的把全部上下文都用满。我项目里用的本地模型是 32B 量级量化之后实际可用的上下文窗口在 8K 到 16K token 之间换算成中文大概是 6000 到 12000 字。一份稍微像样的尽职调查报告或者项目可行性研究文本轻松突破这个数字。更麻烦的是办公场景的文档不只是“长”的问题还有“脏”的问题。PDF 里混着扫描图片、表格错位、页眉页脚重复、超链接散落Word 文档里又是修订痕迹又是批注这些乱七八糟的东西如果直接进入模型上下文Token 消耗翻倍不说还容易干扰模型对重点信息的提取。我第一版测试时直接把一份 3 万字的招标文件全文塞给模型结果模型不仅漏掉了关键的技术参数表还因为页眉页脚重复出现把同一个信息当成了两次不同的条款来解读。所以这个项目的第一个出发点很清楚不要试图把长文本完整塞进上下文而是通过预处理把它变成结构化的、可检索的、按需加载的信息块。这是整个全链路里最基础也最关键的一环。1.2 全链路闭环的价值从原始文档到任务执行单独做一个文档切分脚本不难单独跑一个智能体工作流也不难难的是把它们串成一个可以稳定重复使用的链路。用户丢进来一批文档系统要自动完成解析、清洗、分块、向量化、索引构建然后根据任务类型自动调度智能体去执行对应的分析动作整个过程不需要人工干预也不需要在中间步骤手动搬运数据。我搭的这个链路大概分四层输入层接收 PDF、Word、TXT、Markdown 等格式的文档自动识别类型并归档。预处理层完成文本抽取、格式清洗、表格结构化、章节切分、向量化入库。调度层把不同任务分发给不同智能体子模块管理队列、并发和依赖关系。执行层业务智能体基于向量库检索结果进行分析输出结论文件。在实测中这套流程把一份包含 47 个文件、总字数约 38 万字的项目资料包处理完耗时约 6 分钟后续针对这包资料的各种问答和总结任务单个任务的响应时间控制在 15 秒以内。对比之前“全文塞入”的方案任务成功率从不到 60% 提升到 97%而且输出的信息完整性明显更好。2. 设计思路与方案选型2.1 为什么选本地部署而不是 API 调用可能有人会问长文本超限问题用商用大模型 API 不是更容易解决吗确实不少云端模型提供了更大的上下文窗口但我在这个项目里坚持全本地部署有几个现实考量。首先是数据敏感性。办公文档里经常包含合同条款、人事信息、财务数据这些内容不太适合送到外部 API 处理尤其在没有企业级私有化协议的情况下合规风险是实打实的。其次是成本结构。项目需要频繁处理长文档如果按 Token 计费一个月下来成本不是小数目本地部署用消费级显卡就能跑边际成本接近零。第三是稳定性。本地链路不依赖外部网络就算外网波动、API 限流任务照样能跑这对办公场景的“准实时”需求非常重要。当然本地部署也有代价最大的代价就是上下文窗口更小、算力更有限这恰恰倒逼你在文档预处理和调度策略上做得更精细。换句话说本地部署不是“用更便宜的方案做同样的事”而是“用更聪明的方案做更受限的事”两者对工程能力的要求不在一个量级。2.2 文档预处理的技术路线我对比过好几条路线最后敲定的组合是PyMuPDFfitz做 PDF 解析 python-docx 做 Word 解析 正则表达式体系做清洗 滑动窗口分块 向量化入库。PyMuPDF 选它的核心原因有两个。第一它对 PDF 文本层抽取的速度快单份 50 页的 PDF 解析耗时在 2 秒以内实测比 PDFPlumber 快了一个数量级。第二它提供了块级block和行级line的访问接口方便我按坐标信息重建表格结构。这里有个关键技巧PDF 里很多表格在文本层是“乱序”的因为视觉上同一行的内容在底层可能分布在不同的流对象里直接用文本模式抽取会把表格搞得支离破碎。我的做法是先把字符按坐标聚类再用“同一表格区域 同一行 y 坐标”的规则重组行内容再按列 x 坐标对齐实测对规整的财务表格准确率能到 95% 以上。Word 文档相对简单python-docx 可以逐段落读取还保留了标题层级这对接下来的章节切分太重要了。我在这里踩过一个坑Word 里的修订记录在 python-docx 的默认读取中不会出现在文本里但批注会混进来需要单独过滤 paragraph 的 comment 属性否则模型会把批注当成正文来解读。清洗环节是最烦人的。页眉页脚、页码、超链接、乱码字符、重复空白这些都要处理。我总结出一个原则宁可持续清洗过度也不能放过脏字符。因为脏字符进入向量化阶段后会污染语义向量导致检索阶段召回一堆不相关片段比多花几秒钟清洗时间更可怕。2.3 任务调度框架的选择任务调度层我最初考虑过用 Celery后来放弃了原因是针对“单机 多智能体 轻量任务队列”的场景Celery 重了部署还要额外起 Redis broker。最后我用的是Python 自带 asyncio 自定义优先级队列配合一个简单的状态机管理任务生命周期。为什么不用现成的工作流引擎比如 Airflow因为 Airflow 是为“周期性调度的大数据任务”设计的粒度太粗交互也不够灵活。我需要的是“用户提交任务后秒级响应、多个智能体按依赖关系并行处理、失败任务自动重试”这种轻量级编排能力用 asyncio 自己写一套成本不高而且完全可控。任务调度的核心规则有三条小任务优先检索类、问答类任务标为高优先级处理类任务标为低优先级避免耗时的文档处理阻塞用户实时交互。同类任务合并执行同一份文档的多个查询任务合并成一次上下文加载减少重复检索。失败隔离与重试单个子任务失败不影响整条链路重试次数上限 3 次超过则标记人工介入。这三条规则实测下来非常管用最直观的效果就是任务排队时间减少了 70% 以上。3. 核心环节实操拆解3.1 文档预处理解析、清洗与分块这一步是整个项目的地基我拆成四个子步骤来执行。首先说解析。PDF 和 Word 的解析参数我统一做了一个配置层不用每次在代码里硬编码。解析出来的内容统一封装成一个 DocumentChunk 对象包含字段正文内容、来源文件名、章节路径如“第三章/3.2 节”、页码、块序号。这个统一结构后面所有环节都用得到相当于给不同格式的文档做了一个“标准接口”。然后是清洗。这个环节我把规则分成三层。第一层是“硬规则”针对确定的垃圾内容比如页码正则^\d$且单独成行、页眉文档前 N 行或每页固定重复内容、网址、乱码字符常见 Unicode 控制字符直接删除。第二层是“半规则”针对可能有用也可能没用的内容比如表格编号、图表引用我选择保留但打上特殊标记让模型自己判断。第三层是“软规则”依赖模型判断的内容比如一段看起来像正文但实际是免责声明的话这部分不硬删靠后续检索时的相关性过滤。分块是整个预处理的核心。我用的是滑动窗口 标题感知的分块策略而不是简单的固定长度切分。标题感知的意思是先通过 Markdown 标题层级或者 Word 的 Heading 样式识别文档的章节结构以章节为天然边界。如果一个章节过长超过预设的块大小再在章节内部用滑动窗口切分。这样做的好处是用最小的代价保持了语义完整性避免把一个完整段落拦腰截断。参数上我试验了多组配置最终固定为块大小中文场景下 800 字符。重叠区150 字符。最小块大小50 字符。切分单位优先按段落换行符其次按句子句号、感叹号、问号最后按字符。重叠区的作用是保证跨块的信息不丢失。比如一份合同里“甲方应在收到通知后 30 日内完成支付”这句话如果恰好被切在两个块的边界上没有重叠区的情况下两个块都只能看到半个信息检索时召回哪个都不完整。加了 150 字符的重叠后边界处的关键句在相邻块里都完整出现实测关键信息召回率提升了约 18%。3.2 以向量库为中心的上下文管理文档分块完成后接下来就是向量化入库。我用的是ChromaDB选择它的原因很直接纯本地、零配置、Python 原生接口、支持持久化作为单机场景下的向量库完全够用。Embedding 模型用的也是本地版 bge-base-zh-v1.5这个模型对中文长文本的语义理解在同类模型里算表现稳定的。这里的核心设计是多集合隔离。不同项目、不同批次上传的文档我放到不同的 collection 里而不是全部塞进一个大库。原因很简单办公场景下用户的问题是跟着具体项目走的“帮我看一下 A 项目的合同风险”和“帮我看一下 B 项目的预算表”检索范围天然就应该限定在各自的项目集合里。集合隔离之后不仅检索速度更快还能避免跨项目信息串扰。入库之后还有个容易被忽略的环节索引的增量更新。用户上传新文档、覆盖旧文档都要触发对应集合的增量向量化而不是重建整个集合。ChromaDB 的upsert接口天然支持这一点只要保证 chunk 对象 ID 稳定就能做到分钟级的增量更新。检索策略上我用了“先召回后重排”的两阶段方案。第一阶段用向量相似度召回 Top 20 候选块第二阶段用 BM25 对候选块做关键词加权重排取 Top 8 作为最终上下文。为什么要重排因为纯粹靠向量相似度经常会召回“语义相关但实际不解决用户问题”的块加入关键词重排后能有效把包含精确术语或数字的块提到前面来。这一步提升的效果非常明显实测回答准确率提升约 21%。3.3 任务调度与智能体编排链路里的智能体不是一个大而全的东西而是拆分成多个专用子模块每个子模块负责一种能力这样调度起来更灵活。我把智能体拆分成四类智能体职责输入输出文档理解智能体对召回块做信息抽取、实体识别输入块列表输出结构化 JSON风险分析智能体识别合同/报告中的风险条款输入块列表 规则集输出风险清单汇总生成智能体生成摘要、对比结论输入上述智能体的输出输出报告问答智能体直接回答用户问题输入问题 相关块输出答案调度核心是一个AgentOrchestrator类它维护一个任务图每个节点是一个智能体任务边表示依赖关系。比如一个典型的任务流用户提问 → 预处理任务文档解析 分块 检索 → 文档理解智能体提取关键实体 → 风险分析智能体基于实体分析风险 → 汇总生成智能体产出结论报告并行度控制方面我设置了最多同时执行 3 个子任务超过的自动排队。这个数字不是随便定的而是根据本地显卡推理时延和显存占用测出来的最优值。模型推理是算力密集型同时跑太多任务会导致单任务时延急剧增加反而降低整体吞吐量。依赖失败的处理也在这里体现。比如风险分析智能体如果因为没检索到关键块而输出空结果我不会让链路继续跑下去而是触发一个反馈循环自动重新检索更广泛的候选块再执行一次分析。实测这种“按需回溯”机制能把误判率降低不少。3.4 处理长文本超限的三种兜底策略即使有了分块和检索实际使用中还是会有超限场景冒出来我开发了三种兜底策略。第一种是上下文压缩。当检索回来的块总长度超过模型上下文上限时先让一个轻量级的抽取式摘要模型对块做压缩保留每块的核心句子把总长度压到窗口内再喂给主模型。这个做法适合“多个块都相关但不需要完整细节”的场景比如总结性提问。第二种是分层灌入。把块按相关性分数排序先喂最高分的一组让模型生成初步答案如果模型判断信息不足再补喂下一组。这本质上是一种“多轮分段处理”我用一个context_budget参数控制在每轮能消耗的 Token 数避免后一轮把前一轮的上下文挤爆。第三种是聚焦改写。当用户的问题非常明确时不直接喂原始块而是先让一个抽取智能体把块里的关键数据点、条款编号、金额等信息提取成结构化表单再以“结构化数据 极少量原文”的形式喂给主模型。这样 Token 消耗能压缩到原来的 30% 以下适合风险识别、条款核对这类高精度任务。这三种策略我分别测过效果兜底策略适用场景Token 节省率信息完整度上下文压缩总结类任务50%-70%85% 左右分层灌入多轮问答动态控制最高聚焦改写条款核对、数据提取70%95%实测下来大部分任务在“分块 检索”阶段就能解决真正需要走到兜底策略的场景占比不到 15%但这 15% 如果没有对策几乎用户每次都会碰到超限报错所以这块必须做好。4. 常见问题与排查实录4.1 分块参数怎么调才合理分块大小和重叠区这两个参数是决定后续检索效果的头号因素。我一开始按英文技术文档的习惯设置了 1200 字符块大小、200 字符重叠结果在中文办公文档上效果很差召回的块经常是一半有用一半没用。原因在于中英文信息密度的差异。英文一个 token 约等于 4 个字符1200 字符大概是 300 token中文一个 token 约等于 1.5 到 2 个字符1200 字可能只有 600 到 800 token。表面上块字符数一样实际语义载荷完全不同。我后来改成**中文按“目标 Token 数反推字符数”**来设置目标是每块 400 到 500 token换算成字符就是 800 字左右效果明显好了不少。重叠区的经验值是块大小的 15% 到 20%。太小了边界信息保不住太大了冗余信息增加、检索噪声变大150 字符在 800 字符的块上正好是 18.75%算是比较合适的区间。还要注意一个细节分块不能简单按固定字符数硬切。碰到代码块、JSON 片段、表格这类特殊内容要单独设置规则。比如表格我倾向于整表保留不切分哪怕表格超过块大小也宁可让它作为单独的大块存在因为切碎后的表格在语义上是完全不可用的。4.2 调度任务互相“打架”怎么办任务并发的场景下最容易出现的问题是共享资源竞争。我这里最典型的是显卡推理资源竞争两个智能体同时向模型服务发起推理请求显存占用瞬间飙升导致其中一个任务超时甚至 OOM。排查过程让我意识到单纯限制并发数不够还需要引入推理请求合并。具体做法是把短小的生成任务打包成 batch 请求一次发给模型服务而不是一个个串行调用。用 vLLM 作为推理服务端时它的 continuous batching 机制天然适合这种场景吞吐量能提升 2 到 3 倍。另一个问题是任务状态丢失。程序崩溃或手动中断后任务队列里的状态还停在“执行中”重启后这些任务就变成了僵尸任务。我的解决办法是在任务状态机里增加“心跳时间戳”每次状态更新都刷新时间戳启动时扫描超过 2 分钟没有心跳且状态为“执行中”的任务自动回滚为“待重试”。这个机制救了我好几次。还有一个小坑日志刷屏导致性能下降。前期每个子任务都打详细信息日志高并发时日志 I/O 反而成了瓶颈。后来加了分级日志默认只打任务级摘要DEBUG 级别才输出详细内容问题立刻缓解。4.3 本地资源占用飙升排查本地智能体跑着跑着内存和显存占用一路走高最后卡死这个现象我排查了很久。最终定位到三个核心原因。第一个是向量库查询结果对象没有及时释放。ChromaDB 查询返回的结果对象在 Python 里如果被全局变量引用会一直占着内存。我加了一层封装确保每次查询的结果在函数返回后立即进入垃圾回收。第二个是大模型推理的显存碎片化。连续推理不同长度的序列显存碎片会越来越严重。对策是开启 vLLM 的后端分页注意力PagedAttention它能把显存利用率提升不少碎片问题也减轻了很多。另外我固定了推理的 max_tokens 上限避免个别任务贪心地申请大段显存。第三个原因是文档解析阶段的对象堆积。PyMuPDF 打开一份大 PDF 后Document 对象占用的内存可能达到文件体积的数十倍如果连续解析多份大文件而不主动 close内存会被快速吃光。对策是增加显式的资源回收逻辑解析完一份立即关闭并调用 gc.collect()。我还建议加一套简单的资源监控定时记录 CPU、内存、显存使用率跑上几天就能发现规律也能及时预警。我用的是psutil加pynvml代码量不大效果却很直观。5. 实测效果与个人心得链路稳定跑起来之后我用一份真实项目资料做了压力测试。语料是一份包含 47 个文件、总字数约 38 万字的技术招标资料包包含 20 份 PDF、15 份 Word 文档、12 份 Excel 导出的 CSV 表格。测试分成三类任务单文档问答30 个问题、跨文档对比10 个问题、长文本总结5 个任务。结果汇总如下单文档问答成功 29/30平均响应 6.8 秒。跨文档对比成功 10/10平均响应 11.2 秒。长文本总结成功 5/5平均响应 18.5 秒。全程无长文本超限报错。数字看起来不错但我想说几个更实际的观察。本地智能体的性能瓶颈通常不在模型本身而在工程链路。很多人一开始就把目光盯在模型要换多大参数上实际上把文档预处理做扎实、把检索做精准、把调度做合理带来的提升比换一个更大参数模型更明显、成本更低。在我这个项目里模型从 7B 升级到 32B对最终任务质量的提升远不如“分块参数调优 两阶段检索”带来的提升大。关于长文本问题我现在的理解是“长文本超限”并不是一个需要消灭的问题而是一个需要管理的约束。就像人读书也不会把整本书背下来再回答问题而是先看目录、再翻重点章节、按需精读。智能体也应该走同样的路线预处理做的是“编目录”向量库做的是“翻书”调度做的是“安排阅读顺序”。想通这一点之后很多设计决策都变得顺理成章。最后分享一个技巧给每个智能体任务加上“空结果兜底规则”。当检索不到相关内容时不要让模型硬编一个答案强制它输出“未检索到相关信息可能是知识库覆盖不足”同时触达补充知识库的提示。这个规则避免了很多幻觉问题也推动了知识库的持续完善。这个项目后续还有很多可以扩展的地方比如加入增量学习机制、支持实时文档流式接入、增加多模态文档解析能力扫描件 OCR、图表解读。不过骨架已经搭好了后面都是往上加功能的事基础链路稳扩展就不慌。