MinerU API 实战指南：一条命令把 PDF 变成 Markdown，附批量解析避坑清单

MinerU API 实战指南：一条命令把 PDF 变成 Markdown，附批量解析避坑清单

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

MinerU 是一款开源文档解析工具，能把复杂的 PDF、扫描件和 Office 文档转成可直接喂给 LLM 的 Markdown 和结构化 JSON。它内置的 MinerU API 是一个 RESTful 文档解析接口：你用 HTTP 请求上传文件，它直接返回解析好的 Markdown、JSON 或压缩包，既适合批量 PDF 解析，也方便接进自己的后端服务。

30 秒跑通 MinerU API 🚀

只需要两条命令：装包、起服务。

pip install "mineru[all]" mineru-api --host 0.0.0.0 --port 8000

服务起来后，浏览器访问http://127.0.0.1:8000/docs就能打开 Swagger 调试页。发一个最小请求试试：

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

响应是一个 JSON，results里按文件名组织，每个文件包含你请求的字段，比如md_content（Markdown 正文）。如果只想要文件本身，加-F "response_format_zip=true"，接口会直接回传一个 zip 包（含 .md、中间 JSON 和图片目录），省得自己解析响应体。

这个 API 到底能干什么？⚡

先说清楚接口全貌，免得你被 Swagger 里一长串参数吓到。核心就 5 个端点：

解析能力来自底层这条流水线：预处理（文档分类、乱码检测）→ 模型层（版面/公式检测、OCR）→ 管线层（公式替换、表格合并）→ 输出 Markdown / content list / 中间 JSON。你在 API 层面要做的，只是选对"后端"和"语言"。

后端（backend）怎么选——这是 MinerU API 里最关键的参数：

核心参数速查（其余参数见 官方快速上手文档）：

实战场景一：我只想要 Markdown 文本

最常见的诉求：给后端一个 PDF，拿回干净的 Markdown。同步接口一步到位：

curl -X POST http://127.0.0.1:8000/file_parse \ -F "files=@report.pdf" \ -F "backend=pipeline" \ -F "return_md=true" \ -F "return_images=false"

响应 JSON 里取results["report"]["md_content"]就是全文。两点提醒：

• 公式和表格默认开启（formula_enable、table_enable），纯文本文档关掉它们能明显提速；
• 同一批文件语言不同时，lang_list按文件顺序重复传即可，比如三个文件就传ch、en、ch。

实战场景二：批量解析几十个文件怎么不拖垮服务器

这是新手最容易翻车的地方。/file_parse是同步阻塞的：上传 50 个 PDF 意味着一个 HTTP 连接挂着几分钟到几十分钟，网关超时、内存吃紧都是常见后果。正确姿势是走异步任务接口，分三步：

# 1. 提交任务，立刻拿到 task_id（HTTP 202） curl -X POST http://127.0.0.1:8000/tasks \ -F "files=@doc1.pdf" -F "files=@doc2.pdf" -F "files=@doc3.pdf" \ -F "return_md=true" -F "response_format_zip=true" # 2. 轮询状态 curl http://127.0.0.1:8000/tasks/<task_id> # 3. 完成后取结果（zip） curl -OJ http://127.0.0.1:8000/tasks/<task_id>/result

服务端内部有一个共享任务管理器和信号量控制并发（默认 3 个并发解析），你一次提交的多个文件会排队执行，状态查询里的queued_ahead字段告诉你前面还有几个任务。想观察整体负载，GET /health会返回队列中/处理中/已完成/失败的任务数和并发上限。

Python 端接入也很直接，用httpx发 multipart 请求即可，仓库里的 demo/demo.py 就是一个完整的异步调用示例，包含提交、轮询、下载全流程。

实战场景三：接进自己的后端服务

把 MinerU API 当成一个"文档解析微服务"挂在你系统后面即可。典型做法：

1. 你的业务服务收到用户上传后，转发到POST /tasks，把task_id存进自己的任务表；
2. 定时或轮询GET /tasks/{task_id}，完成后拉取结果 zip 落库；
3. 部署时用GET /health做存活探针。

一个 20 行内的 Python 客户端骨架：

import httpx API = "http://127.0.0.1:8000" def submit_and_wait(path: str, name: str) -> dict: with open(path, "rb") as f: r = httpx.post(f"{API}/tasks", files={"files": (name, f)}, data={"return_md": "true"}) task_id = r.json()["task_id"] while (s := httpx.get(f"{API}/tasks/{task_id}").json())["status"] not in ("completed", "failed"): import time; time.sleep(2) return httpx.get(f"{API}/tasks/{task_id}/result").json()

如果要暴露到公网，注意服务端对*-http-client后端和server_url有安全策略：绑定0.0.0.0时默认禁止这类远程客户端参数，需要显式加--allow-public-http-client启动参数才放行。

进阶调优：最值钱的 3 个开关

不用背全部环境变量，记住这三个，覆盖 90% 的调优需求：

还有一个体验开关：启动时加--enable-vlm-preload true，让 VLM 模型在服务启动阶段就预热完成，否则第一个用到 VLM/hybrid 的请求会额外付出加载模型的等待。精度与速度的取舍主要靠effort参数：medium更快但跳过图像/图表分析，high更准但更慢（仅 hybrid 系后端有效）。

避坑指南：新手最容易踩的 3 个坑 ⚠️

1. 首次运行卡在模型下载。默认从 HuggingFace 拉模型，国内网络基本必卡。启动前先export MINERU_MODEL_SOURCE=modelscope，或用mineru-models-download提前下好模型指向本地目录。
2. 轮询轮着轮着 404 了。任务状态是进程内存态，服务重启、--reload热重载后历史任务就查不到了；且任务完成后默认只保留 24 小时（MINERU_API_TASK_RETENTION_SECONDS）就会被清理，清理后查状态和结果都返回 404。所以结果要在保留期内取走落库，别指望重查。
3. 大文件走同步接口把连接挂死。/file_parse会一直阻塞到解析完成，几十页的 PDF 很容易撞上中间层超时。大文件、多文件一律走POST /tasks异步链路，这也是 FastAPI 源码 里两条端点共享同一任务管理器的原因。

另外上传了不支持的格式会直接 400（Unsupported file type），支持的是 PDF、图片（PNG/JPG 等）以及 DOCX/PPTX/XLSX。

MinerU API 的设计哲学很直白：同步接口给你调试的便利，异步接口给你生产的确定性，参数少而正交。更多参数细节和多 GPU 编排（mineru-router）玩法，见 官方使用文档 和 CLI 参数说明。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU