企业级 AI-OCR #11：多维评测体系与 CI/CD 自动化 Benchmark

前十篇给出架构、算法和集成片段；它们没有构成已验证的完整生产系统。本篇定义如何验证这些片段。没有数据集、运行配置和报告时，不能声称准确率超过 99%、数据完整度达到 100%，或成本下降固定比例。

1. 基准集构建与防泄漏

按文档类型、语言、供应商/模板、扫描质量、页数和表格复杂度分层采样，保留正常样本与明确的异常件。两名标注人员独立标注字段值、原始文本、单位、来源页和 BBox，分歧由专家仲裁。确实无法辨认的字段应标为不可读，不应靠猜测制造标准答案。

调参集与最终测试集隔离；同一文档的不同扫描版本、同源模板或供应商高度相似样本应按组划分，防止近重复样本同时进入两侧。每次报告固定数据集版本/哈希、Schema 和 Prompt 版本、模型 ID、区域、依赖版本及关键配置。运行失败的样本必须保留，不能仅统计成功请求。

2. 五类指标的可复现定义

2.1 字段准确率与完整性

预定义每种文档的评估字段及标准化规则。编号、枚举等使用 Exact Match；日期可按声明的格式转换后比对；金额同时验证数值、币种及单位，不能为了“提高正确率”随意删除字符。分别报告关键字段与普通字段表现。

2.2 证据位置命中率

在页码一致、字段匹配且坐标协议统一的前提下计算 BBox IoU：

示例以 IoU >= 0.5 作为命中条件；这是可调评估阈值，不是通用质量标准。坐标非法、框缺失、零面积或页码错误都计为未命中。跨行/跨页字段可以有多个证据区域，需要预定义匹配方式，不能把整页大框作为有效精确定位。

2.3 页码溯源

以应有来源的字段为分母，比较预测页码与标注来源集合；本系列内部使用从 0 开始的 pageIndex，UI 显示加 1。缺页码计为失败，多来源字段不能随意压成单页。应同时报告“值正确且来源正确”的联合命中率，避免位置对但字段值错的结果被误认为可靠。

2.4 表格单元格 Precision、Recall 与 F1

必须先定义单元格的一对一匹配：在对应文档/表格内，根据规范化后的逻辑行列、rowSpan/colSpan、内容、币种及单位建立候选关系；需要几何匹配时再加入同页 IoU 条件。使用固定、确定的一对一分配规则，禁止一个预测单元格匹配多个标准单元格。多级表头展开方式和跨页续行规则也应版本化。

成功匹配为 TP，未匹配预测为 FP，未匹配标准为 FN，微平均可直接计算：

没有任何应评估表格且没有预测表格时该指标为 N/A，不能自动设为 1 并通过表格发布门禁。只有预测而没有标准表格时应产生 FP。结构正确率和内容正确率最好分别报告，便于定位合并单元格与 OCR 读值问题。

2.5 业务一致性与错误放行率

按文档类型选择金额、数量、时间及编码规则。字段缺失或类型错误导致无法运算时，计为未通过或单列不可校验，不能跳过后按成功处理。

一致性通过不等于事实正确。还需报告错误自动放行率：自动放行结果中与 Ground Truth 不符的文档比例；以及自动处理覆盖率、人工复核率、失败率。否则全部转人工或全部输出自洽的错误数字都可能“优化”某个单项指标。

3. 最小回归案例

前述实现至少应覆盖以下已知失效模式：模板词后增加普通正文词仍能匹配；通栏页底段落保持在页底；同页重复不算跨页页眉；缺失/null/字符串金额拒绝放行；反思请求包含前轮诊断；截断达到预算后明确失败；不同来源的相同明细保留；同一来源冲突触发复核；前端缩放后 BBox 与点击位置一致。

这些是功能回归测试，和真实模型评测相互补充。算法测试可以本地确定性运行，模型集成测试需要受控的凭证、费用预算和失败报告；不能把网络不稳定的集成调用当作全部单元测试。

4. JUnit 5 发布门禁示例

以下是测试骨架，BenchmarkRunner 及其聚合、匹配实现必须由业务工程提供，不是本系列已实现的评测引擎。接口要求返回各个指标的分母、失败样本及匹配结果，测试只消费其报告。测试集必须包含表格和来源标注，指标需为有限的 0～1 数值。

package com.idp.engine.benchmark;import org.junit.jupiter.api.Test;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.boot.test.context.SpringBootTest;import java.nio.file.Path;import static org.junit.jupiter.api.Assertions.*;@SpringBootTestpublic class IdpBenchmarkTest {    @Autowired    private BenchmarkRunner runner;    // 公共接口通常放入独立文件，Bean 由业务工程提供。    public interface BenchmarkRunner {        BenchmarkReport evaluateDirectory(Path dataset) throws Exception;    }    public record BenchmarkReport(int totalDocuments, int failedDocuments,        long expectedFields, long expectedEvidenceFields, long expectedPageFields,        long expectedTableCells, long applicableRuleDocuments,        double exactMatchRate, double bboxHitRate, double pageAttributionAccuracy,        double tableF1Score, double arithmeticConsistencyRate) {}    @Test    void fullRegressionMeetsQualityGate() throws Exception {        BenchmarkReport r = runner.evaluateDirectory(Path.of("src/test/resources/golden-dataset"));        assertTrue(r.totalDocuments() > 0, "测试集不可为空");        assertTrue(r.failedDocuments() >= 0 && r.failedDocuments() <= r.totalDocuments(), "失败数非法");        assertTrue(r.expectedFields() > 0 && r.expectedEvidenceFields() > 0            && r.expectedPageFields() > 0 && r.expectedTableCells() > 0            && r.applicableRuleDocuments() > 0, "缺少门禁所需评估样本");        assertAll(            () -> assertEquals(0, r.failedDocuments(), "本示例不允许处理失败样本"),            () -> checkMetric(r.exactMatchRate(), 0.95, "字段 EM"),            () -> checkMetric(r.bboxHitRate(), 0.90, "证据 BBox 命中"),            () -> checkMetric(r.pageAttributionAccuracy(), 0.99, "来源页码"),            () -> checkMetric(r.tableF1Score(), 0.92, "表格 F1"),            () -> checkMetric(r.arithmeticConsistencyRate(), 0.98, "业务一致性")        );    }    private static void checkMetric(double value, double threshold, String name) {        assertTrue(Double.isFinite(value) && value >= 0 && value <= 1, name + " 值非法");        assertTrue(value >= threshold, name + " 未达到示例门禁: " + value);    }}

类名使用 IdpBenchmarkTest，匹配 Maven Surefire 默认规则；原先 IdpBenchmarkTestSuite 在未配置 includes 时可能被漏掉。CI 应显式运行该测试（如 mvn -Dtest=IdpBenchmarkTest test），检查确实发现并执行了测试，并设置无匹配测试时失败，不能只看命令退出码或日志中有无指标。Surefire 测试发现规则

这些阈值仅用于演示，实际阈值应由分层基线及业务风险决定。Java 21 预览 API 所在工程还需按第 1 篇为测试 JVM 配置 --enable-preview。本测试没有包含延迟、费用及自动放行门禁；投产项目必须为这些指标增加相应数据和断言，不能把它描述为全部生产门禁。

5. CI/CD 报告与结论表达

固定绝对阈值之外，还应与上一个已接受版本比较回归幅度，并按文档类型和关键字段检查最差分组。报告保留失败样本、字段差异、预测与标准 BBox、运行配置、p50/p95 延迟、每文档费用和重试次数。小样本的百分比波动较大，应给出样本量及不确定性，而非仅输出一个准确率。

6. 全系列复盘

第 1～4 篇讨论执行器、分类、版面和图像输入；第 5～8 篇定义抽取、工具执行、截断及反思；第 9～10 篇展示复核交互与基础设施边界。本篇把这些模块连接到可检验的指标。

示例之外仍需实现并验证 Schema 校验适配器、具体文档 Handler、版面/表头解析、持久化任务与权限、完整评测 Runner 等模块。文章中的设计应作为工程起点，是否达到生产质量需要由明确版本和样本下的测试结果决定。