MinerU命令行参数详解：-p -o --task使用指南
MinerU 2.5-1.2B 深度学习 PDF 提取镜像专为解决科研、工程与内容工作者日常面对的PDF解析难题而设计。它不是简单地把PDF转成文字，而是真正理解文档结构——能识别多栏排版、精准提取复杂表格、还原数学公式、保留图片语义，并最终输出可直接用于知识管理、AI训练或内容再创作的高质量Markdown文件。
本镜像已深度预装 GLM-4V-9B 模型权重及全套依赖环境，真正实现“开箱即用”。您无需繁琐配置，只需通过简单的三步指令即可在本地快速启动视觉多模态推理，极大地降低了模型部署与体验的门槛。
1. MinerU核心能力与适用场景
MinerU 2.5（版本号2509-1.2B）并非传统OCR工具，而是一个融合视觉理解、布局分析、文本识别与结构重建的端到端PDF智能解析系统。它特别适合以下几类真实工作流：
1.1 科研文献处理
- 快速将arXiv论文PDF转为带完整公式、图表引用和参考文献的Markdown
- 支持LaTeX公式原样还原（非图片），便于后续编辑与渲染
- 自动识别并分离“方法”“实验”“结论”等章节结构
1.2 技术文档归档
- 解析企业内部PDF手册、API文档、设计规范，生成结构化知识库
- 多栏技术白皮书（如芯片架构图+文字说明混合排版）可准确分块还原
- 表格数据不丢失，支持导出为CSV或嵌入Markdown表格
1.3 内容再生产准备
- 将行业报告、调研PDF一键转为公众号/知乎/Notion可用的富文本草稿
- 图片自动提取并命名（如
fig-1-architecture.png），附带上下文描述 - 公式、代码块、引用块均按语义保留，避免人工二次整理
关键提示：MinerU不是“PDF转Word”工具，它的目标是产出机器可读、人类可编辑、AI可理解的中间格式。这意味着你拿到的不是视觉近似的结果，而是语义准确的结构化数据。
2. 命令行参数详解：-p、-o、--task三大核心选项
MinerU的命令行接口简洁但功能明确。掌握-p、-o、--task三个参数，就掌握了90%的日常使用场景。它们不是孤立存在的，而是构成一个完整的“输入→处理→输出”链条。
2.1-p：指定输入PDF路径（必填）
-p是--pdf-path的缩写，用于告诉MinerU你要解析哪个PDF文件。这是唯一强制要求的参数。
支持类型：
- 单个PDF文件：
-p report.pdf - PDF文件列表（空格分隔）：
-p a.pdf b.pdf c.pdf - 目录路径（自动扫描所有PDF）：
-p ./papers/
- 单个PDF文件：
使用注意：
- 路径支持相对路径（推荐）和绝对路径
- 不支持通配符
*，如-p *.pdf会报错 - 若PDF文件名含空格，请用引号包裹：
-p "my paper.pdf"
常见错误示例：
# ❌ 错误：未指定-p，命令无法执行 mineru --task doc # ❌ 错误：路径不存在或权限不足 mineru -p /home/user/missing.pdf --task doc # 正确：路径存在且可读 mineru -p ./test.pdf --task doc
2.2-o：指定输出目录（必填）
-o是--output-dir的缩写，定义结果保存位置。它必须是一个目录路径，而非文件名。
目录行为逻辑：
- 如果目录不存在，MinerU会自动创建
- 如果目录已存在，MinerU会在其中新建子文件夹（以PDF文件名命名）
- 每个PDF对应一个独立子目录，避免不同任务结果混杂
典型结构示例：
mineru -p paper1.pdf paper2.pdf -o ./results执行后生成：
./results/ ├── paper1/ │ ├── paper1.md # 主Markdown文件 │ ├── images/ # 提取的所有图片 │ └── equations/ # 单独保存的公式图片（LaTeX_OCR输出） └── paper2/ ├── paper2.md ├── images/ └── equations/为什么不能指定文件名？
因为单个PDF可能生成多个文件（MD主文件 + 多张图 + 公式图 + 表格图），固定文件名无法承载这种结构。-o的设计本质是“为本次任务分配一个专属工作空间”。
2.3--task：定义解析任务类型（必填）
--task参数决定MinerU“以什么角色”来理解这份PDF。它不是可选配置，而是任务级指令，直接影响模型调用路径、后处理逻辑和输出格式。
| 任务类型 | 命令写法 | 适用场景 | 输出特点 |
|---|---|---|---|
| 文档解析 | --task doc | 通用学术/技术PDF | 输出完整Markdown，含标题层级、段落、列表、公式、表格、图片，结构最全 |
| 纯文本提取 | --task text | 只需文字内容（如法律条文、合同） | 输出纯.txt文件，无格式、无图片、无公式，速度最快 |
| 表格优先 | --task table | PDF中表格是核心信息（如财报、数据报告） | 输出tables/子目录，含CSV、Excel及Markdown表格，文字内容仅作辅助注释 |
选择建议：
- 95%的场景请用
--task doc——它才是MinerU 2.5的核心价值所在 --task text仅在显存严重不足或只需关键词检索时启用--task table适合财务、统计类用户，对表格识别精度有极致要求
- 95%的场景请用
重要提醒：
--task不改变模型权重，而是切换推理流程。例如doc模式会调用GLM-4V-9B做图文联合理解，而text模式则跳过视觉模块，直走OCR流水线。
3. 实战组合：从入门到进阶的5种常用命令
光懂单个参数不够，真实工作流中它们总是组合出现。以下是经过验证的5种高频用法，覆盖新手到进阶需求。
3.1 最简启动：单文件快速验证
mineru -p test.pdf -o ./output --task doc- 适用：首次运行，确认环境是否正常
- 效果：解析
test.pdf，结果存入./output/test/ - 耗时参考：A4单页PDF约8~12秒（RTX 4090）
3.2 批量处理：一次解析整个文件夹
mineru -p ./papers/ -o ./parsed --task doc- 适用：整理个人文献库、处理会议投稿集
- 效果：自动扫描
./papers/下所有PDF，为每个文件创建独立子目录 - 优势：无需写Shell循环，内置并发控制（默认4线程）
3.3 混合任务：同一命令处理不同类型PDF
mineru -p report.pdf manual.pdf -o ./mixed --task doc mineru -p data.pdf -o ./mixed --task table- 适用：项目中同时存在技术报告与数据报表
- 技巧：两次命令指向同一
-o目录，MinerU会自动区分子目录，避免覆盖
3.4 精准控制：指定GPU设备与显存策略
CUDA_VISIBLE_DEVICES=1 mineru -p thesis.pdf -o ./thesis --task doc- 适用：服务器多卡环境，需指定某张GPU
- 原理：MinerU完全兼容CUDA环境变量，无需修改配置文件
3.5 故障回退：显存不足时无缝切CPU模式
# 先尝试GPU（默认） mineru -p bigbook.pdf -o ./book --task doc # 若报OOM错误，立即改用CPU（修改配置文件后重试） sed -i 's/"device-mode": "cuda"/"device-mode": "cpu"/' /root/magic-pdf.json mineru -p bigbook.pdf -o ./book --task doc- 关键点：CPU模式仍能完成全部解析，只是速度下降约3倍，但稳定性100%
4. 高级技巧与避坑指南
掌握基础参数后，这些实战经验能帮你绕过90%的“为什么没效果”类问题。
4.1 PDF预处理：提升准确率的3个动作
MinerU再强，也无法修复源头质量。以下操作应在运行命令前完成：
动作1：删除扫描件水印
使用pdfimages -list input.pdf检查是否为扫描PDF。若是，先用GIMP或Adobe Acrobat去水印，再运行MinerU。动作2：合并分散页面
若PDF由多张截图拼接而成（常见于微信长图文），用pdfunite page1.pdf page2.pdf merged.pdf合并后再解析。动作3：降级加密
遇到“Permission denied”错误，用qpdf --decrypt input.pdf output.pdf解除复制限制（仅限合法用途）。
4.2 输出结果解读：如何判断解析是否成功
不要只看.md文件是否存在，重点检查三个信号：
信号1：公式目录非空
进入./output/xxx/equations/，应有.png文件。若为空，说明LaTeX_OCR未触发，检查PDF中公式是否为矢量图（位图公式无法识别）。信号2：表格结构完整
打开.md文件，查找|---|分隔线。若表格被拆成多段文字，说明structeqtable模型未生效，确认magic-pdf.json中"enable": true。信号3：图片命名合理
images/fig-3-2.png比images/image_001.png更可信。前者表明MinerU识别出了图注（Figure 3.2），后者只是简单编号。
4.3 性能调优：平衡速度与质量的2个开关
在magic-pdf.json中调整以下两项，可显著改变体验：
"layout-model"：默认yolo，对复杂版式更准；若追求速度，可改为"paddle"（轻量版，精度略降）"ocr-engine"：默认ppocr，中文识别强；若处理英文文献居多，可设为"easyocr"（英文更稳）
修改后无需重启，下次运行自动生效。
5. 总结：让PDF真正成为你的知识资产
MinerU 2.5-1.2B的价值，不在于它能“把PDF变成文字”，而在于它能把PDF变成可搜索、可链接、可编程、可迭代的知识单元。当你用-p指向一份PDF，用-o为其开辟专属空间，用--task doc赋予它结构灵魂，你实际上是在为数字世界构建一座座微型知识仓库。
记住这三条铁律：
-p是起点，确保路径真实存在；-o是容器，它定义了你的工作边界；--task是意图，它决定了MinerU以何种智慧来服务你。
从今天开始，别再把PDF当作需要“打开—阅读—关闭”的一次性文件。用三行命令，把它变成你知识图谱中一个活的节点。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
