MinerU命令行参数详解：-p -o --task 使用说明
MinerU命令行参数详解：-p -o --task 使用说明
MinerU 2.5-1.2B 深度学习 PDF 提取镜像
本镜像已深度预装 GLM-4V-9B 模型权重及全套依赖环境，真正实现“开箱即用”。您无需繁琐配置，只需通过简单的三步指令即可在本地快速启动视觉多模态推理，极大地降低了模型部署与体验的门槛。
1. MinerU 是什么：专为复杂 PDF 而生的智能提取工具
MinerU 不是普通 PDF 转文本工具，它是一个面向学术论文、技术文档、财报报告等高难度 PDF 的端到端结构化提取系统。传统工具在遇到多栏排版、嵌套表格、LaTeX 公式、矢量图、页眉页脚混合内容时，往往输出乱码、错位或直接跳过——而 MinerU 2.5-1.2B 通过融合视觉理解（ViT）、布局分析（Layout Detection）和公式识别（LaTeX OCR）三大能力，把 PDF 当作一张“可读图像”来理解，再还原成语义清晰、层级准确、格式保真的 Markdown。
你拿到的这个镜像，不是半成品，也不是需要自己下载模型的空壳。它已经完整集成：
- 主模型
MinerU2.5-2509-1.2B（25亿参数，专为 PDF 视觉解析优化） - 辅助 OCR 模型
PDF-Extract-Kit-1.0 - LaTeX 公式专用识别模块
- 表格结构解析器
structeqtable - 所有底层依赖（CUDA 12.1、PyTorch 2.3、magic-pdf[full] 等）
换句话说：你输入一个 PDF，它输出的不只是文字，而是带标题层级、代码块、数学公式块、表格对齐、图片引用路径的、可直接用于知识库构建或 AI 训练的高质量 Markdown。
2. 核心命令行参数实战解析
MinerU 的命令行接口设计极简，但每个参数都承担明确职责。我们不讲抽象定义，直接从你每天最可能用到的三个参数入手：-p、-o、--task。
2.1-p：指定输入 PDF 文件（必填，不可省略）
-p是path的缩写，代表你要处理的 PDF 文件路径。它必须指向一个真实存在的.pdf文件，不支持文件夹或通配符。
mineru -p test.pdf -o ./output --task doc正确用法示例：
-p ./data/report.pdf（相对路径）-p /root/workspace/papers/llm-survey.pdf（绝对路径）-p "paper with space.pdf"（含空格时加英文双引号）
❌ 常见错误：
-p *.pdf（不支持通配符，会报错“no such file”）-p folder/（路径结尾是斜杠，会被识别为目录而非文件）-p nonexistent.pdf（文件不存在，报错并退出）
小技巧：如果你不确定当前路径下有哪些 PDF，可以先运行：
ls -l *.pdf确保目标文件确实存在，再执行mineru命令。
2.2-o：指定输出目录（必填，不可省略）
-o是output的缩写，它定义结果保存的根目录，而不是单个文件名。MinerU 会自动在该目录下创建子文件夹，并按规则组织所有产出物。
mineru -p test.pdf -o ./output --task doc执行后，./output目录内将生成：
output/ ├── test/ ← 以 PDF 文件名命名的主文件夹 │ ├── markdown/ ← 提取的 Markdown 主文件（test.md） │ ├── images/ ← 所有被识别出的图片（含公式截图、图表） │ ├── tables/ ← 表格导出为 PNG 或 CSV（依配置而定） │ └── meta.json ← 提取过程元信息（耗时、页数、模型版本等）正确用法：
-o ./result（推荐：简洁、安全、易清理）-o /tmp/mineru_out（适合临时处理）-o "/home/user/my output"（含空格路径需加引号）
❌ 高危错误：
-o test.md（误以为是输出文件名 → 实际会创建名为test.md的目录，导致结构混乱）-o .（输出到当前目录 → 可能污染工作区，且无法区分不同任务结果）-o /root（输出到系统关键目录 → 权限可能拒绝，或覆盖重要文件）
实用建议：始终使用./xxx形式的相对路径。这样既避免权限问题，又方便你一键删除整个输出目录：rm -rf ./output
2.3--task：选择提取模式（决定“怎么理解”这份 PDF）
--task参数是 MinerU 的“大脑开关”，它告诉模型：你面对的是一份什么类型的文档？不同任务触发完全不同的处理流水线。
目前支持三种核心模式：
| 任务类型 | 参数值 | 适用场景 | 关键行为 |
|---|---|---|---|
| 通用文档 | doc | 学术论文、技术白皮书、产品手册、合同等 | 启用全栈能力：多栏检测 + 表格识别 + 公式 OCR + 图片提取 + 标题层级重建 |
| 纯文本摘要 | text | 快速获取内容概要、做关键词提取、送入 LLM 摘要 | 跳过图像/公式/表格处理，仅做 OCR 文字提取 + 段落合并，速度最快（适合批量初筛） |
| 结构化表格 | table | 财务报表、数据统计表、实验结果表等 | 强化表格区域定位与结构还原，输出 CSV + Markdown 表格 + 原图，弱化正文处理 |
推荐组合示例：
- 处理一篇 IEEE 论文 →
--task doc - 批量扫描 100 份 PDF 获取标题和摘要 →
--task text - 从年报中精准提取“资产负债表” →
--task table
注意：--task不可省略。如果不加，MinerU 会报错提示error: the following arguments are required: --task，不会默认 fallback。
3. 三步实操：从零到生成 Markdown 的完整流程
我们不再罗列命令，而是带你走一遍真实工作流。假设你刚进入镜像，当前路径是/root/workspace。
3.1 第一步：确认环境与示例文件
先检查 MinerU 是否就绪，以及示例文件是否存在：
# 查看当前路径 pwd # 应输出 /root/workspace # 列出当前目录内容 ls -l # 进入 MinerU2.5 目录（镜像已预置） cd ../MinerU2.5 # 再次确认 test.pdf 存在 ls -l test.pdf你将看到类似输出：
-rw-r--r-- 1 root root 1.2M May 20 10:30 test.pdf这表示 1.2MB 的测试 PDF 已就位。
3.2 第二步：执行标准提取命令
运行以下命令（注意空格和大小写）：
mineru -p test.pdf -o ./output --task doc你会看到实时日志滚动：
[INFO] Loading model: MinerU2.5-2509-1.2B... [INFO] Processing page 1/12... [INFO] Detected 3 columns, 2 tables, 5 formulas... [INFO] Saving markdown to ./output/test/markdown/test.md [INFO] Done. Total time: 28.4s成功标志：最后一行出现Done.，且无ERROR或Traceback。
如果卡在某一页超过 60 秒，大概率是显存不足或 PDF 有损坏。此时可尝试：
- 改用
--task text快速验证是否环境正常 - 或检查
magic-pdf.json中device-mode是否为cuda
3.3 第三步：查看与验证输出结果
进入输出目录，查看结构：
ls -R ./output你应该看到：
./output: test/ ./output/test: markdown/ images/ tables/ meta.json ./output/test/markdown: test.md现在打开核心成果：
cat ./output/test/markdown/test.md | head -n 30你会看到类似这样的 Markdown 片段：
# Attention Is All You Need ## Abstract The dominant sequence transduction models are based on complex recurrent or... ### 3.1 Model Architecture We use stacked layers of self-attention and point-wise, fully connected... $$ \text{Attention}(Q,K,V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$  | Layer Type | Count | Parameters | |------------|-------|------------| | Encoder | 6 | 120M | | Decoder | 6 | 120M |验证要点：
- 标题层级（
#、##、###）是否准确反映原文结构？ - 公式是否被正确包裹在
$$...$$中？ - 图片路径是否指向
images/下的真实文件？ - 表格是否为标准 Markdown 表格语法？
如果全部符合，恭喜，你已成功跑通 MinerU 全流程。
4. 进阶技巧：让提取更准、更快、更可控
参数只是起点，真正发挥 MinerU 实力，需要结合场景微调。以下是经过实测验证的实用技巧。
4.1 处理超大 PDF：分页提取 + 合并
单个 PDF 超过 50 页时，显存可能溢出。不要硬扛，用分页策略：
# 提取第 1–20 页 mineru -p test.pdf -o ./output_part1 --task doc --start-page 0 --end-page 20 # 提取第 21–40 页 mineru -p test.pdf -o ./output_part2 --task doc --start-page 20 --end-page 40注：
--start-page和--end-page是 MinerU 内置分页参数，页码从 0 开始计数。
提取完成后，手动合并output_part*/test/markdown/test.md即可。比强行加载整份文档稳定得多。
4.2 控制输出粒度：只保留你需要的部分
默认输出包含图片、表格、公式等全部元素。如果你只需要纯文本（比如喂给 RAG 系统），可关闭冗余项：
编辑/root/magic-pdf.json，将以下字段设为false：
{ "save-images": false, "save-tables": false, "enable-latex-ocr": false }下次运行mineru -p xxx.pdf -o ./out --task doc时，./out/test/images/和./out/test/tables/将不再生成，test.md中的公式也会转为纯文本（如E = mc^2），大幅提升处理速度。
4.3 批量处理多个 PDF：一行命令搞定
把所有 PDF 放进./pdfs/目录，然后用 shell 循环：
mkdir -p ./batch_output for pdf in ./pdfs/*.pdf; do basename=$(basename "$pdf" .pdf) echo "Processing $basename..." mineru -p "$pdf" -o "./batch_output/$basename" --task doc done运行后，每个 PDF 都会在./batch_output/下拥有独立文件夹，互不干扰，便于后续自动化处理。
5. 常见问题排查指南（附错误日志对照）
遇到报错别慌，90% 的问题都能在下面找到答案。
5.1 “CUDA out of memory” 显存不足
典型日志：
RuntimeError: CUDA out of memory. Tried to allocate 2.40 GiB...解决方案：
- 编辑
/root/magic-pdf.json，将"device-mode": "cuda"改为"cpu" - 重新运行命令（CPU 模式速度慢 3–5 倍，但 100% 可用）
5.2 “No module named 'mineru'” 模块未找到
典型日志：
Command 'mineru' not found...解决方案：
- 确认你已执行
cd ../MinerU2.5 - 检查
which mineru是否返回/root/MinerU2.5/bin/mineru - 若无返回，手动激活环境：
conda activate mineru-env
5.3 输出 Markdown 中公式显示为乱码或占位符
典型现象：test.md中出现$$\mathrm{...}$$但渲染失败，或公式被替换成[FORMULA]
解决方案：
- 检查 PDF 原文件：用 Adobe Reader 打开，确认公式是否为矢量图（可选中复制）。若为模糊截图，OCR 无法识别。
- 临时提升 OCR 精度：在
magic-pdf.json中增加："latex-ocr-config": { "dpi": 300, "enable-enhance": true }
5.4 表格识别错位、列数不匹配
典型现象：Markdown 表格中内容错行，或 CSV 表头与数据列数不一致
解决方案：
- 在
magic-pdf.json中，将table-config.model从"structeqtable"临时改为"table-transformer"（后者对非标准表格鲁棒性更强） - 或添加
--table-threshold 0.7参数（提高表格检测置信度阈值）
6. 总结：掌握这三个参数，你就掌握了 MinerU 的钥匙
回顾全文，我们没有堆砌术语，而是聚焦你每天真实会敲的命令：
-p是你的“输入锚点”——它必须精确指向一个真实 PDF 文件；-o是你的“输出管家”——它管理整个结果家族，务必给它一个干净、独立的目录；--task是你的“模式旋钮”——doc、text、table三档，对应三种截然不同的理解逻辑。
你不需要懂 ViT 是什么，也不需要调参。MinerU 2.5-1.2B 镜像的价值，正在于把复杂的多模态推理封装成一条命令。今天你用mineru -p test.pdf -o ./output --task doc跑通了；明天你就能用同样逻辑，批量处理 100 份技术文档，构建专属知识库；后天，你甚至可以把这条命令嵌入 Python 脚本，做成自动化 PDF 处理服务。
真正的生产力，从来不是参数越多越好，而是用最少的输入，获得最可靠的输出。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。