pdf-inspector 如何用 paired 基准 harness 检查两个 pdf2md 构建间的质量回归

pdf-inspector 如何用 paired 基准 harness 检查两个 pdf2md 构建间的质量回归【免费下载链接】pdf-inspectorFast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.项目地址: https://gitcode.com/GitHub_Trending/pdf/pdf-inspector当你修改了 pdf-inspector 的抽取或 Markdown 转换逻辑最需要确认的一件事是新构建的输出质量相对已发布的版本有没有回退。pdf-inspector 为此提供了一个 paired 基准 harnessscripts/bench_opendataloader.py用法说明见 docs/benchmarking.md它让 baseline 和 candidate 两个pdf2md二进制跑同一份本地 OpenDataLoader 语料用同一个 evaluator 对两份输出打分然后报告聚合指标差值与逐文档差值。这样做的目的按文档原文是避免比较来自不同语料修订或不同评估器版本的结果。README 的 Benchmark 一节也指向这个 harness用于在完全相同的语料和评估器修订下比较两个本地构建。下面按实际操作顺序说明准备构建、运行 harness、读取报告和门禁结论。准备条件两个构建与一个本地 bench 目录harness 的输入是两份pdf2md二进制加一个本地 OpenDataLoader 基准仓库。构建候选构建candidate。在 pdf-inspector 仓库内执行cargo build --release产物是target/release/pdf2md。准备基线构建baseline。用一个已发布版本或另一份 worktree/克隆的构建。docs/benchmarking.md 的示例指向../pdf-inspector-main/target/release/pdf2md即同一仓库的另一份检出在基线提交上构建出的二进制。准备本地 OpenDataLoader 基准目录示例中是../opendataloader-bench。脚本启动前会检查以下路径任一缺失会直接报错退出bench-dir/src/pdf_parser.pyOpenDataLoader parserbench-dir/src/evaluator.py评估器baseline 二进制、candidate 二进制Python 解释器未指定--python时默认使用bench-dir/.venv/bin/python运行 paired harnessdocs/benchmarking.md 给出的示例命令路径为文档中的同级目录布局示例替换成你实际的 bench 目录与基线构建位置即可cargo build --release python3 scripts/bench_opendataloader.py \ --bench-dir ../opendataloader-bench \ --baseline ../pdf-inspector-main/target/release/pdf2md \ --candidate target/release/pdf2md \ --max-document-regression 0.02 \ --json-output /tmp/pdf-inspector-benchmark.json参数用途--bench-dir本地 OpenDataLoader 基准仓库目录包含语料、parser 和 evaluator。--baseline/--candidate两份pdf2md二进制的路径。--max-document-regression 0.02单文档最大允许回退 0.02不传则不做逐文档回退门禁。--json-output把完整对比结果写成 JSON 文件。执行流程与副作用读脚本 scripts/bench_opendataloader.py 可核对每一轮运行前脚本会删除 bench 目录下已有的prediction/pdf-inspector输出再重新生成避免陈旧预测混入评测。也就是说该命令会写 bench 仓库的prediction/pdf-inspector目录这是 harness 的管理区域跑之前确认里面没有你想保留的手动产物。每轮预测会被复制进临时目录后再交给 evaluatorbaseline 和 candidate 互不覆盖。脚本通过环境变量PDF_INSPECTOR_BINARY指定当前要评测的二进制然后在 bench 目录内运行src/pdf_parser.py --engine pdf-inspector --log-level WARNING再运行src/evaluator.py对该轮输出打分。读取报告与门禁结论控制台输出分三部分指标对比表每个指标一行列出 baseline、candidate 和 delta。覆盖的指标包括overall_mean、nid_mean、nid_s_mean、teds_mean、teds_s_mean、mhs_mean、mhs_s_mean仅在两份评测中都存在的指标才会列出。文档级汇总Documents: X improved, Y regressed, Z unchanged (N shared)以及 Largest improvements / Largest regressions 两个列表各默认前 10 条用--top调整。门禁结论通过输出Benchmark gate passed.进程退出码 0。失败向 stderr 输出Benchmark gate failed:并逐条列出原因退出码 1。门禁规则对应脚本里的evaluate_gatescandidate 的overall_mean差值不得低于--min-overall-delta默认为 0.0即总分不允许回退candidate 的 missing predictions 数量不得超过--max-missing默认为 0即不允许出现缺失输出传了--max-document-regression时最差单文档的 delta 不得低于负阈值示例中为 -0.02。注意这条门禁独立于--top的报告截断报告只显示前 N 条不影响门禁判定逐文档回退门禁只有在传了--max-document-regression时才生效默认门禁只看总分和缺失预测。指定--json-output后完整对比指标差值、missing predictions、逐文档 delta 与最大改进/回退列表会写入目标文件便于归档。可选分支参考评测与要求净提升--reference-evaluation path/to/evaluation.json额外把 candidate 与另一份评测 JSON 对比报告会追加 reference 的 overall 分数和 candidate 相对它的 delta。--require-reference-leadcandidate 相对 reference 的 overall 差值为负时让本次运行失败reference 缺少 overall 分数时门禁报reference overall score is unavailable。--min-overall-delta传正数要求 candidate 相对 baseline 有指定幅度的聚合净提升而不仅是不回退。常见失败与边界预检路径缺失时脚本直接退出并指明对象例如baseline binary not found: ...、OpenDataLoader parser not found: ...按提示检查对应构建或 bench 目录即可。参数校验--top、--max-document-regression、--max-missing不接受负数--min-overall-delta、--max-document-regression不接受非有限值nan/inf。harness 成立的前提是两个构建跑在同一份本地语料与同一版 evaluator 上。如果你更新过 bench 目录的语料修订新一轮的 delta 数字就和旧结果不可直接比较。门禁与报告行为的具体语义可以对照 scripts/tests/test_bench_opendataloader.py 里的单元测试其中覆盖了门禁四类失败、--top0时回退门禁仍然生效、以及陈旧预测会被清理等用例。退出码 0/1 的语义使得这条命令可以直接作为合并前的质量门禁candidate 相对 baseline 的总分不回退、不出现缺失预测、单文档回退不超过你设定的阈值时才会看到Benchmark gate passed.。【免费下载链接】pdf-inspectorFast Rust library for PDF inspection, classification, and text extraction. Intelligently detects scanned vs text-based PDFs to enable smart routing decisions.项目地址: https://gitcode.com/GitHub_Trending/pdf/pdf-inspector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考