MinerU自动化流水线：结合Airflow实现定时提取任务-开发者社区

MinerU自动化流水线：结合Airflow实现定时提取任务

PDF文档的结构化信息提取一直是企业知识管理、学术研究和内容运营中的高频刚需。但面对多栏排版、嵌套表格、复杂公式和高清插图的PDF文件，传统工具往往力不从心——要么丢失格式，要么识别错位，要么需要人工反复校对。MinerU 2.5-1.2B 镜像的出现，让高质量、高保真、开箱即用的PDF智能解析真正走进了日常工程实践。而当它与Airflow结合，就不再只是“手动跑一次”，而是构建起一条可调度、可监控、可复用的自动化流水线。

本文不讲抽象概念，不堆技术参数，只聚焦一件事：如何把MinerU变成你每天自动工作的“数字员工”。你会看到——从单次命令行提取，到按固定时间批量处理指定目录下的PDF；从本地测试验证，到生产环境稳定运行；从结果自动归档，到异常自动告警。所有操作都基于你已有的MinerU镜像，无需重装模型、不改一行核心代码，只需增加几份配置文件和轻量脚本。

1. 理解MinerU镜像的核心能力与定位

MinerU 2.5-1.2B 并非一个孤立的模型，而是一整套为PDF深度解析量身打造的推理环境。它预装了MinerU 2.5 (2509-1.2B)主模型及配套的PDF-Extract-Kit-1.0OCR增强模块，所有依赖（包括magic-pdf[full]、CUDA驱动、图像处理库）均已就绪。这意味着：

你拿到的不是“需要自己下载权重、配环境、调参数”的半成品，而是一个即启即用的视觉多模态推理终端；
它专精于解决真实场景中的硬骨头：三栏新闻稿里的文字错乱、科研论文中跨页表格的断裂、教材里嵌入式公式的像素级还原、扫描件中模糊公式的LaTeX重建；
所有输出默认为结构清晰的Markdown，公式转为LaTeX代码，图片和表格原样保留为独立文件并自动关联，真正实现“所见即所得”的语义级提取。

这种“开箱即用”的价值，在自动化场景中被放大十倍——你不需要每次启动都检查CUDA版本、确认模型路径、调试OCR阈值。稳定性，是流水线的生命线，而这正是该镜像最扎实的底座。

2. 构建自动化流水线的三大核心组件

要让MinerU按时、按需、可靠地工作，不能只靠一条mineru -p xxx.pdf命令。我们需要三个关键角色协同：

2.1 调度中枢：Apache Airflow

Airflow不是替代MinerU，而是它的“指挥官”。它负责：

在设定时间（如每天凌晨2点）触发任务；
检查待处理PDF文件是否存在；
启动MinerU容器并传入正确参数；
监控执行状态，失败时自动重试或发通知；
记录完整日志，便于回溯问题。

它不碰模型，不改代码，只做最擅长的事：可靠调度与可观测性。

2.2 执行载体：Docker容器封装

我们不直接在宿主机跑MinerU，而是将其封装为Docker镜像。这样做的好处是：

环境隔离：避免与Airflow自身Python环境冲突；
路径统一：容器内固定工作路径（/root/workspace/MinerU2.5），外部挂载PDF输入和输出目录即可；
资源可控：通过Docker限制GPU显存使用，防止单个大文件拖垮整个调度集群。

2.3 业务胶水：轻量Shell脚本

这是连接Airflow与MinerU的“翻译器”。它只有几十行，却承担关键职责：

扫描指定输入目录（如/data/incoming/），找出所有.pdf文件；
对每个文件生成唯一输出子目录（如output_20240520_142301_test_report.pdf），避免文件名冲突；
调用mineru命令，明确指定输入路径、输出路径和任务类型（--task doc）；
捕获执行结果，返回成功/失败状态供Airflow判断。

它不处理PDF内容，不解析Markdown，只做最干净的“搬运+调用”。

3. 实战部署：四步完成端到端流水线

以下所有操作均在Linux服务器（Ubuntu 22.04）上完成，假设你已安装Docker、NVIDIA Container Toolkit及Airflow（2.8+）。

3.1 步骤一：准备数据与目录结构

在宿主机创建标准化目录，用于隔离输入、输出与日志：

mkdir -p /data/pdfs/{incoming,processed,failed} mkdir -p /data/logs/mineru

incoming/：放入待处理的PDF文件（Airflow会从此处扫描）；
processed/：成功提取后的原始PDF归档；
failed/：提取失败的PDF暂存，便于人工复查；
logs/：存放Airflow任务日志及脚本执行日志。

3.2 步骤二：编写核心执行脚本

创建/data/scripts/run_mineru.sh，内容如下（请根据你的MinerU镜像名称调整）：

#!/bin/bash # run_mineru.sh - MinerU自动化提取主脚本 set -e INPUT_DIR="/data/pdfs/incoming" OUTPUT_BASE="/data/pdfs/processed" FAILED_DIR="/data/pdfs/failed" LOG_DIR="/data/logs/mineru" # 获取当前时间戳，用于日志和输出目录命名 TIMESTAMP=$(date +"%Y%m%d_%H%M%S") LOG_FILE="${LOG_DIR}/mineru_${TIMESTAMP}.log" echo "[$(date)] Starting MinerU batch run" >> "$LOG_FILE" # 查找所有PDF文件 PDF_FILES=($(find "$INPUT_DIR" -maxdepth 1 -name "*.pdf" -type f | sort)) if [ ${#PDF_FILES[@]} -eq 0 ]; then echo "[$(date)] No PDF files found in $INPUT_DIR" >> "$LOG_FILE" exit 0 fi echo "[$(date)] Found ${#PDF_FILES[@]} PDF(s) to process" >> "$LOG_FILE" # 逐个处理 for pdf_path in "${PDF_FILES[@]}"; do # 提取文件名（不含路径和扩展名） filename=$(basename "$pdf_path" .pdf) # 构建唯一输出子目录 output_subdir="output_${TIMESTAMP}_${filename}" output_dir="${OUTPUT_BASE}/${output_subdir}" echo "[$(date)] Processing: $pdf_path -> $output_dir" >> "$LOG_FILE" # 启动Docker容器执行MinerU if docker run --rm \ --gpus all \ -v "$pdf_path:/root/workspace/MinerU2.5/test.pdf:ro" \ -v "$output_dir:/root/workspace/MinerU2.5/output:rw" \ -w "/root/workspace/MinerU2.5" \ -u "$(id -u):$(id -g)" \ your-mineru-image:2.5-1.2b \ sh -c "mineru -p test.pdf -o ./output --task doc 2>&1" >> "$LOG_FILE" 2>&1; then # 成功：移动PDF到processed，并记录 mv "$pdf_path" "${OUTPUT_BASE}/${filename}.pdf" echo "[$(date)] SUCCESS: $pdf_path processed to $output_dir" >> "$LOG_FILE" else # 失败：移动PDF到failed目录 mv "$pdf_path" "${FAILED_DIR}/${filename}_$(date +%Y%m%d_%H%M%S).pdf" echo "[$(date)] FAILED: $pdf_path moved to failed directory" >> "$LOG_FILE" fi done echo "[$(date)] Batch run completed" >> "$LOG_FILE"

赋予执行权限：

chmod +x /data/scripts/run_mineru.sh

关键说明：脚本中your-mineru-image:2.5-1.2b需替换为你实际的镜像名称（如csdn/mineru:2.5-1.2b）。-v参数将宿主机PDF文件以只读方式挂载进容器test.pdf，并将容器内./output映射到宿主机唯一子目录，彻底规避路径冲突。

3.3 步骤三：定义Airflow DAG

在Airflow的dags/目录下创建mineru_daily_dag.py：

from datetime import datetime, timedelta from airflow import DAG from airflow.operators.bash import BashOperator from airflow.operators.python import PythonOperator from airflow.models import Variable default_args = { 'owner': 'data-engineer', 'depends_on_past': False, 'start_date': datetime(2024, 5, 20), 'email_on_failure': True, 'email_on_retry': False, 'retries': 2, 'retry_delay': timedelta(minutes=5), } dag = DAG( 'mineru_daily_extraction', default_args=default_args, description='Daily PDF extraction using MinerU 2.5-1.2B', schedule_interval='0 2 * * *', # 每天凌晨2点执行 catchup=False, tags=['mineru', 'pdf', 'automation'], ) # 任务1：执行核心脚本 run_mineru_task = BashOperator( task_id='run_mineru_batch', bash_command='/data/scripts/run_mineru.sh', dag=dag, ) # 任务2（可选）：清理过期日志（保留7天） cleanup_logs_task = BashOperator( task_id='cleanup_old_logs', bash_command='find /data/logs/mineru -name "mineru_*.log" -mtime +7 -delete', dag=dag, ) run_mineru_task >> cleanup_logs_task

保存后，Airflow Web UI会自动加载该DAG。你可在UI中开启DAG、手动触发测试，并实时查看每一步的日志输出。

3.4 步骤四：验证与调优

首次运行后，检查以下几点：

输出目录：/data/pdfs/processed/下是否生成了带时间戳的子目录？其内是否有output.md、images/、tables/等？
原始PDF去向：incoming/中文件是否已移至processed/（成功）或failed/（失败）？
日志完整性：/data/logs/mineru/下的日志是否包含SUCCESS或FAILED标记？失败日志中是否有显存溢出（OOM）提示？
Airflow监控：Web UI中DAG状态是否为绿色（Success）？点击任务可查看完整stdout。

若遇显存不足，无需修改脚本，只需编辑宿主机上的/root/magic-pdf.json（挂载进容器的配置文件），将"device-mode": "cuda"改为"cpu"，然后重启DAG即可。这就是配置驱动的灵活性。

4. 进阶技巧：让流水线更智能、更省心

基础流水线跑通后，几个小改动就能大幅提升实用性：

4.1 支持动态PDF源：从本地目录到云存储

当前脚本扫描本地incoming/目录。若PDF来自企业网盘或对象存储（如OSS/S3），只需替换扫描逻辑：

# 替换原find命令，使用awscli或ossutil同步 aws s3 sync s3://my-bucket/pdfs/incoming/ /data/pdfs/incoming/ --exclude "*" --include "*.pdf" # 或 ossutil cp -r oss://my-bucket/pdfs/incoming/ /data/pdfs/incoming/ --include "*.pdf"

再配合定时同步任务，即可实现“云上传→自动提取→本地归档”的闭环。

4.2 结果自动分发：不只是存文件

提取出的Markdown常需进一步处理。在脚本末尾添加：

# 将最新生成的output.md发送到企业微信机器人（示例） LATEST_MD=$(find "$OUTPUT_BASE" -name "output.md" -type f | sort -r | head -n1) if [ -n "$LATEST_MD" ]; then curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY" \ -H 'Content-Type: application/json' \ -d "{\"msgtype\": \"text\", \"text\": {\"content\": \" MinerU完成新报告提取：$(basename $(dirname $LATEST_MD))\"}}" fi

4.3 异常精准捕获：区分“可恢复”与“需人工”

当前脚本将所有失败归入failed/。可增强判断逻辑：

# 在docker run后添加 if [[ "$output" == *"CUDA out of memory"* ]]; then echo "OOM detected, retrying with CPU mode..." >> "$LOG_FILE" # 临时修改配置，重试 sed -i 's/"device-mode": "cuda"/"device-mode": "cpu"/' /root/magic-pdf.json # 重新运行docker命令... elif [[ "$output" == *"Permission denied"* ]]; then echo "File permission error, skipping..." >> "$LOG_FILE" # 移动到special_handling/目录 fi