MinerU PDF 提取器

使用 MinerU API 将 PDF 文档提取为结构化 Markdown。支持公式识别、表格提取和 OCR。

注意：本技能为社区维护，非 MinerU 官方产品。您需自行从 MinerU 获取 API 密钥。

📁 技能目录结构

mineru-pdf-extractor/
├── SKILL.md                          # 英文文档
├── SKILL_zh.md                       # 中文文档
├── docs/                             # 文档
│   ├── Local_File_Parsing_Guide.md   # 本地 PDF 解析详细指南（英文）
│   ├── Online_URL_Parsing_Guide.md   # 在线 PDF 解析详细指南（英文）
│   ├── MinerU_本地文档解析完整流程.md  # 本地解析完整流程（中文）
│   └── MinerU_在线文档解析完整流程.md  # 在线解析完整流程（中文）
└── scripts/                          # 可执行脚本
    ├── local_file_step1_apply_upload_url.sh    # 本地解析第 1 步
    ├── local_file_step2_upload_file.sh         # 本地解析第 2 步
    ├── local_file_step3_poll_result.sh         # 本地解析第 3 步
    ├── local_file_step4_download.sh            # 本地解析第 4 步
    ├── online_file_step1_submit_task.sh        # 在线解析第 1 步
    └── online_file_step2_poll_result.sh        # 在线解析第 2 步

🔧 系统要求

必需的环境变量

脚本会自动从环境变量中读取 MinerU Token（任选其一）：

# 方式 1：设置 MINERU_TOKEN
export MINERU_TOKEN="your_api_token_here"

# 方式 2：设置 MINERU_API_KEY
export MINERU_API_KEY="your_api_token_here"

必需的命令行工具

• curl — 用于发起 HTTP 请求（通常已预装）
• unzip — 用于解压结果文件（通常已预装）

可选工具

• jq — 用于增强 JSON 解析与安全性（推荐但非必需）
  • 若未安装，脚本将自动降级使用备用方法
  • 安装方式：apt-get install jq（Debian/Ubuntu）或 brew install jq（macOS）

可选配置

# 设置 API 基础 URL（默认已预配置）
export MINERU_BASE_URL="https://mineru.net/api/v4"

💡 获取 Token：访问 https://mineru.net/apiManage/docs 注册并获取 API Key

📄 功能 1：解析本地 PDF 文档

适用于本地存储的 PDF 文件。共需 4 个步骤。

快速开始

cd scripts/

# 第 1 步：申请上传 URL
./local_file_step1_apply_upload_url.sh /path/to/your.pdf
# 输出示例：BATCH_ID=xxx UPLOAD_URL=xxx

# 第 2 步：上传文件
./local_file_step2_upload_file.sh "$UPLOAD_URL" /path/to/your.pdf

# 第 3 步：轮询结果状态
./local_file_step3_poll_result.sh "$BATCH_ID"
# 输出示例：FULL_ZIP_URL=xxx

# 第 4 步：下载结果
./local_file_step4_download.sh "$FULL_ZIP_URL" result.zip extracted/

脚本说明

local_file_step1_apply_upload_url.sh

申请上传 URL 并获取 batch_id。

用法：

./local_file_step1_apply_upload_url.sh  [language] [layout_model]

参数说明：

• language：语言选项，ch（中文）、en（英文）、auto（自动检测），默认为 ch
• layout_model：版面分析模型，doclayout_yolo（速度快）、layoutlmv3（精度高），默认为 doclayout_yolo

输出示例：

BATCH_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
UPLOAD_URL=https://mineru.oss-cn-shanghai.aliyuncs.com/...

local_file_step2_upload_file.sh

将 PDF 文件上传至预签名 URL。

用法：

./local_file_step2_upload_file.sh  

local_file_step3_poll_result.sh

持续轮询提取任务状态，直至完成或失败。

用法：

./local_file_step3_poll_result.sh  [max_retries] [retry_interval_seconds]

输出示例：

FULL_ZIP_URL=https://cdn-mineru.openxlab.org.cn/pdf/.../xxx.zip

local_file_step4_download.sh

下载结果 ZIP 包并解压。

用法：

./local_file_step4_download.sh  [output_zip_filename] [extract_directory_name]

输出目录结构：

extracted/
├── full.md              # 📄 Markdown 文档（主结果）
├── images/              # 🖼️ 提取的图像
├── content_list.json    # 结构化内容
└── layout.json          # 版面分析数据

详细文档

📚 完整指南：参见 docs/Local_File_Parsing_Guide.md

🌐 功能 2：解析在线 PDF 文档（URL 方式）

适用于已发布于网络的 PDF 文件（如 arXiv、网站等）。仅需 2 步，更简洁高效。

快速开始

cd scripts/

# 第 1 步：提交解析任务（直接提供 URL）
./online_file_step1_submit_task.sh "https://arxiv.org/pdf/2410.17247.pdf"
# 输出示例：TASK_ID=xxx

# 第 2 步：轮询结果并自动下载/解压
./online_file_step2_poll_result.sh "$TASK_ID" extracted/

脚本说明

online_file_step1_submit_task.sh

为在线 PDF 提交解析任务。

用法：

./online_file_step1_submit_task.sh  [language] [layout_model]

参数说明：

• pdf_url：在线 PDF 的完整 URL（必填）
• language：语言选项，ch（中文）、en（英文）、auto（自动检测），默认为 ch
• layout_model：版面分析模型，doclayout_yolo（速度快）、layoutlmv3（精度高），默认为 doclayout_yolo

输出示例：

TASK_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

online_file_step2_poll_result.sh

轮询提取结果，并在完成后自动下载与解压。

用法：

./online_file_step2_poll_result.sh  [output_directory] [max_retries] [retry_interval_seconds]

输出目录结构：

extracted/
├── full.md              # 📄 Markdown 文档（主结果）
├── images/              # 🖼️ 提取的图像
├── content_list.json    # 结构化内容
└── layout.json          # 版面分析数据

详细文档

📚 完整指南：参见 docs/Online_URL_Parsing_Guide.md

📊 两种解析方式对比

⚙️ 高级用法

批量处理本地文件

for pdf in /path/to/pdfs/*.pdf; do
    echo "Processing: $pdf"
    
    # 第 1 步
    result=$(./local_file_step1_apply_upload_url.sh "$pdf" 2>&1)
    batch_id=$(echo "$result" | grep BATCH_ID | cut -d= -f2)
    upload_url=$(echo "$result" | grep UPLOAD_URL | cut -d= -f2)
    
    # 第 2 步
    ./local_file_step2_upload_file.sh "$upload_url" "$pdf"
    
    # 第 3 步
    zip_url=$(./local_file_step3_poll_result.sh "$batch_id" | grep FULL_ZIP_URL | cut -d= -f2)
    
    # 第 4 步
    filename=$(basename "$pdf" .pdf)
    ./local_file_step4_download.sh "$zip_url" "${filename}.zip" "${filename}_extracted"
done

批量处理在线文件

for url in 
  "https://arxiv.org/pdf/2410.17247.pdf" 
  "https://arxiv.org/pdf/2409.12345.pdf"; do
    echo "Processing: $url"
    
    # 第 1 步
    result=$(./online_file_step1_submit_task.sh "$url" 2>&1)
    task_id=$(echo "$result" | grep TASK_ID | cut -d= -f2)
    
    # 第 2 步
    filename=$(basename "$url" .pdf)
    ./online_file_step2_poll_result.sh "$task_id" "${filename}_extracted"
done

⚠️ 注意事项

1. Token 配置：脚本优先读取 MINERU_TOKEN，未设置时回退至 MINERU_API_KEY
2. Token 安全性：请勿在脚本中硬编码 Token；应始终通过环境变量传入
3. URL 可访问性：在线解析时，请确保提供的 URL 可被公网访问
4. 文件限制：单个文件建议不超过 200MB，最大页数建议不超过 600 页
5. 网络稳定性：上传大文件时请确保网络连接稳定
6. 安全性：本技能内置输入校验与清洗机制，可防范 JSON 注入及路径遍历攻击
7. 可选 jq 工具：安装 jq 可提升 JSON 解析能力，并启用额外安全检查

📚 参考文档

外部资源：

• 🏠 MinerU 官网：https://mineru.net/
• 📖 API 文档：https://mineru.net/apiManage/docs
• 💻 GitHub 仓库：https://github.com/opendatalab/MinerU

技能版本：1.0.0
发布日期：2026-02-18
社区技能 — 与 MinerU 官方无关联