为Claude智能体构建更快、更便宜的PDF解析技能：LiteParse案例研究

在这篇博客文章中，我们详细记录了如何通过评估、追踪分析和迭代改进，将LiteParse文档解析技能优化为更便宜、更快且质量更高的助手。

设置

我们使用pdfQA-Benchmark ClimateFinanceBench数据集，下载了30份企业可持续发展/ESG报告PDF及其标注的问答对，然后通过Claude Agent SDK在15个（PDF，问题）对上运行Claude智能体。每个运行产生结构化JSON答案和完整的JSONL交互追踪。智能体可访问标准工具，并根据评估配置有条件地调用技能。

我们比较了多种配置：原始（raw）直接使用Claude内置读取工具；liteparse初次包装；liteparse-targeted更直接的变体；以及effective-liteparse——基于评估追踪优化的版本。本文重点介绍最后一个版本的形成过程。

为何需要技能？

LiteParse可作为命令行工具或Rust、Python、JavaScript/TypeScript库使用。由于文档解析本质上是I/O密集型的，需要直接访问文件，而MCP服务器不支持文件上传，因此技能是最实用的集成模式。通过将使用说明打包成markdown文件注入智能体上下文，智能体可将LiteParse CLI作为Claude内置PDF阅读器的替代品。此外，CLI便于与grep、sed等Unix工具组合，实现过滤、搜索和转换。

发现反模式

前两轮评估后，我们收集了延迟、轮次、成本等指标，并分析了JSONL追踪，发现了一系列常见且昂贵的错误：

• 反复解析同一PDF——最差情况下，一个文档被解析了9次。
• 对数字原生PDF启用OCR，纯粹浪费时间。
• 将高分辨率页面截图读入上下文，单个PNG消耗约14万字符。
• 无限制的grep，一次性注入1.5万–2.5万字符。

优化：effective-liteparse技能

我们创建了effective-liteparse技能，将修复编码为硬规则：解析一次并保存到临时文件，然后搜索该文件；对数字原生PDF禁用OCR（--no-ocr）；截图仅作为最后手段，一页，适度DPI；保持结果精简。

此外，我们注意到智能体经常使用grep、sed和Read进行多次紧密迭代以找到正确上下文。因此，我们扩展了技能，包含一个自包含的Python脚本，用于并发读取、分块、索引并基于BM25进行检索，并指示智能体在模糊关键词搜索时使用此脚本，默认对模式/子串搜索使用词法搜索。

减少轮次

修复后，新问题浮现：effective-liteparse虽便宜但更慢，原因是轮次过多。最常用的工具是grep和sed，形成串行循环：grep→查看→改进grep→sed读取窗口→再次grep，每次调用都是完整API往返。我们之前的规则“先定位，再用sed读取窗口”使每个查找分裂成两轮，“不进行散弹式搜索”则促使模型进行许多细小的串行grep。

我们修改了指导原则，以减少往返：

• 在同一命令中获取上下文——grep -n -i -C4 "term"一次返回匹配及其上下文，无需后续sed。
• 将独立查找批处理到一个命令中——带标签的for循环一次性探查多个事实。
• 硬搜索预算——最多3次grep，之后回退到BM25排序器。

追踪确认了新行为：批处理模式出现，平均轮次下降约15%（从13.1降至11.1）。

数据结果

我们使用LLM评判员（Gemini和GPT）评分，并分析效率指标。在15个问题的子集上：

质量（LLM评分，越高越好）：

| 指标 | 原始 | effective-liteparse | |------|------|--------------------| | 总体答案 | 46.47 | 56.67 | | 总体推理 | 58.47 | 65.90 | | Gemini答案 | 58.53 | 78.33 | | Gemini推理 | 71.33 | 86.00 | | GPT答案 | 34.40 | 35.00 | | GPT推理 | 45.60 | 45.80 |

效率（追踪指标）：

| 指标 | 原始 | effective-liteparse | |------|------|--------------------| | 平均每个问题成本 | $0.751 | $0.474（-37%） | | p95成本 | $1.323 | $0.746 | | 平均轮次 | 8.47 | 11.08 | | 平均每轮时长 | 6.5秒 | 5.6秒（-14%） |

令牌使用：

| 指标（每次运行平均） | 原始 | effective-liteparse | |----------------------|------|--------------------| | 基础输入令牌 | 23 | 17 | | 缓存写入（5分钟）令牌 | 86,666 | 29,623 | | 缓存读取令牌 | 214,924 | 354,330 | | 输出令牌 | 2,433 | 3,546 | | 总输入令牌 | 301,612 | 383,970 | | 成本 - 缓存写入（5分钟） | $0.542 | $0.185 | | 成本 - 缓存读取 | $0.107 | $0.177 | | 成本 - 输出 | $0.061 | $0.089 | | 平均成本（报告） | $0.751 | $0.452 |

LiteParse技能每个问题便宜37%，所有评判指标得分更高。虽然整个任务仍慢几秒，但每轮时长更快，允许更多迭代。

关于令牌使用的说明

乍看之下，effective-liteparse变体处理了更多输入令牌（约384k对约302k），但这是因为大部分是便宜的缓存读取（$0.50/百万令牌），而昂贵的缓存写入（$6.25/百万令牌）比基线低了约3倍（29.6k对86.7k）。原始方法每次读取都会重新缓存大型PDF图像页面，而LiteParse本地解析并返回紧凑文本，因此缓存写入成本大幅下降。净效果是成本降低约40%。

成本基于发布的Claude Opus 4.7费率。报告成本是运行时的total_cost_usd；与逐类别汇总的小差距来自一个次要的Haiku调用。

经验教训

• 追踪是真理。所有改进都来自阅读智能体实际行为。
• 技能指导有次生效应。“先定位再读取”和“不散弹搜索”听起来合理，但增加了轮次。应优化总轮次而非每个命令的整洁性。
• 将框架与技能分离。最大的成本数字是框架人工产物，而非技能属性。在归因前仔细测量。
• 在这里，更便宜和更好不是取舍。有纪律的本地解析在成本和答案质量上都优于原始PDF摄取。

完整基准测试可在 https://github.com/run-llama/benchmark-claude-pdfs 获得和复现。