MinerU API 文档解析实战：一条 curl 把 PDF 变成 LLM 能吃的 Markdown

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/MinerUMinerU 是一款开源文档解析工具把 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 filesdemo.pdf拿到 200、响应里有md_content字段装着 Markdown 正文就算成功了。注意这里有个坑首次解析会自动下载模型第一次响应可能要等几分钟别以为服务挂了。核心接口拆解 服务一共五个端点POST/file_parse同步等解析完才返回、POST/tasks异步提交立刻返回 task_id、GET/tasks/{task_id}查状态、GET/tasks/{task_id}/result取结果、GET/health健康检查。前四个收同样的表单参数。你的文档页数多、耗时长就改用异步三件套提交、轮询状态、最后取结果这样连接不会被网关超时掐断。请求参数速查常用参数参数类型必填默认值一句话说明files文件列表是—常见文档与图片文件lang_list字符串列表否chOCR 语言每文件一个backend字符串否hybrid-engine解析引擎对比见下文parse_method字符串否autoauto/txt/ocr 三选一formula_enable布尔否true是否解析公式table_enable布尔否true是否解析表格start_page_id整数否0起始页从 0 数end_page_id整数否99999结束页从 0 数进阶参数参数类型必填默认值一句话说明effort字符串否medium仅 hybrid 用medium/highimage_analysis布尔否true是否解析图表server_url字符串否无http-client 的远端地址return_md布尔否true返回 Markdownreturn_middle_json布尔否false返回中间 JSONreturn_model_output布尔否false返回模型原始输出return_content_list布尔否false返回内容列表return_images布尔否false图片 base64 返回response_format_zip布尔否false用 ZIP 代替 JSON 返回client_side_output_generation布尔否false由客户端组装最终 md响应长什么样同步响应把任务状态和结果放在同一个 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-clientVLM 高精度只支持中英文两个 http-client 接远端 OpenAI 兼容推理服务需要配 server_url。按场景实战场景 A本地快速试一份 PDF最小参数痛点就想确认服务活着、解析质量能看。curl -s -X POST http://127.0.0.1:8000/file_parse \ -F filesdemo.pdf \ -F lang_listch注意其余参数全部走默认return_md 默认就是 true所以默认就回 Markdown。场景 B批量 PDF 解析怎么传多个文件痛点十几份报告要一起灌一个个下载结果太累。curl -s -X POST http://127.0.0.1:8000/file_parse \ -F filesa.pdf -F filesb.pdf -F filesc.pdf \ -F response_format_ziptrue -o results.zip注意files 一个文件挂一个 -Flang_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 filespaper.pdf -F return_mdtrue注意这其实已是默认行为——只要别打开其他 return 开关响应就很精简超长的文档建议再切页码对 LLM 上下文更友好。场景 D指定页码范围做增量解析痛点文档一百多页只改了第三章不想整篇重跑。curl -s -X POST http://127.0.0.1:8000/file_parse \ -F filesbook.pdf \ -F start_page_id20 -F end_page_id34注意页码从 0 开始且两端都包含上面等价于解析第 21 到 35 页。MinerU API 环境变量与配置旋钮这些都在启动服务前设好即可前三个能覆盖同名表单参数变量名作用推荐值备注MINERU_DEVICE_MODE指定推理设备不设自动探测 cuda/mps/cpuMINERU_FORMULA_ENABLE公式解析总开关true优先级高于表单参数MINERU_TABLE_ENABLE表格解析总开关true同上MINERU_API_MAX_CONCURRENT_REQUESTS并发解析任务数3Mac 上固定为 1MINERU_PROCESSING_WINDOW_SIZE页级窗口批大小64按内存余量调MINERU_API_TASK_RETENTION_SECONDS完成任务保留时长86400设 0 关闭自动清理MINERU_PDF_RENDER_THREADSPDF 渲染线程数3CPU 核多可加大常见报错速查⚠️ 报错基本都带明确的 detail 字段对着下表处理就行状态码/现象大概率原因30 秒解法400 Unsupported file type文件类型不支持只支持 pdf/常见图片/docx/pptx/xlsx400 Invalid backend 等枚举值写错回看上面两张参数表404 Task not found任务过期或服务重启过重新提交 /tasks409 Task execution failed解析过程抛异常翻服务端的日志503 unhealthyworker 崩溃或未就绪看 /health 输出和日志202 result not ready异步任务还没跑完隔几秒再轮询 status_url最典型的 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 枚举值和响应字段这两处版本与当前兼容一句话差异3.x当前任务化 API异步 /tasks 加 /health2.1.x不兼容旧同步参数带 output_dir 表单字段2.0.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考