MinerU 系列教程 附录：速查手册与参考索引

MinerU 系列教程 附录篇本附录汇集了 MinerU v3.0.9 日常开发和运维中最常查阅的四类参考信息CLI 命令速查、环境变量配置、后端选择决策矩阵以及项目核心文件索引。你可以把它当作一份随手翻的工具手册在遇到具体问题时快速定位答案。附录 AMinerU CLI 命令速查表MinerU 通过pyproject.toml中的[project.scripts]注册了8 个命令行入口覆盖从单文件解析到集群化生产部署的全部场景。安装完成后这些命令即可在终端中直接使用。A.1 命令总览命令入口模块一句话功能minerumineru.cli.client:main主 CLI 工具解析文档的日常入口mineru-apimineru.cli.fast_api:main启动 FastAPI 服务提供 REST APImineru-routermineru.cli.router:main启动路由/调度服务管理多 Workermineru-gradiomineru.cli.gradio_app:main启动 Gradio WebUI浏览器可视化操作mineru-models-downloadmineru.cli.models_download:download_models交互式下载模型文件mineru-vllm-servermineru.cli.vlm_server:vllm_server启动 vLLM 推理服务mineru-lmdeploy-servermineru.cli.vlm_server:lmdeploy_server启动 LMDeploy 推理服务mineru-openai-servermineru.cli.vlm_server:openai_server启动 OpenAI 兼容推理服务A.2mineru— 主 CLI 工具这是你接触最多的命令。它接收一个文件或目录路径输出解析后的 Markdown、JSON 和可视化 PDF。基本语法mineru-p输入路径-o输出目录[选项...]完整参数表参数短选项类型默认值说明--path-pPATH必填输入文件或目录支持 PDF、PNG、JPG、JPEG--output-oPATH必填输出目录--api-url—STRINGNone指定远程 FastAPI 地址省略时自动启动本地临时服务--method-mCHOICEauto解析方法auto自动判断、txt文本提取、ocr强制 OCR--backend-bCHOICEhybrid-auto-engine后端选择详见附录 C--lang-lCHOICEchOCR 语言影响 Pipeline/Hybrid 后端的识别精度--url-uSTRINGNonehttp-client 模式下的远程服务地址--start-sINT0PDF 起始页码从 0 开始--end-eINTNonePDF 结束页码从 0 开始None 表示到最后--formula-fBOOLTrue是否启用公式识别--table-tBOOLTrue是否启用表格识别--version-v——显示版本号并退出语言选项完整列表--lang参数支持以下语言代码语言代码覆盖语言语言代码覆盖语言ch中文含英文korean韩文ch_server中文服务端模型japan日文ch_lite中文轻量模型chinese_cht繁体中文en英文ta泰米尔文te泰卢固文ka卡纳达文th泰文el希腊文latin拉丁语系arabic阿拉伯文east_slavic东斯拉夫语cyrillic西里尔文devanagari天城文——典型用法# 最简单的用法使用默认 hybrid-auto-engine 后端mineru-ppaper.pdf-o./output# 指定 pipeline 后端 英文语言mineru-ppaper.pdf-o./output-bpipeline-len# 解析 PDF 的第 5-10 页禁用公式识别mineru-ppaper.pdf-o./output-s4-e9-ffalse# 连接远程 VLM 服务mineru-ppaper.pdf-o./output-bvlm-http-client-uhttp://192.168.1.100:30000# 指定远程 FastAPI 服务不启动本地临时服务mineru-ppaper.pdf-o./output --api-url http://localhost:8000理解--api-url的作用当你省略--api-url时mineru命令会在后台自动启动一个临时的mineru-api进程来处理解析任务解析完成后自动关闭。如果你已经单独运行了mineru-api可以通过--api-url指向它避免重复启动。A.3mineru-api— FastAPI 服务将 MinerU 的解析能力包装为 REST API 服务支持异步任务提交和结果查询。mineru-api[--host HOST][--port PORT][--enable-vlm-preload]核心特性异步任务模型提交解析任务后返回task_id通过轮询获取状态和结果任务状态流转pending→processing→completed/failed自动清理已完成任务默认保留 24 小时86400 秒每 5 分钟执行一次清理VLM 预加载--enable-vlm-preload在启动时预热 VLM 模型减少首次请求延迟GZip 压缩内置 GZip 中间件自动压缩响应体A.4mineru-router— 路由调度服务面向多 GPU、多节点的生产场景mineru-router充当反向代理和负载均衡器。mineru-router[--host HOST][--port PORT][--upstream-url URL][--local-gpus auto|N]工作模式本地 Worker 管理根据--local-gpus自动检测或手动指定 GPU 数量为每个 GPU 启动独立的mineru-apiWorker远程上游聚合通过--upstream-url聚合多个远程mineru-api节点混合部署同时管理本地 Worker 和远程上游统一对外提供服务健康检查自动监测 Worker 健康状态故障节点自动摘除A.5mineru-gradio— WebUI 界面为不熟悉命令行的用户提供浏览器可视化操作界面底层通过 API 调用mineru-api。mineru-gradio[--port PORT]特性支持 PDF、图片、Office 文档上传实时显示解析进度和并发等待队列兼容 Gradio 5 和 Gradio 6结果在线预览和下载A.6mineru-models-download— 模型下载交互式模型下载工具支持从 HuggingFace 或 ModelScope 下载模型。mineru-models-download[-s{huggingface,modelscope}][-m{pipeline,vlm,all}]参数短选项说明--source-s模型下载源huggingface或modelscope--model_type-m模型类型pipeline、vlm或all如果未指定参数命令会进入交互模式逐步提示你选择下载源和模型类型。Pipeline 模型清单-m pipeline模型用途pp_doclayout_v2版面分析含阅读顺序unimernet_small公式识别UniMERNetpytorch_paddleOCR 引擎检测 识别slanet_plus无线表格识别unet_structure有线表格识别paddle_table_cls表格分类器paddle_orientation_classification图像方向分类pp_formulanet_plus_m公式检测FormulaNet下载完成后工具会自动将模型路径写入~/mineru.json配置文件。A.7mineru-vllm-server/mineru-lmdeploy-server— 推理服务分别启动 vLLM 或 LMDeploy 推理引擎为 VLM/Hybrid 后端的 http-client 模式提供服务端。# 启动 vLLM 推理服务mineru-vllm-server[vLLM 原生参数...]# 启动 LMDeploy 推理服务mineru-lmdeploy-server[LMDeploy 原生参数...]这两个命令是对底层推理引擎的薄封装支持透传各自引擎的原生参数。A.8mineru-openai-server— OpenAI 兼容服务自动选择推理引擎并启动 OpenAI 兼容的 API 服务。mineru-openai-server[-e{auto,vllm,lmdeploy}][引擎原生参数...]--engine选择策略auto默认优先尝试 vLLM不可用时回退到 LMDeployvllm强制使用 vLLMlmdeploy强制使用 LMDeploy附录 B环境变量配置速查表MinerU 使用MINERU_前缀的环境变量来控制运行时行为。这些变量的优先级通常高于配置文件和命令行默认值适合在容器化部署、CI/CD 流水线中使用。B.1 模型与设备配置变量默认值说明MINERU_MODEL_SOURCEhuggingface模型下载源huggingface、modelscope、local使用本地已下载模型MINERU_TOOLS_CONFIG_JSONmineru.json配置文件名位于~/目录下MINERU_DEVICE_MODENone自动检测强制指定设备模式覆盖自动检测逻辑MINERU_VIRTUAL_VRAM_SIZENone自动检测虚拟显存大小整数单位 MB用于覆盖 GPU 显存自动检测结果MINERU_FORMULA_CH_SUPPORTFalse是否启用中文公式识别支持加载中文公式模型B.2 解析功能开关变量默认值说明MINERU_FORMULA_ENABLENone使用 CLI 参数覆盖公式识别开关true/falseMINERU_TABLE_ENABLENone使用 CLI 参数覆盖表格识别开关true/falseMINERU_OCR_DET_MASK_INLINE_FORMULA_ENABLENoneOCR 检测时是否遮罩行内公式区域MINERU_TABLE_MERGE_ENABLEtrue是否启用跨页表格合并MINERU_VLM_FORMULA_ENABLETrueVLM/Hybrid 后端的公式识别开关MINERU_VLM_TABLE_ENABLETrueVLM/Hybrid 后端的表格识别开关MINERU_PDF_CLASSIFY_STRATEGYNonePDF 分类策略文本型/扫描型判断B.3 Hybrid 后端专属变量默认值说明MINERU_FORCE_VLM_OCR_ENABLE0强制启用 VLM OCR1/true/yesMINERU_HYBRID_FORCE_PIPELINE_ENABLE0强制使用 Pipeline禁用 VLM OCR1/true/yesMINERU_HYBRID_BATCH_RATIONone自动Hybrid 批处理比例整数C/S 分离部署时建议手动指定MINERU_HYBRID_BATCH_RATIO参考值源码注释中给出了显存与 batch ratio 的对应关系——显存越大可设置越大的 batch ratio 以提升吞吐。典型值如44GB、88GB、1616GB。B.4 推理引擎配置变量默认值说明MINERU_LMDEPLOY_DEVICE自动LMDeploy 设备类型特殊值maca沐曦加速卡MINERU_LMDEPLOY_BACKEND自动LMDeploy 后端引擎选择MINERU_VLLM_DEVICE自动vLLM 设备类型B.5 处理窗口与并发变量默认值说明MINERU_PROCESSING_WINDOW_SIZE64处理窗口大小控制单次批量处理的页数上限MINERU_API_MAX_CONCURRENT_REQUESTS3API 服务最大并发请求数B.6 API 服务配置变量默认值说明MINERU_API_OUTPUT_ROOT./outputAPI 服务的输出根目录MINERU_API_TASK_RETENTION_SECONDS8640024h已完成任务的保留时间秒MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS3005min任务清理检查间隔秒MINERU_API_ENABLE_VLM_PRELOAD0启动时是否预加载 VLM 模型MINERU_API_ENABLE_FASTAPI_DOCS1启用是否启用 FastAPI 自动文档/docs、/openapi.jsonMINERU_API_DISABLE_ACCESS_LOG0是否禁用 HTTP 访问日志MINERU_API_SHUTDOWN_ON_STDIN_EOF0stdin 关闭时是否自动退出用于被父进程管理的场景MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS—CLI 启动本地临时 API 服务的超时时间B.7 路由服务配置变量默认值说明MINERU_ROUTER_UPSTREAM_URLS_JSONNone上游服务 URL 列表JSON 数组格式MINERU_ROUTER_LOCAL_GPUSauto本地 GPU 数量auto自动检测或指定数字MINERU_ROUTER_WORKER_HOST127.0.0.1Worker 绑定的主机地址MINERU_ROUTER_ENABLE_VLM_PRELOAD0Worker 启动时是否预加载 VLM 模型MINERU_ROUTER_WORKER_ARGS_JSONNoneWorker 额外启动参数JSON 数组格式B.8 PDF 渲染与日志变量默认值说明MINERU_LOG_LEVELINFO日志级别DEBUG、INFO、WARNING、ERRORMINERU_PDF_RENDER_TIMEOUTNonePDF 渲染超时时间秒MINERU_PDF_RENDER_THREADSNonePDF 渲染线程数MINERU_OFFICE_STYLE_RENDER_MODENoneOffice 文档样式渲染模式B.9 性能调优与调试变量默认值说明MINERU_DONOT_CLEAN_MEMNone设置后禁用自动内存清理文档 10 页时默认清理MINERU_INTRA_OP_NUM_THREADSNoneONNX Runtime 算子内部线程数MINERU_INTER_OP_NUM_THREADSNoneONNX Runtime 算子间并行线程数MINERU_SEAL_OCR_DEBUG禁用启用印章 OCR 调试模式MINERU_SEAL_OCR_DEBUG_DIRNone印章 OCR 调试输出目录B.10 环境变量使用示例以下是几个典型的环境变量配置场景场景 1使用 ModelScope 下载模型国内加速exportMINERU_MODEL_SOURCEmodelscope mineru-models-download-mall场景 2Docker 容器化部署 API 服务dockerrun-eMINERU_API_MAX_CONCURRENT_REQUESTS5\-eMINERU_API_OUTPUT_ROOT/data/output\-eMINERU_API_ENABLE_VLM_PRELOAD1\-eMINERU_LOG_LEVELWARNING\-p8000:8000 mineru:latest\mineru-api--host0.0.0.0--port8000场景 3Hybrid 后端 C/S 分离部署# 服务端GPU 机器mineru-openai-server-evllm# 客户端轻量机器手动指定 batch ratioexportMINERU_HYBRID_BATCH_RATIO4exportMINERU_FORCE_VLM_OCR_ENABLE0mineru-pdocs/-o./output-bhybrid-http-client-uhttp://gpu-server:30000场景 4调试 ONNX Runtime 表格识别性能exportMINERU_INTRA_OP_NUM_THREADS4exportMINERU_INTER_OP_NUM_THREADS2exportMINERU_LOG_LEVELDEBUG mineru-ptable-heavy.pdf-o./output-bpipeline附录 C后端选择决策矩阵MinerU v3.0.9 提供 5 种 CLI 后端选项加上 Office 文档的自动识别路径共 6 种实际的解析路径。选择合适的后端是获得最佳解析效果的关键。C.1 后端总览后端CLI 值精度指标本质Pipelinepipeline86传统 OCR 流水线版面分析 → OCR → 公式 → 表格VLM Auto Enginevlm-auto-engine90本地 VLM 端到端解析VLM HTTP Clientvlm-http-client90远程 VLM 服务 本地后处理Hybrid Auto Enginehybrid-auto-engine90VLM 版面检测 Pipeline OCR/MFRHybrid HTTP Clienthybrid-http-client90远程 VLM 本地 Pipeline 组件Office自动——直接转换 DOCX/PPTX/XLSX无需模型C.2 场景决策矩阵面对一个具体的文档解析需求按照以下决策路径选择后端场景推荐后端原因纯 CPU 环境无 GPUpipeline唯一支持纯 CPU 推理的后端中英文文档 高精度需求hybrid-auto-engineVLM 负责版面检测Pipeline 负责 OCR/MFR精度与速度兼顾资源受限 有远程 VLMhybrid-http-client本地仅需约 2GB 显存运行 Pipeline 组件DOCX/PPTX/XLSX 文档自动选择 Office 路径直接结构化转换速度快数十倍无 VLM 幻觉风险端到端高精度 充足显存vlm-auto-engine单模型完成所有任务最高精度多语言文档非中英pipeline支持 109 种语言的 OCR 识别大规模生产环境mineru-router 多后端负载均衡 高吞吐 多 GPU 调度仅有远程 VLM 服务vlm-http-client本地无需 GPU所有计算在远程完成C.3 硬件需求对比维度pipeline*-auto-engine*-http-clientGPU 是否必须否是否hybrid 需约 2GB最低显存—8GB2GB / 0GB内存建议16GB16GB16GB磁盘空间20GB模型20GB模型2GB仅 Pipeline 模型网络依赖否否是连接远程服务C.4 Hybrid 决策算法当你选择hybrid-auto-engine或hybrid-http-client时MinerU 内部通过_should_enable_vlm_ocr()函数决定每个页面是使用 VLM OCR 还是回退到 Pipeline OCR条件判断优先级从高到低 1. MINERU_FORCE_VLM_OCR_ENABLE1 → 强制启用 VLM OCR 2. MINERU_HYBRID_FORCE_PIPELINE_ENABLE1 → 强制使用 Pipeline 3. 同时满足以下条件才启用 VLM OCR - ocr_enable True启用了 OCR - language ∈ {ch, en}语言为中文或英文 - inline_formula_enable True启用了行内公式识别这意味着对于非中英文文档Hybrid 后端会自动回退到 Pipeline OCR因为当前 VLM 对多语言场景的支持尚不如传统 OCR 管线成熟。C.5 后端选择决策流程图输入文档 │ ├── DOCX/PPTX/XLSX ──是──→ Office 路径无需模型直接转换 │ ├── 有 GPU 且显存 8GB │ │ │ ├── 是 → 需要最高精度 │ │ ├── 是 → vlm-auto-engine │ │ └── 否 → hybrid-auto-engine默认推荐 │ │ │ └── 否 → 有远程 VLM 服务 │ ├── 是 → hybrid-http-client本地需约 2GB 显存 │ │ 或 vlm-http-client本地无需 GPU │ └── 否 → pipeline纯 CPU 可用 │ └── 多语言文档非中英 ──是──→ pipeline109 种语言支持C.6 性能参考以下是不同后端在典型硬件上的性能参考解析含表格和公式的学术论文后端硬件配置单页耗时参考说明pipelineCPU only较慢适合小批量或对延迟不敏感的场景pipelineNVIDIA GPU 4GB中等GPU 加速版面分析和 OCRhybrid-auto-engineNVIDIA GPU 8GB较快VLM Pipeline 协同精度与速度平衡vlm-auto-engineNVIDIA GPU 8GB中等偏快端到端 VLM精度最高*-http-client客户端 CPU取决于网络和服务端计算卸载到远程注意实际性能受文档复杂度、页面数量、GPU 型号、网络延迟等多种因素影响以上仅为定性参考。附录 D项目核心文件索引MinerU 的代码库规模较大以下索引列出了最核心的源码文件帮助你在需要深入了解某个模块时快速定位入口。D.1 后端主入口文件路径核心功能教程关联mineru/backend/pipeline/pipeline_analyze.pyPipeline 后端主入口doc_analyze函数第 6、8 课mineru/backend/pipeline/batch_analyze.py批量推理引擎OCR/表格/公式的批处理调度第 8、27 课mineru/backend/pipeline/model_init.pyPipeline 模型初始化Singleton Factory 模式第 7、26 课mineru/backend/pipeline/para_split.py段落拆分与合并算法第 11、27 课mineru/backend/vlm/vlm_analyze.pyVLM 后端主入口6 种推理引擎适配第 14、15 课mineru/backend/hybrid/hybrid_analyze.pyHybrid 后端主入口VLM Pipeline 协同第 16 课mineru/backend/office/docx_analyze.pyOffice 后端主入口DOCX 直接转换第 17 课D.2 模型实现文件路径核心功能教程关联mineru/model/layout/pp_doclayoutv2.pyPP-DocLayoutV2 版面分析模型含阅读顺序第 9、27 课mineru/model/ocr/pytorch_paddle.pyOCR 引擎检测DBNet 识别CRNN第 10 课mineru/model/table/rec/slanet_plus/main.pySLANet 无线表格识别第 12 课mineru/model/table/rec/unet_table/main.pyUNet 有线表格识别第 12 课mineru/model/mfr/utils.py公式识别工具LaTeX 后处理、动态 batch 分组第 13、27 课mineru/model/mfr/unimernet/Unimernet.pyUniMERNet 公式识别模型第 13 课mineru/model/docx/docx_converter.pyDOCX 结构化转换器第 17 课D.3 CLI 与服务文件路径核心功能教程关联mineru/cli/client.py主 CLI 客户端参数解析、任务编排、进度渲染第 2、26 课mineru/cli/fast_api.pyFastAPI REST 服务任务管理、异步解析第 18 课mineru/cli/router.py路由服务负载均衡、Worker 管理第 25 课mineru/cli/gradio_app.pyGradio WebUI浏览器可视化操作第 18 课mineru/cli/common.py公共工具后端设置、文件类型判断第 6 课mineru/cli/vlm_server.pyVLM 推理服务入口vLLM/LMDeploy/OpenAI第 24 课mineru/cli/models_download.py模型下载工具第 2 课mineru/cli/api_client.pyAPI 客户端本地临时服务管理第 18 课D.4 数据抽象与工具文件路径核心功能教程关联mineru/data/data_reader_writer/base.py数据读写抽象基类DataReader/DataWriter第 20、26 课mineru/data/data_reader_writer/filebase.py文件系统读写实现第 20 课mineru/data/data_reader_writer/s3.pyS3 对象存储读写第 20 课mineru/data/data_reader_writer/multi_bucket_s3.py多桶 S3 读写自动路由第 20 课mineru/utils/config_reader.py配置读取设备检测、功能开关、环境变量解析第 21 课mineru/utils/engine_utils.py推理引擎选择平台感知的 VLM 引擎策略第 15、26 课mineru/utils/model_utils.py模型工具显存检测、batch size 计算第 7 课mineru/utils/pdf_classify.pyPDF 分类文本型 vs 扫描型判断第 6 课D.5 配置文件文件路径核心功能pyproject.toml项目元数据、依赖声明、CLI 入口注册、可选依赖组~/mineru.json用户配置模型目录、设备模式等运行时配置mineru/version.py版本号定义D.6 可选依赖组速查pyproject.toml中定义了多个可选依赖组安装时通过mineru[组名]指定依赖组用途典型安装命令core最小核心依赖pip install mineru[core]pipelinePipeline 后端全部依赖pip install mineru[pipeline]vlmVLM 通用依赖Transformerspip install mineru[vlm]vllmvLLM 推理引擎pip install mineru[vllm]lmdeployLMDeploy 推理引擎pip install mineru[lmdeploy]mlxMLX 推理引擎macOS Apple Siliconpip install mineru[mlx]gradioGradio WebUI 依赖pip install mineru[gradio]all全部依赖推荐pip install mineru[all]附录使用建议建议将本附录加入书签或收藏。在日常开发中附录 A 和 B 是最常翻阅的部分——当你忘记某个参数的写法或某个环境变量的名称时直接在这里查找比翻阅源码快得多。附录 C 的决策矩阵适合在项目初期做技术选型时参考附录 D 则是你深入源码阅读时的导航地图。