AI Agent 读 PDF:读完前几页,不等于看懂全文

AI Agent 读取百页 PDF 时,可能把只读前几页当成读懂全文。这篇拆解感知工具设计:先用清单定位内容,再按 offset/limit 分段读取,并明确标注覆盖范围与内容缺口;同时比较图片处理路径,帮助读者设计可续读、可降级的文档工具。

文章目录

原文:AI Agent 工具设计:读完一百页 PDF,不等于真的看懂了

AI Agent 处理长文档时,最危险的误导不是明确报错,而是“看起来读过”。面对百页 PDF,感知工具如果只读前几页就给出答案,系统会把局部信息包装成完整结论。现在值得看这类工具设计,因为答案是否可靠,不只取决于模型能力,还取决于工具能否交代文档范围、读取进度和内容缺口。

这套方法可以直接搬进 Agent 工具层:先给清单建立文档地图,再按 offset/limit 分段读取正文;每次返回都标明已读范围和未读部分,避免把片段当成全文。图片则按任务选择直接理解、识别文字或分区查看的路径。拿走的不是某个 PDF 插件,而是一套让证据边界可见的接口设计。

1、先把“读过”拆成可验证状态

1、先把“读过”拆成可验证状态(AI 生成示意图)

1、先把“读过”拆成可验证状态 · AI 生成示意图

工具的成功状态至少应区分:已发现文档、读取部分内容、覆盖全部可读内容,以及读取失败。只返回一个长文本,再附一句“完成”,会让 Agent 很难判断证据是否充分。程序跑完了,不代表问题涉及的页面都看到了。

更稳的做法,是把内容与覆盖状态一起返回。Agent 先知道拿到了什么,再决定直接回答、继续读取,还是明确提示信息不足。工具不能把“调用成功”冒充“内容完整”。

工具返回状态 实际含义 Agent 的回答边界
已发现文档 知道文档存在 尚不能引用正文
已读取片段 取得部分页面 只能基于片段回答,并说明范围
已覆盖全文 可读页面均已纳入 才能讨论全文层面的结论
读取失败 某些内容无法取得 明确指出失败,不用猜测补齐

2、清单先行:先定位,再读取

2、清单先行:先定位,再读取(AI 生成示意图)

2、清单先行:先定位,再读取 · AI 生成示意图

清单的价值是建立地图,不是替 Agent 读完。清单先告诉它文档有哪些可读页或章节,以及内容应从哪些范围继续取。Agent 据此缩小目标,再请求正文,比一上来吞下整份文件更可控。

这里的关键不是多一次调用,而是把“发现内容”和“理解内容”拆开。前者用于定位,后者才用于回答;任何一步没完成,都不该在结果里伪装成全文结论。先清单再正文,本质上是在给 Agent 留出查证路径。

3、offset/limit:分段读取,并标出缺口

offset/limit 的价值,是把长文档变成可续读的数据流。offset 表示从哪个位置开始,limit 表示本次最多取多少内容,具体单位可以按页或按工具约定。工具返回片段时,同时给出请求范围、实际返回量、下一位置,以及是否仍有后续内容。这样 Agent 才知道眼前文字是起点、中段还是结尾。

缺口也要写进结果。若从非零 offset 开始,就应说明前段内容未包含在本次返回中;若尚未读到末尾,就应标记仍有未读内容。提示不需要复杂,一句“当前结果仅覆盖部分内容”,比沉默地继续生成更可靠。

缺口不是异常,而是工具状态的一部分。

下面的 Python 示例以页为单位,接收按页组织的 JSON 数组,每个元素保存一页抽取结果。offset 在示例中采用从零开始的下标;工具只负责读取契约,不替代 PDF 解析:

import argparse
import json
from pathlib import Path

parser = argparse.ArgumentParser(description='按页读取 PDF 抽取结果,并返回覆盖状态')
parser.add_argument('--input', required=True, help='页列表 JSON 文件')
parser.add_argument('--offset', type=int, required=True, help='起始页下标')
parser.add_argument('--limit', type=int, required=True, help='本次读取的页数')
args = parser.parse_args()

if args.offset < 0 or args.limit <= 0:
    raise SystemExit('offset 不能为负数,limit 必须大于零')

pages = json.loads(Path(args.input).read_text(encoding='utf-8'))
if not isinstance(pages, list):
    raise SystemExit('输入必须是页列表 JSON')

selected = pages[args.offset:args.offset + args.limit]
next_offset = args.offset + len(selected)
has_more = next_offset < len(pages)

result = {
    'offset': args.offset,
    'limit': args.limit,
    'returned_pages': len(selected),
    'index_range': [args.offset, next_offset - 1] if selected else None,
    'prefix_included': args.offset == 0,
    'next_offset': next_offset if has_more else None,
    'has_more': has_more,
    'coverage_note': (
        '仅覆盖当前片段,不能据此断言已读全文'
        if args.offset > 0 or has_more
        else '已覆盖全部可读页'
    ),
    'pages': selected,
}

print(json.dumps(result, ensure_ascii=False, indent=2))

4、图片处理:路径不同,回报也要不同

图片不能只有一条默认路径。以文字为主的内容通常可先识别成文本,再做检索与归纳;图表和示意图通常更适合保留视觉结构直接理解;复杂大图则可以分区查看,避免细节在一次观察中丢失。

选择路径时,Agent 应根据图片内容和工具实际能力决定,并在结果里说明采用了哪条路径。若某条路径不可用,就应降级或请求进一步处理,而不是声称已经看懂。具体支持情况以原文和实际工具为准。

图片情况 通常优先路径 工具应回报
以文字为主 先识别文字,再分析文本 标出识别后的覆盖范围
图表、示意图 直接进行视觉理解 说明已查看对应图片
版面复杂的大图 分区后逐块查看 说明各区域是否都已处理

图片路径可以不同,但“实际看了什么”必须说清楚。

写在最后

百页 PDF 的难点,不是处理了多少页文字,而是证明哪些内容真的被看过。
清单负责定位,分段负责覆盖,缺口标注负责诚实,图片路径负责把非文字证据读对。
结论:Agent 的可靠性,始于工具对“读到了什么”的清楚表达。
我的判断是:评价文档 Agent,不能只看答案,还要看它能否暴露覆盖范围与证据缺口。

相关阅读

想把这套流程装到自己服务器上?阿凡达提供一次性的私有化部署与出海模型接入服务,说明与报价见站内服务页:查看技术服务。

文中链接

整理自本文的外部链接,请以来源页面说明为准。

AI Agent 读 PDF:读完前几页,不等于看懂全文 · 阿凡达博客