MinerU PDF Extractor

核心用法

MinerU PDF Extractor 是一款社区开发的 Shell 脚本工具集，用于调用 MinerU API 将 PDF 文档转换为结构化 Markdown 格式。该 skill 提供两条工作流：

1. 本地文件解析（4 步骤）：申请上传 URL → 上传本地 PDF → 轮询处理结果 → 下载并解压结果包
2. 在线 URL 解析（2 步骤）：直接提交 PDF 链接 → 轮询并自动下载结果

解析结果包含 full.md（主文档）、images/（提取图片）、content_list.json（结构化内容）及 layout.json（版式分析数据）。支持中文/英文/自动检测语言切换，可选 doclayout_yolo（快速）或 layoutlmv3（精准）两种版面分析模型。

显著优点

• 专业级 PDF 解析能力：依托 MinerU 官方 API，具备学术论文、复杂表格、LaTeX 公式的深度识别能力，转换质量显著优于普通 PDF 转文本工具
• 双模式灵活适配：本地文件模式支持大文件（≤200MB），在线模式省去上传等待（10-20 秒），适合 arXiv 等公开资源批量处理
• 完整结果结构：除 Markdown 外，保留原始 JSON 结构化数据与版式信息，便于下游二次开发
• 批量处理友好：脚本化设计天然支持 for 循环批量操作，配合 jq 可实现结果自动化提取
• 开源透明：脚本源码公开，无黑盒逻辑，用户可审计每一行命令

潜在缺点与局限性

• 依赖外部 API 服务：必须注册 MinerU 账号并获取 Token，存在 API 调用费用（免费额度用尽后）及服务可用性风险
• 环境配置门槛：需正确设置 MINERU_TOKEN/MINERU_API_KEY 环境变量，对非技术用户不够友好
• Shell 环境限定：仅支持类 Unix 系统（Linux/macOS/WSL），Windows 原生 CMD/PowerShell 需额外适配
• 大文件上传瓶颈：本地模式需先将文件上传至 OSS，网络不稳定时易中断，且单文件 200MB 上限对扫描版大部头 PDF 可能不足
• 社区非官方维护：Skill 由社区贡献，API 变更时更新可能滞后

适合人群

• 学术研究者：批量下载 arXiv 论文并转换为可编辑 Markdown
• 数据工程师：构建 PDF 结构化抽取流水线
• 技术文档维护者：将遗留 PDF 手册迁移至 Markdown 知识库
• 开发者：需要 PDF 版式分析原始 JSON 数据进行模型训练或前端渲染

常规风险

• Token 泄露风险：环境变量配置不当或脚本历史记录可能导致 API Key 暴露，建议配合 .env 文件或密钥管理服务
• 敏感文件外传：本地模式需将 PDF 上传至 MinerU 服务器，含机密内容的文档存在数据跨境/第三方托管合规风险
• URL 可访问性依赖：在线模式要求源 PDF 公开可下载，私有网络或需认证的资源无法直接解析
• 结果一致性：复杂扫描版 PDF 的 OCR 效果受原图质量影响，公式识别偶发 LaTeX 语法错误需人工校对
• API 限流与计费：高频批量调用可能触发速率限制或产生意外费用，建议添加延迟与成本监控

核心用法

MinerU PDF Extractor 是 MinerU 官方 API 的社区封装工具，提供命令行脚本将 PDF 文档转换为结构化 Markdown 格式。支持两种工作模式：

本地文件解析（4步流程）：申请上传 URL → 上传 PDF → 轮询结果 → 下载解压。适用于本地存储的 PDF 文件，单文件上限 200MB/600 页。

在线 URL 解析（2步流程）：提交任务 → 轮询下载。直接解析网络 PDF（如 arXiv），无需上传，效率更高（10-20秒）。

输出包含：full.md（主文档）、images/（提取图片）、content_list.json（结构化内容）、layout.json（版面分析数据）。支持中文/英文/自动检测，可选快速（doclayout_yolo）或精确（layoutlmv3）版面模型。

显著优点

• 精准解析：MinerU 专为学术/技术文档优化，公式、表格、多栏版面识别准确率高
• 零依赖：仅需系统工具 curl/unzip，无 Python/Node 等运行时依赖
• 安全设计：API Token 强制环境变量读取，无硬编码；输入验证完善（文件名清理、目录遍历防护、URL 白名单）
• 灵活批处理：Shell 脚本易于集成到自动化工作流
• 双语支持：完整的中英文文档和指南

潜在局限

• 外部依赖：核心功能依赖 MinerU 云服务，需网络连接和有效 API Key
• 隐私考量：PDF 内容需上传至 MinerU 服务器（阿里云 OSS），敏感文档需谨慎
• 非官方封装：社区维护，非 MinerU 官方产品，更新可能滞后
• 解压风险：虽有限防护，从远程下载的 ZIP 文件仍存在潜在风险
• 无本地模式：默认不支持自托管 MinerU 实例（可通过 MINERU_BASE_URL 变通配置）

适合人群

• 研究人员、学生：批量处理 arXiv 论文、技术文档
• 开发者：构建文档处理 Pipeline、知识库入库
• 数据工程师：需要结构化提取 PDF 内容的自动化场景

常规风险

| 风险类型 | 等级 | 说明 |

|---------|------|------|

| 数据外传 | 中 | PDF 内容上传第三方服务器，敏感文档需评估 |

| 服务可用性 | 中 | 依赖 MinerU API 稳定性，Token 失效即中断 |

| 文件操作 | 低 | 远程 ZIP 下载解压，已有目录遍历防护 |

| 输入验证 | 低 | URL 验证仅检查协议后缀，边缘情况可能失效 |

建议：处理公开论文、技术文档理想；含敏感个人信息、商业机密的文档建议使用本地部署方案。