企业官网建设流程全解析

MinerU API 文档解析实战：一条 curl 把 PDF 变成 LLM 能吃的 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，从单文件试跑到批量转换都跑通。

30 秒跑通

✅ 三步：装、起、发第一个请求。

pip install mineru mineru-api --host 127.0.0.1 --port 8000

第一条装好命令行工具，第二条启动 API 服务，终端打出Start MinerU FastAPI Service: http://127.0.0.1:8000就说明起来了。浏览器打开同域名的 /docs 能看到可交互的接口文档，想确认服务状态随时可以敲一行curl http://127.0.0.1:8000/health，里面带队列数和版本信息。

然后发第一个解析请求：

curl -s -X POST http://127.0.0.1:8000/file_parse \ -F "files=@demo.pdf"

拿到 200、响应里有md_content字段装着 Markdown 正文，就算成功了。注意这里有个坑：首次解析会自动下载模型，第一次响应可能要等几分钟，别以为服务挂了。

核心接口拆解

📌 服务一共五个端点：POST/file_parse（同步，等解析完才返回）、POST/tasks（异步提交，立刻返回 task_id）、GET/tasks/{task_id}（查状态）、GET/tasks/{task_id}/result（取结果）、GET/health（健康检查）。前四个收同样的表单参数。你的文档页数多、耗时长，就改用异步三件套：提交、轮询状态、最后取结果，这样连接不会被网关超时掐断。

请求参数速查

常用参数：

进阶参数：

响应长什么样

同步响应把任务状态和结果放在同一个 JSON 里，关键就这几个字段：

{ "status": "completed", // 任务状态 "task_id": "9c1e…", // 异步取结果要用它 "status_url": "/tasks/9c1e…", // 状态轮询地址 "result_url": "/tasks/9c1e…/result", // 结果获取地址 "version": "3.4.4", "results": { "demo": { "md_content": "# 标题\n\n正文…" } // 每个文件一份 } }

return_*没开的键不会出现在响应里，所以默认响应已经很小。一旦把response_format_zip打开，响应体就直接变成 zip 下载，不再是这个 JSON。

后端/模式怎么选

• pipeline：通用、支持多语言、不会幻觉，速度最慢，扫描件多时选它。
• hybrid-engine（默认）：速度精度均衡，多语言，覆盖大多数场景。
• vlm-engine / vlm-http-client / hybrid-http-client：VLM 高精度，只支持中英文；两个 http-client 接远端 OpenAI 兼容推理服务，需要配 server_url。

按场景实战

场景 A：本地快速试一份 PDF（最小参数）

痛点：就想确认服务活着、解析质量能看。

curl -s -X POST http://127.0.0.1:8000/file_parse \ -F "files=@demo.pdf" \ -F "lang_list=ch"

注意：其余参数全部走默认，return_md 默认就是 true，所以默认就回 Markdown。

场景 B：批量 PDF 解析怎么传多个文件

痛点：十几份报告要一起灌，一个个下载结果太累。

curl -s -X POST http://127.0.0.1:8000/file_parse \ -F "files=@a.pdf" -F "files=@b.pdf" -F "files=@c.pdf" \ -F "response_format_zip=true" -o results.zip

注意：files 一个文件挂一个 -F；lang_list 想逐文件指定就传成等长列表，否则第一个语言应用到所有文件；结果默认落在 ./output/<task_id> 下，目录用 MINERU_API_OUTPUT_ROOT 改。

场景 C：只返回 Markdown 的 API 调用喂下游 LLM

痛点：下游只要文本，不想让响应里混一堆 base64 和 JSON。

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

注意：这其实已是默认行为——只要别打开其他 return 开关，响应就很精简；超长的文档建议再切页码，对 LLM 上下文更友好。

场景 D：指定页码范围做增量解析

痛点：文档一百多页，只改了第三章，不想整篇重跑。

curl -s -X POST http://127.0.0.1:8000/file_parse \ -F "files=@book.pdf" \ -F "start_page_id=20" -F "end_page_id=34"

注意：页码从 0 开始且两端都包含，上面等价于解析第 21 到 35 页。

MinerU API 环境变量与配置旋钮

这些都在启动服务前设好即可，前三个能覆盖同名表单参数：

常见报错速查

⚠️ 报错基本都带明确的 detail 字段，对着下表处理就行：

最典型的 400 响应长这样：

{ "detail": "Unsupported file type: .txt" }

生产环境三条建议

• 用 Docker 锁镜像版本，模型缓存挂持久卷，重启不用重新下模型。
• 别把 *-http-client 后端直接暴露公网：绑定内网，或先套一层带 HTTPS 和 token 鉴权的网关，再配 --allow-public-http-client 启动。
• MINERU_API_OUTPUT_ROOT 指向独立卷，并按需调 MINERU_API_TASK_RETENTION_SECONDS，让过期结果自动清掉，磁盘不会爆。

版本与迁移提醒

当前 3.x 的接口已经任务化：/file_parse内部也走异步任务队列，表单里不再有旧版的 output_dir 参数（输出位置改由 MINERU_API_OUTPUT_ROOT 控制）。如果你的客户端是按 2.1.x 写的，重点核对 backend 枚举值和响应字段这两处：

MinerU API 调通之后，去 /docs 交互页把参数组合试一圈，再翻翻 issue 跟踪器里有没有你关心的已知问题。

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