MinerU 系列教程 第三课：多场景使用指南 -- CLI 参数详解与批量处理

MinerU 系列教程 第三篇本篇教程作为模块一基础入门与架构概览的第三课全面剖析mineruCLI 的完整参数体系。上一课我们完成了安装并成功运行了第一次解析本课将深入每个参数的含义与使用场景掌握批量处理、分页解析、语言选择等高级用法并了解已知限制让你在各种实际场景中游刃有余。学习目标完成本课学习后你将能够掌握mineruCLI 的全部参数及其组合用法理解后端选择-b与解析方法-m的配合逻辑正确使用语言选项-l提升 OCR 精度使用分页解析-s/-e处理大文档控制公式和表格识别的开关-f/-t了解目录输入的批量处理机制与任务规划策略熟悉 MinerU 支持的所有文件类型与自动识别逻辑知晓当前版本的已知限制与常见问题一、CLI 完整参数详解1.1 参数一览表以下是mineruCLI 的全部参数参数长参数类型默认值说明-p--path路径必填输入文件或目录路径-o--output路径必填输出目录-b--backend选择hybrid-auto-engine解析后端-m--method选择auto解析方法txt/ocr/auto-l--lang选择chOCR 语言-u--url字符串无http-client 模式的远程服务地址-s--start整数0起始页码从 0 开始-e--end整数无结束页码从 0 开始-f--formula布尔True是否启用公式识别-t--table布尔True是否启用表格识别--api-url字符串无远程 mineru-api 服务地址-v--version显示版本号接下来逐一深入解析每个参数。1.2-b / --backend后端选择这是最核心的参数决定了 MinerU 使用哪套引擎来解析文档。mineru-pinput.pdf-ooutput/-bbackend可选值共 5 个后端特点适用场景pipeline兼容性好纯 CPU 可运行无幻觉通用场景、资源受限环境hybrid-auto-engine高精度 低幻觉本地 GPU 推理有 GPU8GB追求精度与可靠性vlm-auto-engine最高精度本地 GPU 推理有 GPU8GB复杂版面需求hybrid-http-client高精度本地需少量计算 远程 VLM本地 GPU 不足但有远程推理服务vlm-http-client高精度纯远程推理仅有 CPU 网络连接默认值为hybrid-auto-engine——这是 MinerU 推荐的次世代高精度方案。选择决策树你有 GPU 且显存 8GB 吗? ├── 是 → 对精度要求极高? │ ├── 是 → vlm-auto-engine │ └── 否 → hybrid-auto-engine默认推荐 └── 否 → 有可用的远程 VLM 推理服务吗? ├── 是 → 本地有 GPU? │ ├── 是 → hybrid-http-client │ └── 否 → vlm-http-client └── 否 → pipelinehttp-client 模式需要额外指定-u参数# vlm-http-client纯远程推理mineru-pinput.pdf-ooutput/-bvlm-http-client-uhttp://192.168.1.100:30000# hybrid-http-client本地 pipeline 远程 VLMmineru-pinput.pdf-ooutput/-bhybrid-http-client-uhttp://192.168.1.100:300001.3-m / --method解析方法解析方法控制 MinerU 如何处理 PDF 中的文本内容。mineru-pinput.pdf-ooutput/-mmethod方法说明auto默认值。自动判断 PDF 类型如果是文本型 PDF 则使用txt方法如果是扫描型/乱码 PDF 则使用ocr方法txt强制使用文本提取方法直接从 PDF 中提取原生文本ocr强制使用 OCR 方法将 PDF 页面渲染为图像后进行 OCR 识别适用范围-m参数仅在pipeline和hybrid-*后端下生效。vlm-*后端通过视觉语言模型直接端到端处理不区分 txt/ocr。何时需要手动指定方法确定是扫描件用-m ocr跳过自动检测直接走 OCR 流程确定是文本型 PDF用-m txt跳过自动检测直接提取原生文本速度更快乱码 PDF某些 PDF 虽然有内嵌文本但字体编码异常导致乱码用-m ocr强制 OCR# 扫描件 PDF强制 OCRmineru-pscanned_doc.pdf-ooutput/-bpipeline-mocr# 文本型 PDF直接文本提取mineru-ptext_doc.pdf-ooutput/-bpipeline-mtxt1.4-l / --lang语言选择语言参数告诉 OCR 引擎文档使用的语言以提升识别精度。mineru-pinput.pdf-ooutput/-llangMinerU 支持 16 个语言/语系选项选项覆盖语言ch中文 英文默认值适合大多数中英文文档ch_server中文服务端模式ch_lite中文轻量模式en英文korean韩文japan日文chinese_cht繁体中文ta泰米尔文te泰卢固文ka卡纳达文th泰文el希腊文latin拉丁字母语系法文、德文、西班牙文、意大利文等arabic阿拉伯文east_slavic东斯拉夫语系俄文、乌克兰文、白俄罗斯文等cyrillic西里尔字母语系devanagari天城文印地文等适用范围-l参数仅在pipeline和hybrid-*后端下生效。vlm-*后端由视觉语言模型自动处理多语言。实操示例# 英文论文mineru-ppaper_en.pdf-ooutput/-bpipeline-len# 日文文档mineru-pdoc_jp.pdf-ooutput/-bpipeline-ljapan# 法文/德文等拉丁字母文档mineru-pdoc_fr.pdf-ooutput/-bpipeline-llatin# 阿拉伯文文档mineru-pdoc_ar.pdf-ooutput/-bpipeline-larabic1.5-s / -e分页解析当只需要解析 PDF 的部分页面时可以使用起始页和结束页参数。页码从0开始计数。# 仅解析第 1 页到第 10 页页码 0~9mineru-plarge_doc.pdf-ooutput/-s0-e9# 从第 50 页开始解析到末尾mineru-plarge_doc.pdf-ooutput/-s49# 仅解析第 5 页mineru-plarge_doc.pdf-ooutput/-s4-e4边界处理规则源自get_end_page_id()逻辑如果-e未指定或为负数自动取 PDF 总页数 - 1即解析到最后一页如果-e超过 PDF 总页数自动裁剪到最后一页如果-s -e会报错提示页面范围为空注意分页参数仅对 PDF 文件有效图片和 Office 文档始终作为整体处理effective_pages 1。1.6-f / -t公式与表格识别开关MinerU 默认开启公式识别和表格识别但在某些场景下你可能希望关闭它们以提升速度。# 关闭公式识别加速处理纯文字文档mineru-pinput.pdf-ooutput/-fFalse# 关闭表格识别mineru-pinput.pdf-ooutput/-tFalse# 同时关闭公式和表格识别最快速度mineru-pinput.pdf-ooutput/-fFalse-tFalse参数默认值关闭后的影响-f / --formulaTrue公式区域将作为普通图片输出不转为 LaTeX-t / --tableTrue表格区域将作为普通图片输出不转为 HTML1.7--api-url连接远程 mineru-api在 MinerU 3.0 的架构中mineruCLI 实际上是mineru-api的编排客户端。默认情况下CLI 会自动启动一个本地临时mineru-api服务。但如果你已经部署了mineru-api或mineru-router可以直接连接# 连接远程 mineru-api 服务mineru-pinput.pdf-ooutput/ --api-url http://192.168.1.100:8000# 连接 mineru-routermineru-pinput.pdf-ooutput/ --api-url http://192.168.1.100:8002--api-url与-u / --url的区别参数连接目标用途--api-urlmineru-api / mineru-router将整个解析任务交给远程服务处理-u / --urlOpenAI 兼容的 VLM 推理服务仅在*-http-client后端下使用本地仍需部分处理二、参数组合实战理解单个参数后让我们看看在实际场景中如何组合使用它们。2.1 场景速查表场景推荐命令通用中英文 PDF有 GPUmineru -p doc.pdf -o out/通用中英文 PDF纯 CPUmineru -p doc.pdf -o out/ -b pipeline英文学术论文高精度mineru -p paper.pdf -o out/ -b vlm-auto-engine -l en日文扫描件mineru -p scan.pdf -o out/ -b pipeline -m ocr -l japan阿拉伯文文档mineru -p ar.pdf -o out/ -b pipeline -l arabic大文档只看前 20 页mineru -p big.pdf -o out/ -s 0 -e 19纯文字 PDF 快速提取mineru -p text.pdf -o out/ -b pipeline -m txt -f False -t False远程 VLM 服务解析mineru -p doc.pdf -o out/ -b vlm-http-client -u http://server:30000Word 文档自动 Office 后端mineru -p report.docx -o out/批量解析一个目录mineru -p docs_folder/ -o out/连接已部署的 API 服务mineru -p doc.pdf -o out/ --api-url http://server:80002.2 参数的后端适用性并非所有参数在所有后端下都有效以下是适用性矩阵参数pipelinehybrid-*vlm-*-m(method)生效生效忽略-l(lang)生效生效忽略-u(url)不适用http-client 必填http-client 必填-s / -e(分页)生效生效生效-f(formula)生效生效生效-t(table)生效生效生效三、批量处理目录输入与任务规划当你有大量文档需要处理时MinerU 提供了便捷的目录级批量解析能力。3.1 目录输入将-p指向一个目录MinerU 会自动扫描目录中的所有支持文件mineru-p/path/to/documents/-o/path/to/output/-bpipeline扫描规则仅扫描目录的第一层不递归子目录按文件名排序后依次处理自动过滤不支持的文件类型如果没有找到任何支持的文件会报错退出3.2 任务规划策略MinerU 不是简单地逐个文件处理而是通过任务规划来优化批量解析的效率。规划策略因后端而异Pipeline 后端——装箱式批量化Pipeline 后端采用类似装箱问题Bin Packing的策略将多个小文档打包成一个批次规划规则 1. 按页数从大到小排序文档 2. 如果文档页数 处理窗口大小默认 64 页独占一个批次 3. 否则尝试放入已有批次中选择当前页数最少的批次 4. 如果放不进任何已有批次创建新批次示例假设处理窗口大小为 64 页有以下文档doc_A.pdf: 100 页 → batch#1 [doc_A] (100 页独占) doc_B.pdf: 30 页 → batch#2 [doc_B doc_D doc_E] (30201060 页) doc_C.pdf: 50 页 → batch#3 [doc_C] (50 页) doc_D.pdf: 20 页 → (放入 batch#2) doc_E.pdf: 10 页 → (放入 batch#2)这种策略最大化了每个批次的 GPU 利用率显著提升了批量处理吞吐量。VLM / Hybrid 后端——逐文档处理VLM 和 Hybrid 后端对每个文档创建独立的任务不进行合并每个文档 一个独立任务3.3 并发执行任务规划完成后MinerU 会根据服务端的最大并发数max_concurrent_requests默认 3并行执行多个任务。实际并发数取服务端配置与任务数的较小值actual_concurrency min(max_concurrent_requests, task_count)3.4 重名处理当目录中存在文件名冲突例如doc.pdf和doc.PDFMinerU 会自动为重复的文件名添加数字后缀doc.pdf → doc doc.PDF → doc_2 doc(1).pdf → doc(1)四、支持的文件类型MinerU 使用 MagikaGoogle 开源的文件类型检测库进行智能文件类型识别不仅依赖文件扩展名还会分析文件的实际内容。4.1 完整文件类型表类别文件类型后缀标识后端处理方式PDFPDF 文档pdfpipeline / vlm / hybrid 后端图片PNGpng转为 PDF 后按 PDF 流程处理JPEGjpeg/jpg同上JPEG 2000jp2同上WebPwebp同上GIFgif同上BMPbmp同上TIFFtiff同上OfficeWord 文档docxOffice 后端原生解析PowerPointpptxOffice 后端原生解析ExcelxlsxOffice 后端原生解析4.2 文件类型识别逻辑MinerU 通过guess_suffix_by_path()函数进行文件类型识别文件输入 │ ▼ Magika 库分析文件内容 │ ▼ 返回识别结果如 pdf、png、docx 等 │ ▼ 特殊处理如果 Magika 识别为 ai 或 html 但文件扩展名为 .pdf 且文件头是 %PDF → 修正为 pdf │ ▼ 对比 pdf_suffixes image_suffixes office_suffixes │ ├── 匹配 → 加入处理队列 └── 不匹配 → 跳过4.3 图片文件的处理对于图片文件PNG、JPEG 等MinerU 会先调用images_bytes_to_pdf_bytes()将图片转换为 PDF 格式然后走标准的 PDF 解析流程。因此图片文件的effective_pages始终为 1。4.4 Office 文件的处理DOCX、PPTX、XLSX 文件由 Office 后端直接原生解析无需转为 PDF。这带来两个优势速度比先转 PDF 再解析快数十倍无幻觉直接从 OOXML 结构中提取内容不会产生 OCR 或 VLM 的识别误差当输入为 DOCX/PPTX/XLSX 时无论-b指定了什么后端MinerU 都会自动切换到 Office 后端。五、常见问题与已知限制5.1 已知限制MinerU 在以下场景中可能表现不够理想限制说明极端复杂版面阅读顺序基于模型排序在极端复杂的排版下可能出现部分区域乱序竖排文字对竖排文字的支持较为有限特殊列表目录和列表通过规则识别少数不常见的列表形式可能无法识别代码块代码块在 pipeline 后端的 layout 模型中尚未完全支持特殊内容漫画书、艺术图册、小学教材、习题尚不能很好解析复杂表格表格识别在复杂表格上可能出现行/列识别错误小语种 OCR小语种 PDF 上 OCR 识别可能出现字符不准确的情况如阿拉伯文易混淆字符部分公式某些公式可能无法在 Markdown 中正确渲染5.2 常见问题排查Q1首次运行非常慢怎么回事首次运行时 MinerU 会自动下载模型文件总计约数 GB下载完成后会缓存到本地后续运行将直接加载。建议提前使用mineru-models-download下载模型。Q2报错提示No supported documents found检查输入路径中是否存在 MinerU 支持的文件类型。MinerU 使用 Magika 做内容检测而非仅看扩展名如果文件损坏或格式不符也可能被跳过。Q3GPU 显存不足CUDA OOM切换到pipeline后端最低仅需 4GB 显存或使用纯 CPU使用*-http-client模式将 VLM 推理卸载到远程服务减小处理窗口大小设置环境变量MINERU_PROCESSING_WINDOW_SIZE32Q4hybrid 后端报错缺少依赖hybrid-*后端需要本地安装 pipeline 依赖包括torch。确保安装了mineru[pipeline]或mineru[core]。如果只想轻量使用远程服务请切换到vlm-http-client。Q5解析结果中文乱码可能是 PDF 内部字体编码异常。尝试使用-m ocr强制 OCR 识别绕过原生文本提取。Q6如何加速批量处理增加并发数通过环境变量MINERU_API_MAX_CONCURRENT_REQUESTS5提升并发使用mineru-router部署多 GPU Worker 进行负载均衡对于 pipeline 后端文档会自动按装箱算法合并批次无需额外配置Q7--api-url和-u可以同时使用吗可以。--api-url指向 mineru-api 服务而-u指向 VLM 推理服务。当同时使用时解析任务由远程 mineru-api 执行VLM 推理由-u指向的服务处理。但通常如果 mineru-api 服务已配置好后端无需额外指定-u。5.3 获取更多帮助官方 FAQ 文档https://opendatalab.github.io/MinerU/zh/faq/DeepWiki AI 助手https://deepwiki.com/opendatalab/MinerUDiscord 社区微信社区六、源码导读CLI 编排核心逻辑本课的源码导读聚焦于mineru/cli/client.py这是mineruCLI 命令的入口和核心编排逻辑所在。6.1 文件定位mineru/cli/client.py ← CLI 主入口本课重点 mineru/cli/common.py ← 文件类型定义、依赖检查等公共逻辑 mineru/cli/api_client.py ← mineru-api 交互客户端 mineru/cli/output_paths.py ← 输出路径构建6.2 核心数据结构client.py定义了两个关键数据类dataclass(frozenTrue)classInputDocument:path:Path# 文件路径suffix:str# 文件类型pdf/png/docx 等stem:str# 文件名不含扩展名effective_pages:int# 有效页数order:int# 在输入列表中的序号dataclassclassPlannedTask:index:int# 任务序号documents:list[InputDocument]# 包含的文档列表total_pages:int# 总页数InputDocument代表一个待处理的文档PlannedTask代表一个计划执行的批处理任务可包含多个文档。6.3collect_input_documents()文档收集这个函数负责从输入路径收集所有合法文档defcollect_input_documents(input_path,start_page_id,end_page_id):# 1. 判断输入是文件还是目录ifinput_path.is_dir():documentssorted(input_path.glob(*))# 只扫第一层else:documents[input_path]# 2. 遍历每个文件通过 Magika 识别类型forpathindocuments:suffixguess_suffix_by_path(path)ifsuffixnotinpdf_suffixesimage_suffixesoffice_suffixes:continue# 跳过不支持的文件# 3. 计算有效页数ifsuffixinpdf_suffixes:effective_pagesprobe_pdf_effective_pages(path,start_page_id,end_page_id)else:effective_pages1# 图片和 Office 文档算 1 页# 4. 处理文件名重复normalized_stemsuniquify_task_stems(stems)几个值得注意的设计Magika 内容检测不只看扩展名还分析文件实际内容避免误判PDF 页数探测通过pypdfium2打开 PDF 获取实际页数结合-s/-e计算有效页数文件名去重通过uniquify_task_stems()处理大小写重复等情况添加_2、_3后缀6.4plan_tasks()任务规划任务规划是批量处理的核心根据后端类型选择不同的策略defplan_tasks(documents,backend,processing_window_size):ifbackendpipeline:returnplan_pipeline_tasks(documents,processing_window_size)# 其他后端每个文档一个独立任务return[PlannedTask(indexi,documents[doc],total_pagesdoc.effective_pages)fori,docinenumerate(documents,start1)]plan_pipeline_tasks()的装箱算法defplan_pipeline_tasks(documents,processing_window_size):# 1. 按页数从大到小排序sorted_docssorted(documents,keylambdadoc:(-doc.effective_pages,doc.order))fordocumentinsorted_docs:# 2. 超大文档独占一个批次ifdocument.effective_pagesprocessing_window_size:bins.append(PlannedTask(...))continue# 3. 尝试放入现有批次贪心选最空的candidates[taskfortaskinbinsiftask.total_pagesdocument.effective_pagesprocessing_window_size]ifcandidates:selectedmin(candidates,keylambdat:(t.total_pages,t.index))selected.documents.append(document)continue# 4. 创建新批次bins.append(PlannedTask(...))6.5run_orchestrated_cli()完整执行流程这是 CLI 的核心编排函数将上述环节串联起来main() 解析命令行参数 │ ▼ run_orchestrated_cli() │ ├── 1. 校验参数页码范围、后端依赖 ├── 2. 创建输出目录 ├── 3. collect_input_documents() → 收集文档 │ ├── 4. 启动或连接 API 服务 │ ├── api_url 未指定 → 自动启动本地 mineru-api │ └── api_url 已指定 → 连接远程服务 协商并发数 │ ├── 5. plan_tasks() → 规划批处理任务 ├── 6. build_request_form_data() → 构建请求参数 │ ├── 7. execute_planned_tasks() → 并发执行任务 │ └── 对每个任务 │ ├── submit_task() → 提交到 API │ ├── wait_for_task_result() → 等待完成 │ ├── download_result_zip() → 下载结果 │ ├── safe_extract_zip() → 解压到输出目录 │ └── queue_visualization_jobs() → 异步生成可视化 │ ├── 8. 等待可视化任务完成 └── 9. 清理资源停止本地 API、关闭渲染器6.6 实时任务状态渲染当连接远程--api-url时CLI 会在终端显示实时任务状态。LiveTaskStatusRenderer通过 ANSI 转义序列在终端渲染动态进度条[ ] statusprocessing | task_idabc123 [ ] statuspending | ahead2 | task_iddef456这个渲染器与日志输出互斥协调通过LiveAwareStderrSink确保日志打印不会破坏进度条显示。小结本课我们全面掌握了 MinerU CLI 的多场景使用方法参数体系完整10 个参数覆盖后端选择、解析方法、语言指定、分页范围、功能开关等全部配置维度后端选择有据根据硬件条件和精度需求从 pipeline通用到 hybrid推荐再到 vlm极致精度有清晰的决策路径解析方法灵活auto自动判断、txt直提文本、ocr强制识别三种方法应对不同 PDF 类型批量处理高效目录输入自动扫描pipeline 后端通过装箱算法合并批次多任务并发执行文件类型广泛PDF 7 种图片格式 3 种 Office 格式基于 Magika 的内容检测确保准确识别源码逻辑清晰collect_input_documents()→plan_tasks()→execute_planned_tasks()三阶段流水线架构设计体现了良好的关注点分离掌握了这些使用技巧和内部机制你已经能应对绝大多数文档解析场景。下一课预告第四课多后端架构设计哲学我们将深入 MinerU 的四大后端Pipeline / VLM / Hybrid / Office的内部架构理解统一中间格式 Middle JSON 的设计以及 Magic Model 转换层如何将异构输出标准化为统一的块结构。从使用者视角进入架构师视角开启核心篇的学习。