MinerU API 实战指南3 步启动、5 个场景把 PDF 批量解析搬进你的项目【免费下载链接】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 文档转成 Markdown 与 JSON 的开源工具配套的 MinerU API 让你用一条 curl 就能拿到解析结果。适合想把文档解析接进自己项目的开发者本文只讲怎么跑起来、怎么配、怎么避坑。三步跑通服务第 1 步安装。一条命令把 CLI 和 API 服务一起装上pip install mineru第 2 步启动 API 服务。mineru-api基于 uvicorn 拉起 FastAPI 服务默认端口 8000。绑定 0.0.0.0 后容器里或局域网的同事都能访问浏览器打开/docs就是可交互的 Swagger 页面# 监听所有网卡方便容器或其他机器访问 mineru-api --host 0.0.0.0 --port 8000第 3 步发第一条请求。接口只有一个必传项文件。其余参数都有默认值直接用仓库自带的示例 PDF 验证链路curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F lang_listch \ -F return_mdtrue返回 JSON 里出现md_content说明整条链路通了。读懂核心接口 /file_parse所有参数都在 multipart 表单区files 在文件区缺省时全部走默认值。这张总表建议存档参数必填默认值说明files是-待解析文件支持 PDF、图片、DOCX、PPTX、XLSXlang_list否[ch]每个文件对应的 OCR 语言仅 pipeline 后端生效backend否hybrid-engine解析引擎选型见后文对比表effort否mediumhybrid 后端的解析强度medium / highparse_method否autoauto / txt / ocr仅 pipeline 与 hybrid 生效formula_enable否true是否识别公式table_enable否true是否识别表格image_analysis否true是否分析图片与图表vlm 和 hybrid 生效server_url否-远程推理地址OpenAI 兼容仅 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 返回结果start_page_id / end_page_id否0 / 99999解析页范围两端都包含成功响应固定带 backend、version 和按文件名组织的 results每份文件里只有你勾选的输出{ backend: hybrid-engine, version: 3.4.4, results: { demo1: { md_content: # 标题\n正文……, content_list: [{\type\: \text\, ...}] } } }每个字段的校验规则和默认值都写在 OpenAPI 描述里参数定义可查 mineru/cli/api_request.py服务端入口在 mineru/cli/fast_api.py。 lang_list 和 files 是按位置配对的三个文件只传一个语言值时三份全用第一个只有数量与文件数一致时每个文件才各用各的。混语料上传出问题时先查这里。5 个高频场景场景一一次解析一批 PDF。做批量 PDF 解析服务时一个请求就能带多份文件重复传 files 字段即可不用自己写循环curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F filesdemo/pdfs/demo2.pdf \ -F filesdemo/pdfs/demo3.pdf场景二只要 Markdown。下游只消费文本时把无关输出全部关掉响应体会小很多curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F return_mdtrue \ -F return_middle_jsonfalse \ -F return_imagesfalse场景三按页码切片。长文档可以分页解析既降内存压力也让单页失败时重试成本更低。注意页码从 0 数起# 只解析第 5 页到第 15 页 curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F start_page_id5 \ -F end_page_id15场景四多语言混排批处理。一批文件里中英文混着来就按位置给每份文件指定语言curl -X POST http://localhost:8000/file_parse \ -F fileschinese.pdf -F filesjapanese.pdf \ -F lang_listch -F lang_listch \ -F backendpipeline场景五控制输出字段喂给下游。往 RAG 流水线灌数据时分块用 content_list 比 md_content 顺手想把产物一次性落盘就切 ZIP# 只取分块友好的内容列表打包成 ZIP 下载 curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F return_mdfalse \ -F return_content_listtrue \ -F response_format_ziptrue -o results.zip⚠️ 两个高频翻车点页码从 0 计数前 10 页是 0 到 9不是 1 到 10上传类型仅限 PDF、图片、DOCX、PPTX、XLSX其他后缀直接被 400 拒掉客户端最好先自行校验扩展名。解析引擎怎么选backend 参数就是 MinerU API 的发动机切换键当前五个取值各适其主backend特点选型结论pipeline传统流水线语言支持面最广CPU 可跑没有 GPU、文档语言杂就选它hybrid-engine流水线与 VLM 混合默认引擎拿不准就保持默认不动vlm-engineVLM 端到端精度高仅中英文中英文文档追求精度时选它vlm-http-client调远程 OpenAI 兼容服务本地几乎零算力服务器配置薄时另配一台 GPU 推理机hybrid-http-client同上但为混合模式支持多语言多语料 远程推理的组合方案 两个配套细节effort 只对两个 hybrid 后端生效精度优先时传 highparse_method 只对 pipeline 和 hybrid 生效有文本层的 PDF 用 txt扫描件用 ocr。上生产前检查一遍上线前把这份紧凑清单过一遍容器化部署仓库自带 docker/compose.yaml 可直接docker compose up -d自建镜像时记得挂载输出目录并固定模型缓存卷避免每次启动重新下模型。HTTPS 与暴露面默认只绑定 127.0.0.1仅限本机真要对外先挂一层反向代理 TLS别把裸 HTTP 端口直接交给公网。日志级别由 MINERU_LOG_LEVEL 控制排查期设 DEBUG上线后回 INFO。输出根目录MINERU_API_OUTPUT_ROOT 决定解析产物落在哪容器环境挂到大磁盘。关键环境变量MINERU_DEVICE_MODEcuda / cpu、MINERU_MODEL_SOURCE模型下载源国内环境可设 modelscope、MINERU_VIRTUAL_VRAM_SIZE限定显存、MINERU_FORMULA_ENABLE 与 MINERU_TABLE_ENABLE全局关闭公式或表格识别。出了问题先查这里先对错误码再对症状状态码含义你的动作400文件类型不支持或参数取值越界核对扩展名核对 backend、parse_method 的枚举值422表单校验失败字段缺失或类型不对打开 /docs 对照 schema500服务端解析出错看日志多为模型未下载或显存/内存不足三个高频问题每个给一两个能直接执行的动作响应慢先关 formula_enable、table_enable再考虑把重活交给 http-client 后端丢给远程 GPU。大文件上百页卡死或失败用 start_page_id、end_page_id 分段并发处理或换 vlm-http-client 远程推理。精度不够backend 换 vlm-engine 或把 hybrid-engine 的 effort 调到 high扫描件确认 parse_methodocr 且 lang_list 语言正确。命令行参数与环境变量的完整说明见 docs/zh/usage/cli_tools.md。MinerU API 的字段不多把 return_* 五个开关、页码切片和 backend 组合吃透就能覆盖绝大多数集成需求。先在开发环境跑通三步再逐场景验证最后按清单上生产。遇到文档没写到的行为项目仓库的官方文档目录docs/zh/和 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），仅供参考
MinerU API 实战指南：3 步启动、5 个场景把 PDF 批量解析搬进你的项目
MinerU API 实战指南3 步启动、5 个场景把 PDF 批量解析搬进你的项目【免费下载链接】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 文档转成 Markdown 与 JSON 的开源工具配套的 MinerU API 让你用一条 curl 就能拿到解析结果。适合想把文档解析接进自己项目的开发者本文只讲怎么跑起来、怎么配、怎么避坑。三步跑通服务第 1 步安装。一条命令把 CLI 和 API 服务一起装上pip install mineru第 2 步启动 API 服务。mineru-api基于 uvicorn 拉起 FastAPI 服务默认端口 8000。绑定 0.0.0.0 后容器里或局域网的同事都能访问浏览器打开/docs就是可交互的 Swagger 页面# 监听所有网卡方便容器或其他机器访问 mineru-api --host 0.0.0.0 --port 8000第 3 步发第一条请求。接口只有一个必传项文件。其余参数都有默认值直接用仓库自带的示例 PDF 验证链路curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F lang_listch \ -F return_mdtrue返回 JSON 里出现md_content说明整条链路通了。读懂核心接口 /file_parse所有参数都在 multipart 表单区files 在文件区缺省时全部走默认值。这张总表建议存档参数必填默认值说明files是-待解析文件支持 PDF、图片、DOCX、PPTX、XLSXlang_list否[ch]每个文件对应的 OCR 语言仅 pipeline 后端生效backend否hybrid-engine解析引擎选型见后文对比表effort否mediumhybrid 后端的解析强度medium / highparse_method否autoauto / txt / ocr仅 pipeline 与 hybrid 生效formula_enable否true是否识别公式table_enable否true是否识别表格image_analysis否true是否分析图片与图表vlm 和 hybrid 生效server_url否-远程推理地址OpenAI 兼容仅 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 返回结果start_page_id / end_page_id否0 / 99999解析页范围两端都包含成功响应固定带 backend、version 和按文件名组织的 results每份文件里只有你勾选的输出{ backend: hybrid-engine, version: 3.4.4, results: { demo1: { md_content: # 标题\n正文……, content_list: [{\type\: \text\, ...}] } } }每个字段的校验规则和默认值都写在 OpenAPI 描述里参数定义可查 mineru/cli/api_request.py服务端入口在 mineru/cli/fast_api.py。 lang_list 和 files 是按位置配对的三个文件只传一个语言值时三份全用第一个只有数量与文件数一致时每个文件才各用各的。混语料上传出问题时先查这里。5 个高频场景场景一一次解析一批 PDF。做批量 PDF 解析服务时一个请求就能带多份文件重复传 files 字段即可不用自己写循环curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F filesdemo/pdfs/demo2.pdf \ -F filesdemo/pdfs/demo3.pdf场景二只要 Markdown。下游只消费文本时把无关输出全部关掉响应体会小很多curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F return_mdtrue \ -F return_middle_jsonfalse \ -F return_imagesfalse场景三按页码切片。长文档可以分页解析既降内存压力也让单页失败时重试成本更低。注意页码从 0 数起# 只解析第 5 页到第 15 页 curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F start_page_id5 \ -F end_page_id15场景四多语言混排批处理。一批文件里中英文混着来就按位置给每份文件指定语言curl -X POST http://localhost:8000/file_parse \ -F fileschinese.pdf -F filesjapanese.pdf \ -F lang_listch -F lang_listch \ -F backendpipeline场景五控制输出字段喂给下游。往 RAG 流水线灌数据时分块用 content_list 比 md_content 顺手想把产物一次性落盘就切 ZIP# 只取分块友好的内容列表打包成 ZIP 下载 curl -X POST http://localhost:8000/file_parse \ -F filesdemo/pdfs/demo1.pdf \ -F return_mdfalse \ -F return_content_listtrue \ -F response_format_ziptrue -o results.zip⚠️ 两个高频翻车点页码从 0 计数前 10 页是 0 到 9不是 1 到 10上传类型仅限 PDF、图片、DOCX、PPTX、XLSX其他后缀直接被 400 拒掉客户端最好先自行校验扩展名。解析引擎怎么选backend 参数就是 MinerU API 的发动机切换键当前五个取值各适其主backend特点选型结论pipeline传统流水线语言支持面最广CPU 可跑没有 GPU、文档语言杂就选它hybrid-engine流水线与 VLM 混合默认引擎拿不准就保持默认不动vlm-engineVLM 端到端精度高仅中英文中英文文档追求精度时选它vlm-http-client调远程 OpenAI 兼容服务本地几乎零算力服务器配置薄时另配一台 GPU 推理机hybrid-http-client同上但为混合模式支持多语言多语料 远程推理的组合方案 两个配套细节effort 只对两个 hybrid 后端生效精度优先时传 highparse_method 只对 pipeline 和 hybrid 生效有文本层的 PDF 用 txt扫描件用 ocr。上生产前检查一遍上线前把这份紧凑清单过一遍容器化部署仓库自带 docker/compose.yaml 可直接docker compose up -d自建镜像时记得挂载输出目录并固定模型缓存卷避免每次启动重新下模型。HTTPS 与暴露面默认只绑定 127.0.0.1仅限本机真要对外先挂一层反向代理 TLS别把裸 HTTP 端口直接交给公网。日志级别由 MINERU_LOG_LEVEL 控制排查期设 DEBUG上线后回 INFO。输出根目录MINERU_API_OUTPUT_ROOT 决定解析产物落在哪容器环境挂到大磁盘。关键环境变量MINERU_DEVICE_MODEcuda / cpu、MINERU_MODEL_SOURCE模型下载源国内环境可设 modelscope、MINERU_VIRTUAL_VRAM_SIZE限定显存、MINERU_FORMULA_ENABLE 与 MINERU_TABLE_ENABLE全局关闭公式或表格识别。出了问题先查这里先对错误码再对症状状态码含义你的动作400文件类型不支持或参数取值越界核对扩展名核对 backend、parse_method 的枚举值422表单校验失败字段缺失或类型不对打开 /docs 对照 schema500服务端解析出错看日志多为模型未下载或显存/内存不足三个高频问题每个给一两个能直接执行的动作响应慢先关 formula_enable、table_enable再考虑把重活交给 http-client 后端丢给远程 GPU。大文件上百页卡死或失败用 start_page_id、end_page_id 分段并发处理或换 vlm-http-client 远程推理。精度不够backend 换 vlm-engine 或把 hybrid-engine 的 effort 调到 high扫描件确认 parse_methodocr 且 lang_list 语言正确。命令行参数与环境变量的完整说明见 docs/zh/usage/cli_tools.md。MinerU API 的字段不多把 return_* 五个开关、页码切片和 backend 组合吃透就能覆盖绝大多数集成需求。先在开发环境跑通三步再逐场景验证最后按清单上生产。遇到文档没写到的行为项目仓库的官方文档目录docs/zh/和 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），仅供参考