面向文档问答基准的AI代理评测与调优教程

一、教程目标

本教程要帮助读者完成一件具体的事：搭建一套可复现的文档问答（Document QA）基准评测流程，并在此基础上对AI代理系统进行调优与结果分析。

具体来说，读完后你应当能够：

1. 理解文档问答基准评测的基本组成：评测集、检索模块、阅读/推理模块、评分脚本；
2. 独立配置一套本地可运行的评测流水线，并跑通端到端流程；
3. 正确解读基准得分，理解“理想检索条件”与“端到端条件”下指标差异的含义；
4. 设计人机对比实验，定位AI代理系统的能力边界；
5. 针对常见失败模式进行排查与优化。

适合读者：具备一定编程基础的开发者、负责模型评测的算法工程师、需要评估文档智能处理方案的技术负责人，以及希望把评测流程纳入CI体系的运维人员。

说明：本文讨论的是通用方法论与工程实践，涉及具体模型或平台时统一以中立表述指代，不绑定任何特定厂商产品。

---

二、适用场景

文档问答基准评测通常出现在以下场景中：

• 模型选型：在多个候选模型或代理方案之间做横向比较，需要一个统一的量化标尺；
• 版本回归：模型或检索组件升级后，验证指标是否退化；
• 能力诊断：区分“检索没找对页面”与“找到了页面但读不懂”两类错误；
• 人机对比：评估AI代理在特定任务上相对人类分析师的位置，为业务上线提供依据；
• 提示词与编排调优：比较不同代理编排策略（单轮、多轮、工具调用）的效果差异。

不同场景对评测流程的要求不同：模型选型更关注可复现性与公平性；能力诊断更关注细粒度错误归因；人机对比则需要严格控制实验条件。

---

三、前置准备

在开始搭建之前，请确认具备以下条件：

3.1 环境与依赖

• 一台可运行容器或虚拟环境的开发机，建议具备充足的CPU与内存（文档解析与向量检索对内存较敏感）；
• 通用的编程运行时环境与包管理工具；
• 一个可用的模型推理入口（本地推理服务或经授权的API网关），仅需具备文本生成与工具调用能力；
• 可选的向量检索组件（如本地向量索引库）与文档解析组件（如PDF/HTML解析库）。

3.2 数据准备

• 评测集：一组“问题 + 标准答案 + 参考文档”的三元组。若基准本身只提供问题与答案，需要补充文档语料；
• 文档语料：原始文档需经过解析、分块、建立索引，形成可检索的知识库；
• 评分规则：明确答案判定方式（精确匹配、数值容差、语义相似度或人工判定）。

3.3 知识准备

• 理解检索增强生成（RAG）的基本流程：召回 → 重排 → 阅读 → 生成；
• 理解准确率（Accuracy）与容错匹配的定义；
• 了解“理想检索条件”（oracle retrieval）这一实验设计的含义：直接把包含答案的正确文档页面喂给阅读模块，从而把检索误差排除在外。

注意：评测集与文档语料往往涉及版权与隐私，务必在合规范围内使用，并对敏感字段做脱敏处理。

---

四、实施步骤

步骤一：明确评测口径，先定指标再搭系统

做什么：在写任何代码之前，先书面确定评测口径，包括：评测集规模、答案判定规则、是否启用理想检索条件、是否允许多轮工具调用。

为什么做：文档问答的得分对口径极其敏感。同一套系统，在“宽松的语义匹配”和“严格的精确匹配”下可能相差十几个百分点。口径不统一，横向比较就没有意义。

注意什么：

• 明确区分两类指标：端到端准确率（检索+阅读全流程）与理想检索下的阅读准确率（只考察阅读与推理）；
• 对数值型答案定义容差（如相对误差不超过1%）；
• 对多答案问题定义部分得分规则；
• 固定评测集的版本号，任何改动都要记录。

一个推荐的实验记录表结构示意：

experiment_id, dataset_version, retrieval_mode(oracle|end2end),
model_version, prompt_version, accuracy, timestamp

步骤二：构建文档解析与索引流水线

做什么：把原始文档解析为结构化文本，按语义或版面切块，生成向量索引与元数据（文档ID、页码、章节）。

为什么做：文档问答的答案往往落在表格、脚注、跨页段落中。切块策略直接决定召回质量，而召回质量又是端到端指标的天花板。

注意什么：

• 保留页码与版面信息，便于后续错误归因（“错在没检索到页面”还是“检索到了但读错”）；
• 表格建议单独切块并保留表头，避免行列语义丢失；
• 切块不宜过碎，否则阅读模块缺乏上下文；也不宜过大，否则召回精度下降；
• 为每个块建立稳定ID，便于缓存与复现。

示意性伪代码：

for doc in corpus:
    pages = parse(doc)                # 保留页码
    for page in pages:
        blocks = split_by_layout(page)  # 段落/表格/脚注分开
        for b in blocks:
            chunk = normalize(b)
            index.add(id=hash(doc, page, b), vector=embed(chunk), meta={doc, page})

步骤三：实现检索模块并支持“理想检索”开关

做什么：实现两种检索模式——常规向量检索（或混合检索），以及理想检索模式（直接按标注返回正确页面）。

为什么做：理想检索模式是定位瓶颈的关键工具。当理想检索准确率显著高于端到端准确率时，说明主要瓶颈在检索侧；反之则在阅读与推理侧。

注意什么：

• 理想检索模式仅用于诊断，不可用于对外汇报的最终指标；
• 常规检索建议采用“向量召回 + 关键词召回”的混合策略，再加重排；
• 记录每次检索返回的Top-K文档ID，用于离线分析召回率（Recall@K）。

步骤四：编排阅读与推理代理

做什么：把检索到的上下文送入模型，按统一提示词模板生成答案；对需要多步推理的问题，允许代理进行有限轮次的工具调用（如再次检索、计算）。

为什么做：文档问答中相当一部分问题需要跨页聚合或多步计算，单轮“读一遍就答”会系统性偏低。代理化编排能显著提升复杂问题的表现，但也引入新的失败模式（如循环调用、上下文超长）。

注意什么：

• 统一提示词模板并版本化管理，模板变更必须记录；
• 限制最大工具调用轮次与总token预算，防止成本失控；
• 要求模型输出结构化答案（答案值 + 引用页码），便于自动评分与人工复核；
• 对无法回答的问题允许输出“无法确定”，并在评分时单独统计拒答率。

示意性提示词结构：

系统：你是文档问答助手。仅依据给定文档作答。
      若文档不足以回答，输出 "INSUFFICIENT"。
用户：问题：{question}
      文档：{context_with_page_marks}
输出格式：{"answer": ..., "pages": [...], "confidence": ...}

步骤五：实现评分脚本与结果汇总

做什么：按步骤一定义的规则自动评分，输出总体准确率、分题型准确率、拒答率，并保存每条样本的中间结果。

为什么做：只有总体分数无法指导优化。保留逐样本的检索结果、模型输出与判定结果，才能做错误归因。

注意什么：

• 评分脚本自身要有单元测试，避免“评分器bug”污染结论；
• 对数值答案做归一化（单位换算、千分位去除）后再比较；
• 统计置信区间，小样本评测集的分数波动可能很大。

步骤六：设计人机对比实验

做什么：在相同条件下（同一批问题、同一份文档、同样的时间与工具限制），让人类分析师与AI代理系统分别作答，比较平均准确率。

为什么做：绝对分数缺乏直观意义，人机对比能给出可解释的能力定位。原始信息中提到的一类典型结果是：在获得准确文档页面的理想条件下，AI代理系统的平均准确率高于人类分析师。这类结论的价值在于说明“当检索问题被排除后，阅读与推理环节AI已具备优势”，但不能直接推广到端到端场景。

注意什么：

• 必须严格控制条件对等：人类分析师也应在“已知正确页面”的条件下作答，否则比较不公平；
• 样本量要足够，且问题难度分布要公开；
• 记录人类分析师的耗时，用于成本侧对比；
• 结论表述要限定边界，避免过度外推。

步骤七：错误归因与迭代

做什么：把错误分为四类并分别统计：检索未命中、页面命中但答案抽取错误、推理/计算错误、格式或评分不匹配。

为什么做：不同错误类型对应完全不同的优化手段。检索问题要靠切块与重排优化，推理问题要靠提示词与代理编排优化，评分问题则要改评分器。

注意什么：

• 每轮迭代只改一个变量，保持其他条件不变；
• 建立回归集，防止“修好一类、弄坏另一类”；
• 对高频错误样本做人工抽检，校准自动评分的可靠性。

---

五、配置说明

以下配置项在评测流程中最常影响结果，建议逐项显式设定并记录：

配置项	含义	常见取值逻辑	风险
切块长度	单块文本的最大长度	按文档类型调整，表格单独处理	过短丢上下文，过长降召回精度
Top-K 召回数	送入阅读模块的块数	与上下文窗口和成本平衡	过大引入噪声并推高成本
重排开关	是否对召回结果二次排序	语料大、噪声多时开启	增加延迟
最大工具调用轮次	代理可发起的额外检索/计算次数	按问题复杂度设定，通常较小	过大导致循环与成本失控
温度参数	生成随机性	评测场景建议取低值	高值导致结果不可复现
拒答阈值	触发“无法确定”的置信度门槛	按业务容忍度调整	过低虚答，过高漏答

配置管理的核心原则是可复现：任何一次评测运行都应能通过配置文件完整还原。

---

六、结果验证

完成一次评测运行后，按以下顺序验证结果可信度：

1. 流程完整性检查：样本数是否与评测集一致，是否存在解析失败被静默跳过的样本；
2. 中间结果抽检：随机抽取若干样本，人工核对检索返回的页面是否真实包含答案；
3. 评分器校验：构造一批已知对错的样例，验证评分脚本判定正确；
4. 复现性验证：相同配置重复运行，指标波动应在可接受范围内；
5. 分项指标对照：理想检索准确率应不低于端到端准确率，否则说明流程存在问题。

只有当以上检查全部通过，指标才具备对外引用的价值。

---

七、常见问题与排查

问题一：端到端指标远低于理想检索指标。
原因：检索侧是主要瓶颈。排查方向：检查切块是否破坏了表格与跨页段落；检查召回Top-K是否过小；检查嵌入模型是否适配该领域语料；尝试加入关键词召回与重排。

问题二：理想检索下仍有大量错误，且集中在数值类问题。
原因：多为计算或单位换算错误。排查方向：检查提示词是否要求展示计算步骤；检查评分器的数值归一化逻辑；考虑允许代理调用计算工具。

问题三：代理出现重复检索或超长上下文。
原因：工具调用轮次上限过高或提示词缺少终止条件。排查方向：降低最大轮次；在提示中明确“信息已足够时直接作答”；对上下文做截断与摘要。

问题四：指标在两次运行间波动明显。
原因：生成随机性、样本量不足或并行执行导致的不确定性。排查方向：固定随机种子与温度；扩大评测集；确保运行环境一致。

问题五：拒答率异常偏高。
原因：拒答阈值过严或上下文召回不足。排查方向：放宽阈值；检查召回是否漏掉关键页面；复核提示词中“无法确定”的触发条件是否表述过强。

---

八、优化建议

• 性能：对文档解析与嵌入做离线批量处理并缓存，评测时只跑检索与推理；对重复问题做结果缓存。
• 稳定性：固定模型版本、提示词版本与配置版本，三者任一变更都视为一次新实验。
• 可维护性：把评测流程脚本化并纳入持续集成，配置变更时自动触发回归评测。
• 成本控制：优先用理想检索模式做快速诊断，只在必要时跑全量端到端评测；对长文档做分层检索减少上下文长度。
• 安全与合规：评测语料脱敏；对外发布结论时注明评测口径、样本量与实验条件，避免绝对化表述。
• 结论表达：区分“理想条件下”与“端到端条件下”的结论边界，人机对比结果应同时报告双方的条件与耗时，避免单维度比较。

---

九、总结

本教程围绕文档问答基准评测，给出了从口径定义、索引构建、检索与代理编排、评分汇总，到人机对比实验与错误归因的完整流程。关键要点有三：先定口径再搭系统，保证指标可比；用理想检索开关做瓶颈定位，区分检索问题与阅读推理问题；严格控制人机对比的实验条件，让结论边界清晰可辩护。

后续可继续关注的方向包括：更细粒度的错误分类体系、评测集的难度分层统计，以及把评测流程产品化为可持续运行的回归体系。