名称: mineru-pDF-提取器描述: 使用 MinerU API 将 PDF 内容提取为 Markdown 格式。支持公式、表格、OCR。提供本地文件和在线 URL 两种解析方法。作者: 社区版本: 1.0.0 主页: https://mineru.net/ 源码: https://github.com/opendatalab/MinerU 环境变量:

名称: MINERU_TOKEN 描述: “用于身份验证的 MinerU API 令牌（主要）” 必需: true
名称: MINERU_API_KEY 描述: “如果未设置 MINERU_TOKEN，则使用此备用 API 令牌” 必需: false
名称: MINERU_BASE_URL 描述: “API 基础 URL（可选，默认为 https://mineru.net/api/v4）” 必需: false 默认值: “https://mineru.net/api/v4” 所需工具: 必需:
- 名称: curl 描述: “用于 API 请求和文件下载的 HTTP 客户端”
- 名称: unzip 描述: “用于解压结果 ZIP 文件的归档提取工具” 可选:
- 名称: jq 描述: “用于增强 JSON 解析和安全性的 JSON 处理器（推荐）”

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 令牌（选择其一）：

# 选项 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"

💡 获取令牌: 访问 https://mineru.net/apiManage/docs 注册并获取 API 密钥

📄 功能 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 <pdf文件路径> [语言] [布局模型]

参数:

语言: ch (中文), en (英文), auto (自动检测), 默认 ch
布局模型: 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 <上传_url> <pdf文件路径>

local_file_step3_poll_result.sh

轮询提取结果，直到完成或失败。

用法:

./local_file_step3_poll_result.sh <batch_id> [最大重试次数] [重试间隔秒数]

输出:

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

local_file_step4_download.sh

下载结果 ZIP 文件并解压。

用法:

./local_file_step4_download.sh <zip_url> [输出_zip_文件名] [解压目录名]

输出结构:

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 <pdf_url> [语言] [布局模型]

参数:

pdf_url: 在线 PDF 的完整 URL（必需）
语言: ch (中文), en (英文), auto (自动检测), 默认 ch
布局模型: doclayout_yolo (快速), layoutlmv3 (准确), 默认 doclayout_yolo

输出:

TASK_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

online_file_step2_poll_result.sh

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

用法:

./online_file_step2_poll_result.sh <task_id> [输出目录] [最大重试次数] [重试间隔秒数]

输出结构:

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

详细文档

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

📊 两种解析方法对比

特性	本地 PDF 解析	在线 PDF 解析
步骤	4 步	2 步
需要上传	✅ 是	❌ 否
平均时间	30-60 秒	10-20 秒
使用场景	本地文件	已在线文件（arXiv、网站等）
文件大小限制	200MB	受源服务器限制

⚙️ 高级用法

批量处理本地文件

for pdf in /path/to/pdfs/*.pdf; do
    echo "处理中: $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 "处理中: $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

⚠️ 注意事项

令牌配置: 脚本优先使用 MINERU_TOKEN，如果未找到则回退到 MINERU_API_KEY
令牌安全: 请勿在脚本中硬编码令牌；使用环境变量
URL 可访问性: 对于在线解析，请确保提供的 URL 可公开访问
文件限制: 单个文件建议不超过 200MB，最多 600 页
网络稳定性: 上传大文件时确保网络稳定
安全性: 此技能包含输入验证和清理，以防止 JSON 注入和目录遍历攻击
可选 jq: 安装 jq 可提供增强的 JSON 解析和额外的安全检查

📚 参考文档

文档	描述
`docs/Local_File_Parsing_Guide.md`	本地 PDF 解析的详细 curl 命令和参数
`docs/Online_URL_Parsing_Guide.md`	在线 PDF 解析的详细 curl 命令和参数

外部资源:

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

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