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/MinerUMinerU 是一款开源文档解析工具能把复杂的 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 filesdemo/pdfs/demo1.pdf \ -F return_mdtrue响应是一个 JSONresults里按文件名组织每个文件包含你请求的字段比如md_contentMarkdown 正文。如果只想要文件本身加-F response_format_ziptrue接口会直接回传一个 zip 包含 .md、中间 JSON 和图片目录省得自己解析响应体。这个 API 到底能干什么⚡先说清楚接口全貌免得你被 Swagger 里一长串参数吓到。核心就 5 个端点端点作用典型用法POST /file_parse同步解析阻塞到完成再返回小文件、调试POST /tasks异步提交立刻返回task_id大文件、批量任务GET /tasks/{task_id}查任务状态含排队位置queued_ahead轮询GET /tasks/{task_id}/result取最终结果未完成时返回 202轮询GET /health健康检查 队列/并发指标监控、部署解析能力来自底层这条流水线预处理文档分类、乱码检测→ 模型层版面/公式检测、OCR→ 管线层公式替换、表格合并→ 输出 Markdown / content list / 中间 JSON。你在 API 层面要做的只是选对后端和语言。后端backend怎么选——这是 MinerU API 里最关键的参数backend运行位置特点适合场景hybrid-engine默认本地混合解析多语言用effort调精度大多数场景的起点pipeline本地传统流水线多语言稳定无幻觉多语言 OCR、大批量vlm-engine本地VLM 端到端精度高仅中英高难度版式文档vlm-http-client远程轻量客户端本地无需 torch算力在另一台机器hybrid-http-client远程本地混合解析走远端推理混合后端规模化部署核心参数速查其余参数见 官方快速上手文档参数默认值说明files-必填PDF/图片/DOCX/PPTX/XLSX可传多个backendhybrid-engine见上表lang_list[ch]语言代码与文件数量对应不够会自动补齐parse_methodautoauto/txt/ocr扫描件手动指定ocrformula_enable/table_enabletrue公式、表格解析开关return_md/return_middle_json/return_images真/假/假控制响应里带哪些字段response_format_zipfalse结果打包成 zip 直接下载start_page_id/end_page_id0/99999页码范围从 0 开始实战场景一我只想要 Markdown 文本最常见的诉求给后端一个 PDF拿回干净的 Markdown。同步接口一步到位curl -X POST http://127.0.0.1:8000/file_parse \ -F filesreport.pdf \ -F backendpipeline \ -F return_mdtrue \ -F return_imagesfalse响应 JSON 里取results[report][md_content]就是全文。两点提醒公式和表格默认开启formula_enable、table_enable纯文本文档关掉它们能明显提速同一批文件语言不同时lang_list按文件顺序重复传即可比如三个文件就传ch、en、ch。实战场景二批量解析几十个文件怎么不拖垮服务器这是新手最容易翻车的地方。/file_parse是同步阻塞的上传 50 个 PDF 意味着一个 HTTP 连接挂着几分钟到几十分钟网关超时、内存吃紧都是常见后果。正确姿势是走异步任务接口分三步# 1. 提交任务立刻拿到 task_idHTTP 202 curl -X POST http://127.0.0.1:8000/tasks \ -F filesdoc1.pdf -F filesdoc2.pdf -F filesdoc3.pdf \ -F return_mdtrue -F response_format_ziptrue # 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 当成一个文档解析微服务挂在你系统后面即可。典型做法你的业务服务收到用户上传后转发到POST /tasks把task_id存进自己的任务表定时或轮询GET /tasks/{task_id}完成后拉取结果 zip 落库部署时用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% 的调优需求环境变量默认什么时候调MINERU_API_MAX_CONCURRENT_REQUESTS3机器余量足就调大提升吞吐OOM/超时就往回调MINERU_MODEL_SOURCEhuggingface国内网络设modelscope模型已备好可设local并配models-dirMINERU_API_OUTPUT_ROOT./output把输出指到大磁盘默认目录和系统盘同盘容易写爆还有一个体验开关启动时加--enable-vlm-preload true让 VLM 模型在服务启动阶段就预热完成否则第一个用到 VLM/hybrid 的请求会额外付出加载模型的等待。精度与速度的取舍主要靠effort参数medium更快但跳过图像/图表分析high更准但更慢仅 hybrid 系后端有效。避坑指南新手最容易踩的 3 个坑 ⚠️首次运行卡在模型下载。默认从 HuggingFace 拉模型国内网络基本必卡。启动前先export MINERU_MODEL_SOURCEmodelscope或用mineru-models-download提前下好模型指向本地目录。轮询轮着轮着 404 了。任务状态是进程内存态服务重启、--reload热重载后历史任务就查不到了且任务完成后默认只保留 24 小时MINERU_API_TASK_RETENTION_SECONDS就会被清理清理后查状态和结果都返回 404。所以结果要在保留期内取走落库别指望重查。大文件走同步接口把连接挂死。/file_parse会一直阻塞到解析完成几十页的 PDF 很容易撞上中间层超时。大文件、多文件一律走POST /tasks异步链路这也是 FastAPI 源码 里两条端点共享同一任务管理器的原因。另外上传了不支持的格式会直接 400Unsupported 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/MinerUMinerU 是一款开源文档解析工具能把复杂的 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 filesdemo/pdfs/demo1.pdf \ -F return_mdtrue响应是一个 JSONresults里按文件名组织每个文件包含你请求的字段比如md_contentMarkdown 正文。如果只想要文件本身加-F response_format_ziptrue接口会直接回传一个 zip 包含 .md、中间 JSON 和图片目录省得自己解析响应体。这个 API 到底能干什么⚡先说清楚接口全貌免得你被 Swagger 里一长串参数吓到。核心就 5 个端点端点作用典型用法POST /file_parse同步解析阻塞到完成再返回小文件、调试POST /tasks异步提交立刻返回task_id大文件、批量任务GET /tasks/{task_id}查任务状态含排队位置queued_ahead轮询GET /tasks/{task_id}/result取最终结果未完成时返回 202轮询GET /health健康检查 队列/并发指标监控、部署解析能力来自底层这条流水线预处理文档分类、乱码检测→ 模型层版面/公式检测、OCR→ 管线层公式替换、表格合并→ 输出 Markdown / content list / 中间 JSON。你在 API 层面要做的只是选对后端和语言。后端backend怎么选——这是 MinerU API 里最关键的参数backend运行位置特点适合场景hybrid-engine默认本地混合解析多语言用effort调精度大多数场景的起点pipeline本地传统流水线多语言稳定无幻觉多语言 OCR、大批量vlm-engine本地VLM 端到端精度高仅中英高难度版式文档vlm-http-client远程轻量客户端本地无需 torch算力在另一台机器hybrid-http-client远程本地混合解析走远端推理混合后端规模化部署核心参数速查其余参数见 官方快速上手文档参数默认值说明files-必填PDF/图片/DOCX/PPTX/XLSX可传多个backendhybrid-engine见上表lang_list[ch]语言代码与文件数量对应不够会自动补齐parse_methodautoauto/txt/ocr扫描件手动指定ocrformula_enable/table_enabletrue公式、表格解析开关return_md/return_middle_json/return_images真/假/假控制响应里带哪些字段response_format_zipfalse结果打包成 zip 直接下载start_page_id/end_page_id0/99999页码范围从 0 开始实战场景一我只想要 Markdown 文本最常见的诉求给后端一个 PDF拿回干净的 Markdown。同步接口一步到位curl -X POST http://127.0.0.1:8000/file_parse \ -F filesreport.pdf \ -F backendpipeline \ -F return_mdtrue \ -F return_imagesfalse响应 JSON 里取results[report][md_content]就是全文。两点提醒公式和表格默认开启formula_enable、table_enable纯文本文档关掉它们能明显提速同一批文件语言不同时lang_list按文件顺序重复传即可比如三个文件就传ch、en、ch。实战场景二批量解析几十个文件怎么不拖垮服务器这是新手最容易翻车的地方。/file_parse是同步阻塞的上传 50 个 PDF 意味着一个 HTTP 连接挂着几分钟到几十分钟网关超时、内存吃紧都是常见后果。正确姿势是走异步任务接口分三步# 1. 提交任务立刻拿到 task_idHTTP 202 curl -X POST http://127.0.0.1:8000/tasks \ -F filesdoc1.pdf -F filesdoc2.pdf -F filesdoc3.pdf \ -F return_mdtrue -F response_format_ziptrue # 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 当成一个文档解析微服务挂在你系统后面即可。典型做法你的业务服务收到用户上传后转发到POST /tasks把task_id存进自己的任务表定时或轮询GET /tasks/{task_id}完成后拉取结果 zip 落库部署时用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% 的调优需求环境变量默认什么时候调MINERU_API_MAX_CONCURRENT_REQUESTS3机器余量足就调大提升吞吐OOM/超时就往回调MINERU_MODEL_SOURCEhuggingface国内网络设modelscope模型已备好可设local并配models-dirMINERU_API_OUTPUT_ROOT./output把输出指到大磁盘默认目录和系统盘同盘容易写爆还有一个体验开关启动时加--enable-vlm-preload true让 VLM 模型在服务启动阶段就预热完成否则第一个用到 VLM/hybrid 的请求会额外付出加载模型的等待。精度与速度的取舍主要靠effort参数medium更快但跳过图像/图表分析high更准但更慢仅 hybrid 系后端有效。避坑指南新手最容易踩的 3 个坑 ⚠️首次运行卡在模型下载。默认从 HuggingFace 拉模型国内网络基本必卡。启动前先export MINERU_MODEL_SOURCEmodelscope或用mineru-models-download提前下好模型指向本地目录。轮询轮着轮着 404 了。任务状态是进程内存态服务重启、--reload热重载后历史任务就查不到了且任务完成后默认只保留 24 小时MINERU_API_TASK_RETENTION_SECONDS就会被清理清理后查状态和结果都返回 404。所以结果要在保留期内取走落库别指望重查。大文件走同步接口把连接挂死。/file_parse会一直阻塞到解析完成几十页的 PDF 很容易撞上中间层超时。大文件、多文件一律走POST /tasks异步链路这也是 FastAPI 源码 里两条端点共享同一任务管理器的原因。另外上传了不支持的格式会直接 400Unsupported 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考