跳转至

Context不是免费的：长文档Agent性能天花板与架构优化

Ch04.174 Context不是免费的：长文档Agent性能天花板与架构优化

📊 Level ⭐⭐ | 11.9KB | entities/context-not-free-long-document-agent-architecture-raunak.md

-> Context不是免费的：长文档Agent性能天花板与架构优化

核心命题

构建文档密集型 Agent 时，原始解析 JSON（坐标、置信度分数、边界框）塞满上下文窗口导致 Agent 无法工作。解决方案：将 Content（Markdown 编号块）和 Metadata（CSV/JSON 结构化文件）分离，让 Agent 用代码按需查询元数据，而非全部塞进上下文。

核心问题：原始 API 响应并非为智能体输入而设计

问题现象： - 100 页变更单解析后产生 20 万行 JSON - JSON 包含大量：边界框坐标、OCR 置信度浮点数、块类型分类、坐标数据 - 智能体在密集边界框数组中艰难推理合同条款 - 上下文窗口在 Agent 开始干正事之前就已经耗尽

根因：解析 API 是为工程灵活性设计的，不是为智能体上下文设计的。我们为工程师结构化 JSON，而不是为了让智能体直接消耗。

解决方案：Content/Metadata 分离架构

三步后处理（约 20 行代码）

  1. 从 API 响应提取内容（.result.chunks[i].content）写入 .md 文件
  2. 丢弃坐标、置信度分数和块元数据
  3. 在 Markdown 中为每个块编号（用于后续引用）

编号块格式

块 0 | 第一节：一般条款
块 1 | 承包商应提供所有人工、材料和设备...
块 2 | 附件 B 中规定的单价应作为所有定价的依据...
块 3 | 1.1 工作范围
块 4 | 本变更单涵盖的工作包括对...的修改

按需查询架构

  • 完整解析 JSON（或 CSV）存放在智能体沙盒文件系统中
  • Agent 阅读 Markdown 内容进行推理
  • 当发现值得引用的内容（如第 47 块单价不一致）时，编写 pandas 代码从结构化文件提取边界框
  • 元数据永远不占用上下文窗口，只在需要时通过代码按需获取

完整流水线

文档上传 → Reducto 解析 API（获取全保真 JSON）→ 预处理（约 20 行代码）
                                                  ├→ 提取块内容 → 带有编号的 .md 文件
                                                  └→ 存储元数据 → 沙盒中的 CSV/JSON 文件
                                                                    （可选）生成章节索引
智能体沙盒：
  .md 文件 → 智能体阅读并推理
  元数据文件 → 智能体在需要时通过代码查询
  工具：搜索、grep、代码执行、带有引用的单元格写入
智能体引用第 47 块 → 编写 pandas 片段 → 提取边界框
应用层在原始 PDF 中渲染高亮引用

Prompt Pattern 修正

有害模式：

"从头到尾阅读每个附件文档。"

模型非常擅长执行指令，哪怕指令本身并不合理。对于 100 页变更单，上下文预算在做任何有用工作之前就已耗尽。

正确模式：

"利用附件文档回答问题。使用子智能体或工具来有效管理上下文。如果文件很大，请搜索相关章节，而不是加载整个文档。"

区别：第一种像死记硬背教科书的学生；第二种像研究员——搜索（grep）相关章节、阅读特定片段、利用工具提取特定数据。它是在引导（navigate）文档，而不是试图背诵文档。

核心原则

"上下文不是免费的。每一个 token 都会影响模型的行为，而那些对任务无用的 token 会积极地挤占掉那些有用的 token。"

一个包含 90% 坐标元数据的 100 万 token 上下文，效果不如一个拥有干净 Markdown 和优秀工具的 20 万 token 上下文。

其他可行方法（对比）

  • 向量搜索分块（Chunking with vector search）
  • 层级化摘要（Hierarchical summarization）
  • 微调检索（Fine-tuned retrieval）

本文方法的独特价值：适用于 Agent 需要跨文档进行详细交叉引用并产生精确引用的用例，且不丢失 PDF 像素级引用能力。

深度分析

1. 解析 API 与智能体输入之间存在根本性的设计目标错位

原始解析 API（Reducto）返回的 JSON 包含了工程所需的全部信息：边界框坐标、OCR 置信度浮点数、块类型分类、坐标数据等。这种结构对开发者构建文档阅读器或版面分析工具非常有用，但这些元数据对智能体的推理任务毫无价值。 这揭示了一个普遍现象：大多数结构化 API 响应的设计目标是工程灵活性，而非智能体可消费性。Raunak 明确指出这一点——"我们为工程师结构化 JSON，而不是为了让智能体直接消耗"。这意味着在实际工程中，任何向智能体传递外部系统输出的场景，都需要经过类似的"消费层适配"转换。

2. 按需查询架构将智能体从不必要的 token 消耗中解放出来

Content/Metadata 分离的核心洞察是：智能体对待结构化元数据应该像开发者一样——将其视为待查询的数据，而不是待阅读的文本。 在沙盒文件系统中，智能体通过编写简单的 pandas 代码从结构化文件中提取所需的边界框，而不是将整个 JSON 塞进上下文。这种架构将原本 20 万 token 的 JSON 转化为：一个用于理解的干净 Markdown 文件（20 万 token 量级显著压缩）和一个用于空间查询的结构化文件（元数据按需获取，不进入上下文窗口）。这直接验证了"上下文不是免费的"这一核心原则——对任务无用的 token 不仅浪费资源，还会积极挤占有用 token 的位置。

3. Prompt Pattern 的修正比模型能力更重要

文中揭示的有害模式"从头到尾阅读每个附件文档"是一个极其常见的 Agent 设计错误。模型的行为遵循指令而非判断指令的合理性——当被要求阅读整个文档时，模型会忠实地尝试将所有内容加载到上下文窗口中，无论文档有多长。 正确的模式则明确指导 Agent 使用子智能体或工具来有效管理上下文，搜索相关章节而不是加载整个文档。这不是说模型不够聪明，而是指令设计需要反映对计算资源约束的认知。对于构建长上下文 LLM Agent 的团队，这个 Prompt Pattern 修正是最容易实施且效果最显著的优化之一。

4. 20 行代码实现的性能跃升具有极高的工程推广价值

从 20 万行 JSON 到干净 Markdown + 按需元数据查询，这个转换的实现成本约 20 行代码。 这个极低的实现成本与极其显著的性能提升形成了强烈对比。对于任何处理文档密集型任务的 Agent 团队，这个预处理步骤都应该成为标准流水线的一部分，而不需要复杂的向量搜索、层级化摘要或微调检索。这种"消费层适配"的思路可以推广到任何向 Agent 传递外部系统输出的场景——关键问题不是模型不够强大，而是输入格式不对。

5. 精确引用能力与 token 效率并非不可调和的矛盾

传统的 RAG 分块方法（向量搜索分块）虽然能压缩上下文，但往往丢失了精确引用能力——无法将 Agent 的输出链接回原始 PDF 的特定区域。 本文的方案通过在 Markdown 中为每个块编号，在沙盒文件系统中保留完整的解析 JSON，实现了鱼与熊掌的兼得：干净的 Markdown 保证高效的推理上下文，元数据文件在需要时通过代码查询提供像素级引用。应用层最终在原始 PDF 中渲染高亮引用，满足建筑项目经理对"每一项发现都需要链接回原始 PDF 的精确区域"的严苛需求。

实践启示

1. 在向 Agent 传递任何外部系统输出之前，执行"消费层适配"转换

解析 API、数据库查询结果、第三方服务响应——这些输出的设计目标都不是直接给 Agent 消费。在进入 Agent 上下文之前，应该先问：Agent 实际需要什么信息？这个转换的成本通常很低（20 行代码级别），但对 Agent 性能的影响是数量级的。建议为每个外部数据源建立类似的预处理流水线，将工程友好的格式转换为 Agent 友好的格式。

2. 为文档块建立编号系统，保留精确引用能力而不污染上下文

在 Markdown 中为每个解析块编号，同时将完整元数据存入沙盒文件系统。这是实现"干净上下文 + 精确引用"双重目标的关键设计。当 Agent 需要引用特定内容时，通过编号在元数据文件中查询边界框，而不是将坐标数据全部塞进上下文。这个模式适用于任何需要跨文档详细交叉引用的场景，如法律合同审查、财务报表审计、技术文档比对等。

3. Prompt 设计应明确指导 Agent 使用工具管理上下文，而非全量加载

"从头到尾阅读每个文档"这类指令在模型看来是字面意思，模型会忠实地尝试全量加载。在涉及长文档的 Agent 系统中，Prompt 应该明确包含：使用搜索工具定位相关内容、使用代码执行提取特定数据、通过子智能体分工处理不同文档片段。[导航（navigate）而非背诵（memorize）] 应该成为所有长文档 Agent Prompt 的核心原则。

4. 评估 Agent 性能时，先审查上下文中的 token 分布质量

在优化模型能力、Prompt 调优之前，先检查 Agent 的输入上下文中有多少 token 是对当前任务真正有用的信息。一个包含 90% 坐标元数据的上下文，其实际有效信息密度可能极低。使用"干净 Markdown + 按需元数据"架构后，有效信息密度可以大幅提升，这往往比升级模型或优化 Prompt 的投入产出比更高。

5. 智能体沙盒是文档密集型任务的标准基础设施

沙盒环境使 Agent 能够安全地读写文件系统、执行代码（pandas 查询）、使用搜索和 grep 工具。 这些能力组合起来，构成了文档密集型 Agent 的标准工作环境：文件系统存储 Markdown 内容供 Agent 阅读，代码执行能力允许按需查询元数据，带引用的单元格写入支持将发现写入结构化输出。对于构建企业级文档智能体的团队，沙盒化编码 Agent 架构应该是首选方案。

关联阅读