自己做LLM模型测评这一年多，长上下文领域的评估一直是最让我头疼的环节之一。市面上已有的基准测试，要么长度不够，要么“水分”太大，测出来的分数和真实使用体验完全是两回事。直到后来用上了paperclip，我才觉得长上下文评测这件事终于有了能打的工具。
paperclip是OpenAI开源的一套评估套件，核心思路非常“反常规”：不靠人工编造所谓的高难度问题去刁难模型，而是直接生成大量内容复杂、信息密度极高的PDF文档，让模型在真实的长文本里去做检索、推理、跨页关联。换句话说，它不去测一个“聪明但文本很短”的问题，而是把任务设计成“在几百页的复杂文档里把事办明白”。这篇文章我会把它背后的设计思路、完整跑通的实操过程、以及我个人踩过的一些坑全部梳理一遍，希望能帮最近在研究长上下文评估的朋友省点时间。
1. 内容整体设计与思路拆解
1.1 长上下文评估为什么难做
先聊一个基础问题：为什么RULER、NIAH（大海捞针）这类基准测完，大家还是觉得不放心？
关键在于两个点。
第一，文本复杂度太低。大海捞针类测试生成的文档本质上是重复的填充语句，模型在阅读时不需要真正理解内容，只需要在信息密度几乎为零的文本流里“感知到一个异常点”。这测的是注意力机制对异类的敏感度，不是真正的长程理解能力。真实场景里谁会去读几百页重复废话？
第二，检索粒度太粗。绝大多数基准的题目设计是“找出X”，答案就是一个实体、一个数字、一句话。但真实的长上下文使用场景呢？读一份财报，要对比不同年度的数据并推算趋势；看一份合同，要找出两个条款之间的隐含冲突；审阅论文，要判断实验方法和结论之间的逻辑关系。这些任务要求模型在多个位置之间建立联系，而现有基准很少覆盖。
这就解释了为什么有些模型在大海捞针测试里能拿满分，但真让它处理一份60页的行业研究报告就彻底胡言乱语。评估任务和真实使用场景之间出现了系统性偏差，长上下文评估失去了应有的说服力。
1.2 Paperclip的特立独行之处
paperclip的做法是从根上换了一个思路，它不再试图“造一个更难的针”，而是把整个“草垛”变成有价值的信息体。
具体说，paperclip用GPT-4o这样的顶级模型自动生成内容复杂、篇幅长达几十甚至上百页的PDF文档。这些文档包括审计报告、项目提案、艺术品目录、学术综述等等，每一页都有真实的排版、图表、脚注、交叉引用。然后基于这些文档出测试题，要求被测模型完成信息定位、跨页比对、深层推理等任务。
这样一来，评估材料就不再是人工设计的花架子，而是模型自身都难以生成的密集信息体。由于生成文档时使用的是不同的模型能力，被测模型无法通过记忆或模式匹配“猜”出答案，必须老老实实读文档找信息。
一句话总结paperclip的核心思想：用模型的复杂度去对抗模型的复杂度。生成端的高复杂度保证测试材料的信息密度，测评分的高复杂度保证测试任务无法靠捷径解决。
2. 核心机制与关键设计解读
2.1 什么是“半结构化文档”
要说清楚paperclip的机制，必须先理解“半结构化文档”这个概念。
你可以把纯文本想象成一张白纸上写满了字，没有任何层级逻辑；把数据库想象成带表格和字段的Excel；而半结构化文档，就是一份真实世界里常见的PDF：它有章节、有标题、有表格、有附录、有页眉页脚，逻辑上有一个整体的叙事框架，但信息不是均匀分布的。
paperclip生成的每份文档，内部信息按语义结构分布：同一个主题的相关内容聚集成章节，章节之间通过引用关系相互关联，表格里放结构化数据，正文里放解释性描述，脚注里放补充信息。这意味着，模型要回答问题，不能只做“扫描关键词”这种表面功夫，它必须理解文档的整体结构，知道去哪儿找什么。
审计报告就是一个典型例子。报告主体可能20页，但关键的财务明细都在附录里，正文通过脚注引用将两者关联。要回答“该机构过去五年在基础设施上的总投入”，必须定位附录里的两张表格，还要考虑汇率的调整说明——这些信息分散在多个位置，只有读完、梳理完才能作答。
2.2 两种测试方式的差异化设计
paperclip在生成评估样本时，设计了两种不同的测试提示方式，分别针对模型的两类使用形态。
第一种是把整个PDF进行解析后，作为文本直接嵌入到系统提示词中，让模型在“一级上下文”范围内自主检索信息。这种测试方式对应的是开发者将文档内容全部塞进上下文窗口的场景，考验模型在超大上下文里综合信息的能力。
第二种则是将PDF作为用户输入和问题一起传给模型，模拟的是终端用户“上传一份文档然后提问”的操作方式。这两种方式虽然只差了一个格式位置，但实际难度差异不小，因为第二种方式下模型需要先理解整份文档的结构，再定位目标信息，处理链路上多了一个环节。
更细节的是，文档在解析过程中要经过版面分析、阅读顺序重建、表格结构化等步骤，每一步都可能引入噪声。模型必须在这些不完美的输入条件下仍然表现稳定，才算通过了长上下文能力的实用性验证。
2.3 为什么选择“生成”而不是“聚合”
可能有朋友会问：为什么不直接拿真实的公开报告来做测试材料？
这个问题的答案涉及版权、成本、标准化的平衡。真实报告确实信息密度高，但一份真实的审计报告可能包含复杂的商业数据，涉及多方利益，无法随意用于公开基准；同时不同报告之间的格式差异巨大，很难统一出题。
paperclip选择生成路线，有三层好处。第一，生成内容不涉及版权问题，可以自由分发和修改。第二，生成过程中可以控制文档的主题、长度、信息分布，做到标准化生产。第三，也是最巧妙的一点：生成文档时使用的是另一个独立的模型，且生成任务经过了精心设计，被测模型在物理上就“没读过”这份文档，杜绝了数据泄露的隐患。
用一个不恰当的类比，这就像出卷老师用的草稿纸和考生用的试卷是两套语言系统，考生不可能事先知道答案。
3. 实操全记录：从环境搭建到跑出第一份报告
3.1 环境准备与安装
paperclip的安装过程比较常规，但有几个细节值得注意。官方仓库对Python版本有要求，我是在3.11环境下跑通的，3.10也可以但是部分依赖需要单独编译。
git clone https://github.com/openai/paperclip.git cd paperclip python -m venv .venv source .venv/bin/activate pip install -e .注意这里建议用虚拟环境，因为paperclip依赖的PDF处理库版本比较敏感，我一度因为本机有旧版本的reportlab导致中文字体嵌入出问题，折腾了一个下午。装完之后可以跑一条自检命令确认整链路是通的：
paperclip --self-test3.2 配置API密钥与生成策略
待处理的文档生成依赖OpenAI的API。如果想控制成本，建议在配置里注意两个参数：生成时使用的模型规格和单份文档的最大篇幅。默认配置生成的文档偏长，单份可能在40到60页之间，内容和版式复杂度都高，当然消耗的token也比较可观。
我个人的实践是先在配置里把max_pages降到10，把小规模生成的跑通，确认输出质量后再放开。不要一上来就生成60页的文档，如果代码有问题，你浪费的不仅是一个小时，而是一整天的预算。
配置文件是~/.paperclip/config.yaml，核心部分长这样：
generation: model: gpt-4o max_pages: 30 num_samples: 5 fruit_evaluation: model: gpt-4o-mini temperature: 0.2这里num_samples控制生成多少份测试文档。第一次跑建议3到5份，跑通后再上规模。生成策略上，我习惯把文档类型设定为“审计报告”和“公司年度总结”交叉使用，这两类文档天然具备表格多、引用多、数据分散的特点，评测维度拉得比较开。
3.3 生成测试集与质量复核
运行生成命令：
paperclip generate --config ~/.paperclip/config.yaml --output-dir ./eval_set每份文档的生成时长取决于篇幅和当下API的负载，通常40页的文档大约需要2到3分钟。生成完毕后在输出目录里会看到对应的.pdf文件和一份metadata.json。强烈建议大家先去人工翻两份生成的PDF，确认排版正常、表格没有被切碎、页码顺序正确，再来做后续评估。视觉质量直接影响后续文本解析的效果。
纸上谈兵到这儿就够了，下面说说测试本身。
3.4 跑评估并导出结果
文档生成完毕，开始跑评估：
paperclip evaluate --input-dir ./eval_set --output-dir ./results评估阶段会把每份PDF解析成文本，生成对应的测试问题集，然后逐题让被测模型回答，最后统一打分。默认的输出结果是一个JSON文件，包含每道题的得分、模型输出原文以及标准答案。
我的习惯是把--output-dir指向一个带日期和模型名的目录（比如./results/20240115_qwen25_72b），因为paperclip不会自动重命名，跑多轮你根本分不清哪份是哪份。
作为参考，一个包含5份40页文档的测试集，在单张T4显卡上用14B模型推理，大约需要2到3小时。如果只是想做快速验证，可以用--quick参数只跑每份文档的前5道题，但这样出来的分数参考意义有限，只适合调试流程。
4. 关键参数与评估结果解读
4.1 两个需要调明白的参数
实测下来，有两个参数对结果影响最大。
一个是temperature。因为评测任务的答案相对明确，我建议设为0到0.2之间。别小看这点差别，我用同一个模型跑过，温度从0.2调到0.7，有一道跨页推理题的得分从1降到了0——模型在“不确定”的状态下开始编细节了。
另一个是max_tokens，也就是模型回答的最大长度。很多长上下文任务需要模型输出详细的推理链条，如果限制得太小，模型很容易在论证到一半的时候被截断，导致答案不完整被记零。我一般至少给到1024。
一个容易忽略的点是，paperclip的评分器本身也是一个模型。评分器的工作是根据标准答案判断模型的输出“对不对”。如果你的被测模型输出语言和标准答案语言不一致，很影响最终卷面分。
4.2 分数之外的观察维度
paperclip输出结果的JSON结构里，除了题目的得分，还提供了一些过程性字段。其中值得关注的是每个样本的“注意力痕迹”，它记录了模型在推理时关注了文档中的哪些区域（这里指被解析后的文档块）。
这个字段的用途在于区分“真会”与“假会”。有些模型得分不错，但注意力痕迹显示它在答第一题时几乎把整篇文档都“看”了一遍，这说明它不是精准检索，而是广撒网捞到的答案。在真实使用场景里，这种“囫囵吞枣式”的检索方式，消耗的上下文窗口和计算资源都高得多。
所以我的建议是不要只盯最终分数，而是把注意力痕迹和得分结合起来看。一个得分高、注意力集中的模型，才是真正具备工程可用性的模型；得分高但每个问题都全局扫描的模型，在长文档处理中并不能带来好的用户体验。
4.3 如何做多模型横向对比
做模型评测，横评是绕不开的。我在做一个中等尺寸模型对比测试的时候，会固定同一个测试集，让多个模型分别跑，然后对比“总分”、“分区得分”、“超页得分”三个指标。分区得分是测试集中题目按文档位置分桶后的得分，跨页类的题专门测模型建立多段落联系的能力。
实际操作里，跨页推理题是最能拉开模型差距的。我在最近一次测试中对比了三个7B左右的模型，其中两个在信息定位类题目上都拿到了80%以上的得分，但一旦遇到需要从第10页正文和第102页附录交叉取证的题目，其中一个模型的正确率直接掉到30%。这就是典型的“能看见，但串不起来”，它理解了局部的信息，却没能构建全局的文档图景。这个维度不通过长文档评估是暴露不出来的。
5. 踩坑手册与问题排查实录
5.1 生成的PDF排版错乱
最常遇到的坑是PDF生成阶段表格排版错乱。这种现象通常表现为表格列宽异常、文本溢出到页面边界之外、或者中文字符变成乱码。
排查思路分三步：
- 检查生成文档时用的模型是否支持中文排版指令。默认情况下，部分模型对详细布局指令的执行能力一般，可以尝试在配置里增加对格式要求的描述。
- 检查本机安装的字体。PDF生成组件如果找不到合适的中文字体，会出现“豆腐块”或完全空白。
- 升级依赖库版本。我遇到过一次PDF组件版本太旧导致表格边框绘制失败的案例，升级到指定版本后问题消失。
如果以上都不行，优先考虑临时把测试集文档类型切换到“英文审计报告”验证链路是否正常。能快速定位问题是出在生成环节还是解析环境。
5.2 模型得分波动异常
如果你用同一个模型同一个测试集连续跑两轮，发现两次得分差距超过5个百分点，先别怀疑随机性，大概率是解析环节不稳定。
paperclip对PDF的解析依赖版面分析模型。同样的PDF在两次解析时可能因为版面元素的排序规则微调，产生不同的文本流顺序。文本顺序一旦变了，模型在定位关键信息时的“路径”就会明显不同，最终导致结果差异。
解决办法是固定一个随机种子，并且在生成测试集时把解析后的文本产物也保存下来（--save-parsed-text）。之后的评估统一走“预解析文本”，而不是现场重新解析PDF。这样能够做到完全可复现。
5.3 推理时长过长导致评测卡死
有一次我跑一个14B模型的评测，单题推理时长远超预期，评测进程卡在一个文档的第7题上。排查后发现是解析出的文本超出了模型的上下文处理范围，模型陷入长文本循环“绕不出来”。
处理方法有两个：一是把被测模型的上下文窗口上限在配置里显式声明，paperclip会据此自动裁剪文档片段；二是启用--timeout参数给单题设置时间上限，超时按“未答出”来处理。我建议两个都做，一方面保证评测进度，另一方面也间接测试模型在超长输入下的工程速度。
6. 几点观察与个人心得
6.1 对模型能力差异的真实刻画
用paperclip跑完一轮各规模模型的评测后，我对中小尺寸模型的“长上下文实力”有了一个比较清晰的认识。
很多在通用benchmark上分数接近的模型，放到真长文场景下会拉开极大的差距。7B级别里表现最好的模型，在跨页推理题上能拿到60%以上的正确率；也有同尺寸的模型，信息定位还可以，但一旦要求它跨文档汇总，就频繁出现“遗漏关键信息”和“生成与原文相悖的细节”的问题。
这类差异在普通评测里是被掩盖的，因为那些基准里的推理链路短到不足以触发“长程遗忘”。这也解释了一个现象：为什么有些模型指标很好看，部署到RAG应用里就不如另一个“分数略低”的模型，因为RAG的摘要生成天然就要求模型拼接多个来源的信息，这正是长文档推理能力的体现。
6.2 与其他长上下文评测工具的搭配
需要说明一点，paperclip不是用来替代其他评测工具的，更准确说它是一种“上限压力测试”。
我给团队的评测方案目前是这样的：先跑常规的NIAH基线，确认模型的基础长文检索能力没有明显短板；然后用paperclip做高难度的信息密度评测，侧重跨页关联和深层推理；最后再拿几份真实业务场景的脱敏文档做抽测，验证体验侧的可行性。
这样分级的好处是每一层都能快速定位问题。如果第一层过不了，就不必上第二层了，因为基础能力不够，上难度评测纯属浪费钱和时间。
6.3 做评测的两个原则
一年多实践下来，有两个原则我一直坚持。
第一，永远不要只看总分。总分容易掩盖结构性的短板，只有分区得分才能告诉你模型的问题出在局部检索、跨页关联还是长程记忆。不少朋友拿着90%的总分来问为什么自己的RAG效果不好，一看分区得分，最该强的长程推理类目只有30%，总分再高也弥补不了这个致命短板。
第二，评测材料一定要有“真实的复杂性”。如果测试材料全是人工生成的千篇一律的模板文档，那你测出来的不是长上下文能力，而是模型对模板的拟合程度。paperclip用模型生成文档的方式，至少在复杂度这个维度上做到了相对真实，这也是它在设计上最让我认可的地方。
7. 结尾多说一句
paperclip本身还在快速迭代中，官方仓库里后续应该会增加更多文档类型和题型设计，目前的版本对长文档场景的刻画已经比较立体，尤其适合想认真做长上下文能力评估的团队拿来复用。
个人实际体会是，评测工具的上限决定了你对自己模型的认知上限。用简单的工具，你只能得到一个简单的结论；用能生成复杂信息体的工具，你才能看到模型在真实压力下的表现，也才敢把结论带到生产决策里去。如果你正准备给手头的模型做一次长上下文“体检”，paperclip值得花一个完整的下午去跑通，它带来的结果可能会推翻一些你之前的认知。
