首页
/ MinerU 快速上手：一条命令解析 PDF 与 Office 文档，以及 FastAPI、WebUI 与多卡路由实战

MinerU 快速上手：一条命令解析 PDF 与 Office 文档，以及 FastAPI、WebUI 与多卡路由实战

2026-09-04 21:27:50作者：韦蓉瑛
MinerU
Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
项目地址：https://gitcode.com/GitHub_Trending/mi/MinerU

MinerU 是一个面向 LLM 工作流的文档解析工具，可将 PDF、图片、DOCX、PPTX、XLSX 等复杂文档转换为 Markdown 与结构化 JSON。本文基于仓库中 docs/en/usage/quick_usage.md 的完整脉络展开：先讲模型源配置，再逐层给出 mineru 命令行、mineru-api 服务、Gradio WebUI、mineru-router 多服务编排与 mineru-openai-server 远程推理五种使用方式，并结合 mineru/cli/client.py、mineru/cli/fast_api.py、mineru/utils/config_reader.py 等源码印证每个参数的真实取值与默认行为，读完即可在本地或远程环境中跑通 MinerU 的全套调用链路。

一、快速配置模型源：MINERU_MODEL_SOURCE

MinerU 默认使用 huggingface 作为模型源。如果受网络限制无法访问 HuggingFace，可以通过环境变量一键切换到 modelscope：

export MINERU_MODEL_SOURCE=modelscope

更完整的模型源策略（auto 探测回退、本地模型路径配置等）参见 模型源文档。从 mineru/utils/config_reader.py 的源码可以看出其优先级与容错逻辑：

  • get_configured_model_source() 支持 huggingface、modelscope 两种固定值；配置为 auto 或缺失时回退到默认值，即先探测 HuggingFace 可达性，不通再回落到 ModelScope，并把解析结果写回 mineru.json 的 model-source 字段，避免后续启动因网络抖动来回切换；
  • 环境变量的优先级高于 mineru.json 中的 model-source，且环境变量不要设置为 auto——想自动选择时直接不设置该变量即可；
  • 设备选择同样有自动探测逻辑：get_device() 会按 cuda → mps → npu → gcu → musa → mlu → sdaa → cpu 的顺序探测可用加速后端，也可用环境变量 MINERU_DEVICE_MODE 强制指定。

注意：命令行工具在 Linux 与 macOS 上会自动尝试 cuda/mps 加速。Windows 用户如需 cuda 加速，需前往 PyTorch 官网按自己的 cuda 版本选择对应命令，单独安装带加速能力的 torch 与 torchvision。

二、命令行快速解析：mineru

MinerU 内置了命令行工具，这是最常用的入口：

mineru -p <input_path> -o <output_path>

参数说明：

  • <input_path>：本地 PDF / 图片 / DOCX / PPTX / XLSX 文件，或包含上述文件的目录；
  • <output_path>：输出目录；
  • 不带 --api-url 时，CLI 会自动拉起一个临时本地 mineru-api 服务，解析完成后退出并回收；
  • 带 --api-url 时，CLI 直接连接一个已存在的本地或远程 FastAPI 服务。

输出文件的完整结构说明参见 输出文件文档。仓库自带了演示文件（demo/pdfs/demo1.pdf 等），可直接跑一条真实命令：

mineru -p demo/pdfs/demo1.pdf -o ./output

2.1 完整参数一览（源码实证）

mineru 命令由 mineru/cli/client.py 中的 click 定义注册（入口见 pyproject.toml 的 mineru = "mineru.cli.client:main"）。除 -p/-o 外，还有以下完整参数集，全部可从 --help 输出验证：

参数 默认值 说明
-p, --path 必填 本地文件路径或目录，支持 pdf、图片、docx、pptx、xlsx
-o, --output 必填 本地输出目录
--api-url None 指定已有 MinerU FastAPI 基地址；缺省时自动启动临时本地 mineru-api
-m, --method auto auto / txt / ocr，仅 pipeline 与 hybrid-* 后端生效
-b, --backend hybrid-engine 可选 pipeline、vlm-engine、vlm-http-client、hybrid-engine、hybrid-http-client
--effort medium Hybrid 解析力度：medium（更快，关闭图片/图表分析）或 high（更高精度，含图片/图表分析），仅 hybrid-* 生效
-l, --lang ch 文档语言提示，提高 OCR 准确率，仅 pipeline 后端生效
-u, --url None *-http-client 后端必填，如 http://127.0.0.1:30000
-s, --start / -e, --end 0 / None 零基页码范围，解析 PDF 的起止页
-f, --formula True 是否启用公式解析
-t, --table True 是否启用表格解析
--image-analysis True VLM 与 hybrid 后端的图片/图表分析；hybrid medium 会自动关闭
--client-side-output-generation False 由客户端基于服务端返回的 middle json、图片与原件在本地重建 markdown 与 content list

几个值得注意的源码细节：

  • 后端默认值定义在 mineru/cli/backend_options.py：DEFAULT_BACKEND = "hybrid-engine"，且旧别名 vlm-auto-engine、hybrid-auto-engine 会被 normalize_backend() 自动映射到新名称，即历史版本的命令可以无感迁移；
  • 从源码结构看（client.py 的 collect_input_documents），输入目录下的文件按后缀识别，PDF 会实际探测有效页数，重名文档 stem 会被自动去重改名并打 warning；pipeline 后端还会按 processing_window_size 把多个文档合并成批次（plan_pipeline_tasks），而其余后端一文档一任务；
  • 公式/表格开关也可被环境变量 MINERU_FORMULA_ENABLE、MINERU_TABLE_ENABLE 覆盖（见 config_reader.py）。

更多参数（含 vLLM/LMDeploy 透传参数）参见 命令行工具使用说明 与 高级命令行参数。

三、FastAPI 服务化调用：mineru-api

mineru-api --host 0.0.0.0 --port 8000

启动后在浏览器访问 http://127.0.0.1:8000/docs 查看交互式 API 文档。核心端点与行为如下（与 mineru/cli/fast_api.py 实现一一对应）：

  • 健康检查 GET /health：返回 protocol_version、processing_window_size、max_concurrent_requests 以及任务统计，CLI 客户端在提交前会先探测该端点；
  • 异步任务提交 POST /tasks：立即返回 task_id，状态流转为 pending → processing → completed/failed；
  • 同步解析 POST /file_parse：内部复用同一套任务管理器，等待任务完成后同步返回最终结果；
  • 任务查询 GET /tasks/{task_id}、GET /tasks/{task_id}/result；
  • 上传目前支持 PDF、图片、DOCX、PPTX、XLSX；
  • API 输出由服务端控制，默认写入 ./output（源码常量 DEFAULT_OUTPUT_ROOT = "./output"，见 fast_api.py#L85-L87，可用 MINERU_API_OUTPUT_ROOT 调整）。

3.1 任务生命周期要点（源码印证）

  • POST /tasks 立即返回 task_id；POST /file_parse 使用同一个任务管理器，只是阻塞等待到任务结束再返回结果；
  • 任务排队时，提交响应与任务状态响应都可能携带 queued_ahead 字段，表示前面还有多少个任务（对应 AsyncParseTask.to_status_payload 中的条件注入）；
  • 任务状态仅存在于单个 mineru-api 进程内存中：服务重启、--reload 或多进程部署都不保留状态；
  • 已完成/失败的任务默认保留 24 小时，随后任务状态与输出目录自动清理，清理后状态与结果端点返回 404。源码中 DEFAULT_TASK_RETENTION_SECONDS = 24 * 60 * 60、DEFAULT_TASK_CLEANUP_INTERVAL_SECONDS = 5 * 60（fast_api.py#L85-L87），可通过环境变量调整：
    • MINERU_API_TASK_RETENTION_SECONDS：保留时长；
    • MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS：清理轮询间隔；
  • 并发受信号量控制，默认值为 3（DEFAULT_MAX_CONCURRENT_REQUESTS，可用 MINERU_API_MAX_CONCURRENT_REQUESTS 调整，macOS 上从源码看会被强制限制为 1，见 create_app）；
  • 使用 --enable-vlm-preload true 可在服务启动阶段预热本地 VLM 模型，避免第一个 VLM/hybrid 请求长时间等待。

3.2 可复制的调用示例

异步任务提交：

curl -X POST http://127.0.0.1:8000/tasks \
  -F "files=@demo/pdfs/demo1.pdf" \
  -F "return_md=true"

同步解析（返回 zip 包并附带原文件）：

curl -X POST http://127.0.0.1:8000/file_parse \
  -F "files=@demo/pdfs/demo1.pdf" \
  -F "return_md=true" \
  -F "response_format_zip=true" \
  -F "return_original_file=true"

轮询任务状态与获取结果：

curl http://127.0.0.1:8000/tasks/<task_id>
curl http://127.0.0.1:8000/tasks/<task_id>/result
curl http://127.0.0.1:8000/health

Python HTTP 异步调用完整示例见仓库内的 demo/demo.py：它演示了「未指定 api_url 时自动拉起临时本地服务 → 提交任务 → 轮询状态（含 queued_ahead 提示）→ 下载结果 zip 并解压」的完整链路，且对 backend、effort、parse_method、server_url、页码范围等参数均有注释说明，是很好的二次开发参考。

四、Gradio WebUI 可视化前端：mineru-gradio

mineru-gradio --server-name 0.0.0.0 --server-port 7860
  • 浏览器访问 http://127.0.0.1:7860 即可使用可视化界面；
  • 不带 --api-url 时，Gradio 会启动一个可复用的本地 mineru-api；带 --api-url 时则复用已有的本地或远程服务；
  • --enable-vlm-preload true 会让 Gradio 在 WebUI 启动阶段拉起本地 mineru-api 并等待 VLM 预热完成；当 --api-url 指向已有服务时该参数被忽略；
  • 目前 WebUI 接受 PDF、图片、DOCX、PPTX、XLSX 上传。

五、多服务 / 多 GPU 编排：mineru-router

mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

mineru-router 是面向高级部署的统一入口层（实现见 mineru/cli/router.py）：

  • 对外暴露与 mineru-api 完全相同的端点集合：/health、/tasks、/file_parse、/tasks/{task_id}、/tasks/{task_id}/result，因此现有客户端无需任何改动即可切换；
  • 重复传 --upstream-url 可聚合多个已存在的 mineru-api 服务；或使用 --local-gpus 按本地 GPU 数量自动拉起 worker（auto 自动探测，none 不拉起）；
  • --enable-vlm-preload true 只对 router 管理的本地 worker 生效，不会预热通过 --upstream-url 传入的远程服务；
  • 定位是多服务、多 GPU、统一入口的编排层；从源码结构看，router 内部实现了上游健康探测、失败计数（连续失败阈值后剔除）与 worker 周期刷新，用于在多实例间做请求分发。

六、http-client / server 分离部署

当 GPU 推理服务与解析客户端不在同一台机器时，可以拆分两端。先启动一个 OpenAI 兼容的推理服务端（需要 vLLM 或 LMDeploy 环境）：

mineru-openai-server --port 30000

该命令支持 --engine auto/vllm/lmdeploy，auto 模式下会优先尝试导入 vllm，失败再尝试 lmdeploy，两者都缺失则报错退出（见 mineru/cli/vlm_server.py）。

然后在另一台终端，让客户端通过 HTTP 连接推理服务：

mineru -p <input_path> -o <output_path> -b hybrid-http-client -u http://127.0.0.1:30000

两种远程后端的依赖差异值得明确：

  • vlm-http-client：轻量远程客户端，本地不需要 torch；
  • hybrid-http-client：需要本地 pipeline 依赖（mineru[pipeline]）与 torch，因为它在本地执行版面分析等 pipeline 步骤，仅把 VLM 推理部分发到远程。

说明：所有官方支持的 vLLM / LMDeploy 参数都可以通过命令行透传给 MinerU，覆盖 mineru、mineru-openai-server、mineru-gradio、mineru-api、mineru-router 五个命令。常用 vLLM/LMDeploy 参数的整理版说明见 高级命令行参数。

七、用配置文件扩展 MinerU 功能

MinerU 开箱即用，同时支持通过用户目录（~）下的 mineru.json 扩展配置。该文件在使用内置模型下载命令 mineru-models-download 时会自动生成；也可以把仓库根目录的 配置文件模板 复制到用户目录并改名为 mineru.json。模板实际内容如下，可对照逐项理解：

{
    "bucket_info": {
        "bucket-name-1": ["ak", "sk", "endpoint"],
        "bucket-name-2": ["ak", "sk", "endpoint"]
    },
    "latex-delimiter-config": {
        "display": { "left": "$$", "right": "$$" },
        "inline":  { "left": "$",  "right": "$" }
    },
    "llm-aided-config": {
        "title_aided": {
            "api_key": "your_api_key",
            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "model": "qwen3.5-plus",
            "enable_thinking": false,
            "enable": false
        }
    },
    "models-dir": { "pipeline": "", "vlm": "" },
    "model-source": "auto",
    "config_version": "1.3.2"
}

主要可配置项说明（读取逻辑均在 mineru/utils/config_reader.py）：

  • latex-delimiter-config：配置 LaTeX 公式定界符，默认行内公式为 $...$、块级公式为 $$...$$（对应模板中的 inline / display 左右定界符），可按需改成其他符号或字符串，get_latex_delimiter_config() 会在配置缺失时返回 None 走默认值；

  • llm-aided-config：配置 LLM 辅助标题层级（title_aided 子段），兼容所有 OpenAI 协议模型，默认指向阿里云百炼的 qwen3-next-80b-a3b-instruct 模型（模板示例值为 qwen3.5-plus）。需要填入自己的 API key 并把 enable 置为 true 才会生效；若你的 API 提供方不支持 enable_thinking 参数，请手动删除该字段，例如把：

    "llm-aided-config": {
   "api_key": "your_api_key",
   "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
   "model": "qwen3-next-80b-a3b-instruct",
   "enable_thinking": false,
   "enable": false
}

    改为：

    "llm-aided-config": {
   "api_key": "your_api_key",
   "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
   "model": "qwen3-next-80b-a3b-instruct",
   "enable": false
}

  • models-dir：指定本地模型存储目录，pipeline 与 vlm 两个后端需分别填写各自模型目录；填好目录后，再配合环境变量即可切换到本地模型：

    export MINERU_MODEL_SOURCE=local

另外两点从源码可确认的行为：配置文件名可被环境变量 MINERU_TOOLS_CONFIG_JSON 覆盖为绝对路径或自定义文件名（config_reader.py#L13-L30），文件不存在时全部配置读取函数都安全返回默认值，因此没有 mineru.json 不影响使用。

八、小结与延伸阅读

  • 最小可用路径：export MINERU_MODEL_SOURCE=modelscope（按需）→ mineru -p demo/pdfs/demo1.pdf -o ./output，其余全部走默认（hybrid-engine + auto + medium effort）；
  • 服务化/多卡场景：mineru-api 单机 → mineru-router 多 worker → mineru-gradio 可视化，三者共用同一套 /health、/tasks、/file_parse 协议；
  • 推理分离场景：mineru-openai-server + *-http-client 后端。

可进一步阅读的相关文件：命令行工具使用说明、输出文件文档、模型源文档、高级命令行参数、Python 调用示例、配置模板 与 命令入口注册。

MinerU
Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
项目地址：https://gitcode.com/GitHub_Trending/mi/MinerU
登录后查看全文

相关内容推荐

1 MinerU 文档解析工具深度解析：从 PDF/Office 到 LLM-ready Markdown 与 JSON 的完整实现2 MinerU 文档解析引擎实战指南：将 PDF 与 Office 文档解析为 LLM 就绪的 Markdown/JSON3 MinerU 项目全景解析：把 PDF 与 Office 文档转换为 LLM 就绪 Markdown/JSON 的开源文档解析引擎4 MinerU 快速入门：从环境选型、安装部署到命令行解析的完整上手指南5 MinerU 海光 DCU 加速卡部署实践：构建 vLLM 镜像、启动容器与解析后端选择指南6 MinerU 文档解析实战指南：从安装部署、后端选型到 CLI 完整参数的深度解析7 MinerU 版本演进全解读：从 0.x 首次开源到 2.7 系列的后端路线图与环境变量速查8 MinerU 快速使用实战：从命令行一键解析 PDF/Office 到 API 服务与配置文件扩展9 MinerU实战指南：从安装到部署完整教程10 MinerU 命令行工具完全指南：mineru、mineru-api、mineru-gradio 与 mineru-router 参数、环境变量与编排机制
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

CodeGraph 索引漂移（CG-33）：增量 sync 与全量重建之间 4.3% 的静默分叉，以及如何让它收敛Bevy 0.20 迁移指南：CompressedImageSaver 重构与 compressed_image_saver 压缩纹理后端详解rtk 的 /worktree 命令解析：为 Rust 项目打造秒级 Git Worktree 隔离开发环境DeepTutor v1.0.2 发布解析：搜索整合简化、Provider 切换修复与前端资源泄漏治理next-ai-draw-io 部署与使用排障指南：PDF 导出、内网离线部署、自建模型 tool calling 与视觉模型选择etcd 多 Go 模块仓库的依赖管理实践：升级顺序、自动化脚本与版本一致性保障Ultralytics YOLO26-Depth 中的 TartanAir 深度数据集：AirSim 合成数据、80 米稠密真值与 uint16 PNG 深度格式Open Notebook 安装指南：从安装路线选择到 Docker Compose、源码运行与 Windows 原生部署的完整实践rustc_codegen_gcc 常见编译错误排障：failed to build archive 与 crtbegin.o 缺失的根因和修复AutoGPT × Vercel React Best Practices：用 Ref 存储事件处理器，构建稳定的 Effect 订阅

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
588
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
906
1.83 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
docsdocs
暂无描述
Markdown
891
5.79 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.53 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
988
506
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384