MinerU自动化测试脚本编写：CI/CD集成实战指南

MinerU 2.5-1.2B 是一款专为复杂PDF文档结构化提取设计的深度学习模型镜像，聚焦于多栏排版、嵌套表格、数学公式与矢量图混合场景下的高保真Markdown转换。它不是通用OCR工具，而是面向技术文档、学术论文、产品手册等专业PDF内容的“理解型”提取引擎——能识别段落逻辑关系、保留公式语义、还原表格行列结构，并将图片按上下文位置精准锚定。本文不讲理论推导，也不堆砌参数指标，而是带你从零写出可落地的自动化测试脚本，并真正把它接入CI/CD流水线，在每次代码提交后自动验证PDF解析质量是否退化。

1. 为什么需要自动化测试？——从人工验证到可信交付

你可能已经成功在本地跑通了mineru -p test.pdf -o ./output --task doc这条命令，看到生成的Markdown里公式没乱码、表格没错行、图片路径正确。但这种“手动点一次、看一眼结果”的方式，在团队协作和持续迭代中很快会失效。

当新同事第一次拉取镜像，他是否知道要改哪几个配置才能适配自己服务器的GPU型号？
当你升级了magic-pdf[full]包的小版本，是否敢确认所有历史PDF样本仍能100%通过解析？
当OpenDataLab发布MinerU2.5-2509-1.2B的补丁模型，你如何快速判断它对财报类PDF的表格识别率提升了3%，还是意外降低了公式渲染精度？

这些问题的答案，不是靠人眼比对，而是靠可重复、可量化、可归档的自动化测试。它不是锦上添花的“高级功能”，而是把MinerU从“能用”推向“敢用”的关键一跃。

我们不追求覆盖全部PDF类型，而是聚焦三类最具代表性的“压力样本”：

学术论文PDF（含LaTeX公式+多级参考文献+跨页表格）
企业财报PDF（含合并报表嵌套表+页眉页脚干扰+扫描件混合）
技术白皮书PDF（含代码块截图+流程图+多栏图文混排）

这三类样本构成了我们的“黄金测试集”，它们小而精，平均体积<5MB，却足以暴露90%以上的实际部署问题。

2. 构建可执行的测试脚本：从命令行到断言逻辑

MinerU本身不提供测试框架，但它的CLI接口足够稳定，这正是我们构建自动化测试的基础。以下脚本不依赖任何外部测试库，仅用Shell + Python标准库即可完成端到端验证。

2.1 测试目录结构设计

在镜像的/root/workspace下新建测试目录：

cd /root/workspace mkdir -p mineru-test/{samples,expected,actual,reports}

samples/：存放三类PDF样本（paper.pdf,report.pdf,whitepaper.pdf）
expected/：存放人工校验通过的“黄金标准”Markdown（paper.md,report.md,whitepaper.md）
actual/：每次运行生成的实际输出
reports/：保存本次测试的差异报告与日志

这种结构清晰分离输入、预期、实际、输出，便于CI环境复现与排查。

2.2 核心测试脚本（shell + python混合）

创建/root/workspace/mineru-test/run_test.sh：

#!/bin/bash set -e # 任一命令失败即退出 TEST_DIR="/root/workspace/mineru-test" SAMPLES_DIR="$TEST_DIR/samples" EXPECTED_DIR="$TEST_DIR/expected" ACTUAL_DIR="$TEST_DIR/actual" REPORTS_DIR="$TEST_DIR/reports" # 清理上次输出 rm -rf "$ACTUAL_DIR" "$REPORTS_DIR" mkdir -p "$ACTUAL_DIR" "$REPORTS_DIR" echo " 开始运行MinerU自动化测试..." # 逐个处理样本 for pdf in "$SAMPLES_DIR"/*.pdf; do if [[ ! -f "$pdf" ]]; then continue fi basename=$(basename "$pdf" .pdf) echo " → 正在处理: $basename.pdf" # 执行MinerU提取（强制GPU，超时300秒） timeout 300 mineru -p "$pdf" -o "$ACTUAL_DIR" --task doc 2>&1 | tee "$REPORTS_DIR/${basename}_mineru.log" # 检查输出文件是否存在 if [[ ! -f "$ACTUAL_DIR/${basename}.md" ]]; then echo "❌ 失败: $basename.md 未生成" exit 1 fi # 调用Python脚本进行语义级比对 python3 "$TEST_DIR/compare_md.py" \ "$EXPECTED_DIR/${basename}.md" \ "$ACTUAL_DIR/${basename}.md" \ "$REPORTS_DIR/${basename}_diff.html" done echo " 全部样本处理完成"

该脚本做了四件关键事：

用timeout防止GPU卡死导致CI挂起
用tee同时保存原始日志供调试
对每个PDF生成独立差异报告
遇到缺失输出文件立即失败，不继续执行

2.3 语义级比对脚本（Python）

创建/root/workspace/mineru-test/compare_md.py：

#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ MinerU Markdown语义比对器 不比对空格/换行/注释，专注：公式块完整性、表格行列数、图片数量、标题层级 """ import sys import re from pathlib import Path def count_formulas(md_content): """统计$$...$$和$...$公式块数量""" double_dollar = len(re.findall(r'\$\$[\s\S]*?\$\$', md_content)) single_dollar = len(re.findall(r'(?<!\$)\$[^\$]+\$(?!\$)', md_content)) return double_dollar + single_dollar def count_tables(md_content): """粗略统计表格数量（以|---|开头的行）""" lines = md_content.split('\n') return sum(1 for line in lines if re.match(r'^\s*\|[-\s]+\|', line)) def count_images(md_content): """统计![]()图片引用数量""" return len(re.findall(r'!\[.*?\]\(.*?\)', md_content)) def count_headers(md_content): """统计各级标题数量""" h1 = md_content.count('\n# ') h2 = md_content.count('\n## ') h3 = md_content.count('\n### ') return h1 + h2 + h3 def main(expected_path, actual_path, report_path): try: with open(expected_path, 'r', encoding='utf-8') as f: exp = f.read() with open(actual_path, 'r', encoding='utf-8') as f: act = f.read() except Exception as e: print(f"读取文件失败: {e}") sys.exit(1) # 提取关键指标 exp_metrics = { 'formulas': count_formulas(exp), 'tables': count_tables(exp), 'images': count_images(exp), 'headers': count_headers(exp) } act_metrics = { 'formulas': count_formulas(act), 'tables': count_tables(act), 'images': count_images(act), 'headers': count_headers(act) } # 生成HTML差异报告 html = f"""<!DOCTYPE html> <html><head><title>MinerU {Path(expected_path).stem} 比对报告</title> <style>body{{font-family:sans-serif;margin:2em}}.ok{{color:green}}.ng{{color:red}}</style> </head><body><h1> {Path(expected_path).stem} 语义比对报告</h1> <table border="1" class="dataframe"><thead><tr><th>指标</th><th>预期值</th><th>实际值</th><th>状态</th></tr></thead><tbody>""" all_ok = True for key in ['formulas', 'tables', 'images', 'headers']: status = '' if exp_metrics[key] == act_metrics[key] else '❌' color = 'ok' if exp_metrics[key] == act_metrics[key] else 'ng' html += f"<tr><td>{key}</td><td>{exp_metrics[key]}</td><td>{act_metrics[key]}</td><td class='{color}'>{status}</td></tr>" if exp_metrics[key] != act_metrics[key]: all_ok = False html += "</tbody></table>" if not all_ok: html += "<p><strong> 检测到语义差异，请检查输出Markdown质量</strong></p>" else: html += "<p><strong> 所有语义指标匹配，通过测试</strong></p>" html += "</body></html>" with open(report_path, 'w', encoding='utf-8') as f: f.write(html) # 退出码：全匹配返回0，否则1（供shell脚本判断） sys.exit(0 if all_ok else 1) if __name__ == '__main__': if len(sys.argv) != 4: print("用法: python compare_md.py <预期.md> <实际.md> <报告.html>") sys.exit(1) main(sys.argv[1], sys.argv[2], sys.argv[3])

这个脚本的价值在于：它不追求字面完全一致（PDF渲染微小差异不可避免），而是抓住业务最关心的四个语义维度——公式、表格、图片、标题。只要这四项数量一致，就认为核心信息提取无损。你可以根据团队需求轻松扩展，比如增加“代码块数量”或“参考文献条目数”。

3. CI/CD集成：让测试成为代码提交的守门员

有了可执行的测试脚本，下一步就是让它在每次git push后自动运行。我们以GitHub Actions为例，展示如何在CSDN星图镜像环境中实现。

3.1 GitHub Actions工作流配置

在项目根目录创建.github/workflows/mineru-ci.yml：

name: MinerU PDF提取质量检测 on: push: branches: [main] paths: - 'Dockerfile' - 'requirements.txt' - 'mineru-test/**' jobs: test-mineru: runs-on: ubuntu-22.04 container: image: registry.cn-hangzhou.aliyuncs.com/csdn-ai/mineuru-2509-1.2b:latest options: --gpus all --shm-size=2g steps: - name: Checkout code uses: actions/checkout@v4 - name: Prepare test environment run: | cd /root/workspace mkdir -p mineru-test/{samples,expected,actual,reports} # 复制测试样本（此处应替换为你的私有存储链接） wget -O mineru-test/samples/paper.pdf https://example.com/paper.pdf wget -O mineru-test/samples/report.pdf https://example.com/report.pdf wget -O mineru-test/samples/whitepaper.pdf https://example.com/whitepaper.pdf # 复制黄金标准（需提前生成并存入仓库） cp tests/golden/*.md mineru-test/expected/ - name: Run MinerU automated test run: | cd /root/workspace chmod +x mineru-test/run_test.sh ./mineru-test/run_test.sh - name: Upload test reports if: always() uses: actions/upload-artifact@v3 with: name: mineru-test-reports path: /root/workspace/mineru-test/reports/

关键点说明：

container.image直接调用CSDN星图镜像，无需再docker build
options: --gpus all确保容器内可见GPU（需Runner主机已安装NVIDIA驱动）
--shm-size=2g解决多进程共享内存不足问题（MinerU内部使用multiprocessing）
if: always()确保无论测试成功失败都上传报告，方便事后分析

3.2 测试失败时的快速定位策略

当CI流水线报红，不要第一反应去重跑。请按此顺序排查：

查看mineru.log原始日志：是否出现CUDA out of memory？→ 降低batch_size或切回CPU模式
打开_diff.html报告：是公式数量少了？→ 检查PDF源文件是否被压缩降质；是表格数量多了？→ 可能是页眉页脚被误识别为表格
对比actual/与expected/的原始Markdown：用diff -u看具体哪一行不同，常发现是图片路径前缀不一致（如./images/vsimages/），此时需统一magic-pdf.json中的image-dir配置

这套机制把“为什么失败”从玄学问题变成了可追踪的日志链路。

4. 进阶实践：构建PDF质量基线与回归预警

自动化测试的终极目标，不是“这次有没有过”，而是“这次比上次好还是坏”。我们通过轻量级基线管理，让质量变化可视化。

4.1 建立质量基线

在/root/workspace/mineru-test/下创建baseline.json：

{ "paper.pdf": { "formulas": 42, "tables": 7, "images": 15, "headers": 23, "md_size_kb": 128 }, "report.pdf": { "formulas": 0, "tables": 24, "images": 8, "headers": 19, "md_size_kb": 205 } }

该文件记录每个样本在“当前最优版本”下的各项指标。每次新版本测试后，脚本自动更新此文件，形成质量演进快照。

4.2 回归预警脚本

新增/root/workspace/mineru-test/check_regression.py：

import json from pathlib import Path def load_baseline(): with open('baseline.json') as f: return json.load(f) def check_regression(current_results): baseline = load_baseline() regressions = [] for pdf_name, current in current_results.items(): if pdf_name not in baseline: continue base = baseline[pdf_name] for metric, value in current.items(): if metric in base and abs(value - base[metric]) > base[metric] * 0.05: # 5%波动阈值 regressions.append(f"{pdf_name}: {metric} 从{base[metric]}→{value} (变化{((value-base[metric])/base[metric]*100):.1f}%)") return regressions # 使用示例：在run_test.sh末尾调用 # regressions = check_regression({"paper.pdf": {"formulas": 40, ...}}) # if regressions: # print(" 检测到性能回归：") # for r in regressions: print(r)

当某次更新导致财报PDF的表格识别数下降8%，它会明确告诉你：“report.pdf: tables 从24→22”，而不是笼统地说“测试失败”。这才是工程化交付应有的确定性。

5. 总结：让MinerU真正成为你的PDF处理流水线一环

写到这里，你手里的MinerU已不再是那个“跑通了就行”的Demo模型，而是一个可验证、可监控、可回滚的生产级组件。回顾整个过程，我们没有修改一行MinerU源码，却完成了三重跃迁：

从手动到自动：用12行Shell + 80行Python，替代了每天重复的手动验证；
从黑盒到白盒：通过语义指标比对，把“提取效果好不好”转化为可量化的数字；
从单点到体系：CI/CD集成让质量保障嵌入开发流程，基线管理让技术决策有据可依。

最后提醒两个易忽略的实战细节：

PDF样本必须版本受控：不要用本地临时文件，所有samples/中的PDF应作为Git LFS对象纳入版本库，确保每次CI拉取的是同一份二进制；
GPU环境需显式声明：CSDN星图镜像虽预装CUDA，但在CI容器中仍需--gpus all参数，否则device-mode: cuda会静默降级为CPU，导致测试通过但线上性能不符。

真正的AI工程化，不在炫技的模型参数，而在这些让机器可靠运转的“螺丝钉”里。