MinerU 4.0 深度解读：开源文档解析进入 Agent 时代

DOCPARSING·AGENTERA·2026.09MinerU4.0深度解读开源文档解析进入Agent时代把PDF、图片、Office、网页、电子书变成Agent能直接消费的结构化数据四级解析·原生多格式·本地文档库·统一SDK/API·安装与实测CONTENTS五个部分，一次讲透MinerU4.001重新认识MinerU它解决什么问题，4.0变了什么02架构解析四级解析、DocVortex与本地文档库03安装部署从pip安装到模型下载与硬件选型04怎么用CLI/PythonSDK/V1API/WebUI05实测对比OmniDocBench跑分、短板与选型建议END写在最后一句话结论与落地路径01重新认识MinerUINTRO·它解决什么问题，4.0变了什么01/WHATISMINERU一句话：把复杂文档变成Agent能直接啃的干净数据MinerU是上海人工智能实验室OpenDataLab团队开源的智能文档解析引擎，专门把PDF、图片、Office、网页、电子书等复杂文档，转成大模型可直接消费的结构化数据（Markdown/JSON/LaTeX）。它长期位居开源社区最受欢迎的复杂文档解析工具之列，广泛用于科研文献解析、AI-Ready数据生产和企业知识库建设。80k+GitHubStar数量级109支持识别的语言数量4.02026年9月发布的大版本01/THEPROBLEM文档解析=转PDF再OCR？复杂文档不该这么狼狈传统PDF解析的常见痛点复杂多栏排版结构丢失扫描件、模糊页识别率低公式、跨页表格还原差阅读顺序错乱，段落拼接错误页眉页脚页码混进正文MinerU的处理方式VLM+小模型双引擎协同自动去除页眉页脚与页码公式转LaTeX、表格转HTML还原人类自然阅读顺序保留标题、段落、列表层级输出即大模型友好的结构化文本，而不是一堆需要后处理的版面碎片01/WHAT'SNEWIN4.04.0的六大关键变化：从单机工具到解析基础设施四级解析flash→basic→standard→advanced，按质量、速度、成本取舍DocVortex原生解析docx/pptx/xlsx，不再先转PDF，快数十倍本地文档库parse/read/find/search，支持Agent渐进式阅读模型配置独立小模型与VLM引擎解耦，ONNX/Torch与llama.cpp/vLLM/LMDeploy独立配置统一SDK/API/WebUIPythonSDK、批量转换、多服务Router、GradioWebUI共享同一结果模型，V1API重建九种渲染目标一个文档模型可渲染到Markdown/HTML/LaTeX/DOCX/EPUB/PDF等九种目标01/LICENSE&ECOSYSTEM协议商用友好，4.0把受限依赖清理干净MinerUOpenSourceLicense（基于Apache2.0）绝大多数场景可免费商用MAU超1亿或月收入超2000万美元时需单独商业授权基于MinerU提供第三方在线服务需显著标注4.0移除AGPLv3与CC-BY-NC-SA等受限模型依赖生态上支持MCP协议，可对接Dify、Notion等主流Agent框架；4.0首次适配AMDRadeon本地GPU，并持续适配昇腾、寒武纪、昆仑芯、海光、摩尔线程等国产芯片。02架构解析ARCH·四级解析、DocVortex与本地文档库02/FOURTIERS四级解析质量：按质量—速度—成本灵活取舍Tier质量与速度典型用途flash质量最低、速度最快，无需推理模型文档发现、快速预览、建索引basic小模型跑OCR/公式/表格，可纯CPU低资源环境下的本地阅读standard小模型+VLM，默认阅读质量复杂文档的主动阅读与入库advanced更多推理算力，最慢但质量最高困难文档追求最大解析质量PDF与图片支持全部四级；Office、OpenDocument、EPUB、OFD、HTML、CSV/TSV在flash层本地解析；纯文本直接读取。02/D0CVORTEXDocVortex：不再转PDF，直接解析原生Office文档传统做法：先转PDF再解析docx/pptx/xlsx转PDFOCR/VLM多一次格式转换，结构信息损失，速度慢，GPU占用高DocVortex：原生直读docx/pptx/xlsx结构化Markdown/JSON无幻觉：直接读原生结构，不靠视觉猜。快数十倍：省去转PDF与视觉推理。几乎不占GPU：适合高频、批量、在线化处理。02/LOCALDOCUMENTLIBRARY从"解析一次"升级为"本地文档库"核心命令族parse解析文档入库read按定位符读取区块内容find/search在已入库文档中检索show/list查看文档与区块列表watch/scan监听目录与扫描新增文档invalidate缓存控制：失效/清理这意味着什么文档不再是一次性文件，而是被索引、可检索的本地知识解析结果带缓存，重复查询零成本配合后台服务，文档目录变化可自动感知为Agent把文档当"可检索知识库"使用打下基础02/PROGRESSIVEREADINGAgent渐进式阅读：长文档逐页读，而非一次性加载第一步：mineruparse默认只解析前10页返回结果中附带next_request续读命令，不一次性吞掉整本文档第二步：按需续读下一段Agent判断前10页信息不足时，再发起下一段解析，节省算力与时间第三步：稳定定位符支持可核验引用doc:ab12cd3/tier:standard/page:11/block:5定位符支持续读、页码与区块图片导出——这正是Agent把文档当"可检索知识"用的关键02/PRIVACYBYDEFAULT默认本地解析，文档不出机器01本地优先：所有解析默认在本机完成，只有显式加--remote才会上传到远程服务。02遥测透明：可用minerutelemetrystatus查看当前遥测状态，并随时关闭。03商用边界：基于MinerU提供第三方在线服务需显著标注，MAU与营收达阈值时另行商业授权。02/MODELCONFIG小模型与VLM引擎解耦，不再绑定单一stack小模型后端model.small_backendONNX（开箱即用，CPU可跑）或Torch（AppleSilicon/GPU推荐）VLM引擎model.vlm.enginellama.cpp（轻量默认）/vLLM（Linux高性能）/LMDeploy（Windows）两层独立配置，移除旧的model.stack/--stack；按硬件与精度需求自由组合。基础包baseONNXCPU小模型+llama.cppVLM，开箱即用mineru[torch]加Torch小模型，AppleSilicon/有GPU推荐mineru[full]装vLLM（Linux）或LMDeploy（Windows）高性能推理02/UNIFIEDTOOLCHAIN&V1API四种入口共享同一结构化结果模型统一工具链PythonSDKparse/parse_async/云端客户端mineru-kitparse无状态批量文件转换mineru-router多服务路由与负载均衡mineru-webuiGradio图形界面V1HTTPAPI（围绕V1重建）GET/v1/healthGET/v1/tiersPOST/v1/uploadsPOST/v1/parse/jobsGET/v1/files/{id}/content旧版/file_parse与/tasks端点已移除；四端结果对象可序列化回放，SDK与服务端行为一致。02/NINERENDERTARGETS一个文档模型，渲染到九种目标格式MarkdownHTMLLaTeXDOCXEPUBPDFStructuredContentContentListV1/V2页码范围语法跨CLI/库/API/SDK完全一致s"1-5,8,r3-r1"#r1表示倒数第1页，all表示全文同一份解析结果可同时产出给人看的PDF/DOCX和给机器消费的JSON/ContentList02/ENGINEERINGENHANCEMENTS万页级长文档，8GB内存也能稳定跑8GB滑动窗口降低峰值内存，流式落盘持续写出，万页级长文档不再一次性吞进内存。多线程与多GPU线程安全与多线程并发推理；mineru-router一键多GPU、自动负载均衡国产芯片持续适配昇腾、寒武纪、昆仑芯、海光、摩尔线程等平台持续适配中AMDRadeon本地GPU4.0首次适配AMDRadeon，本地部署覆盖更多算力平台03安装部署INSTALL·从pip安装到模型下载与硬件选型03/INSTALLpip三档安装，按硬件对号入座环境要求Python≥3.10且<3.15普通电脑用基础包即可开箱即用要更高精度或GPU加速再装torch/full#基础包：开箱即用pipinstall-Umineru#加Torch小模型（AppleSilicon/GPU）pipinstall-U"mineru[torch]"#加vLLM/LMDeploy（高性能推理）pipinstall-U"mineru[full]"基础包=ONNXCPU小模型+llama.cppVLM；full包在Linux上装vLLM，Windows上装LMDeploy03/MODELDOWNLOAD首次使用前下载模型，国内走ModelScope镜像#下载模型（standard替代旧-mall）mineru-kitmodelsdownload--tierstandardmineru-kitmodelsverify#校验完整性国内镜像加速exportMINERU_MODEL_SOURCE=modelscope配置文件迁移旧版mineru.json已迁移到$MINERU_HOME/config.yaml下完模型用verify校验完整性，避免下载中断导致加载失败。模型按tier下载，standard是日常推荐档位。03/HARDWAREGUIDE硬件选型：从纯CPU到多GPU全档位覆盖硬件环境推荐Tier附加包macOSAppleSiliconstandardtorchWin/Linux+NVIDIA8GB以上standardfullWin/Linux+NVIDIA4GB以上basictorch无现代加速器basicbase资源占用参考basic：模型约0.8GB，内存2GB，可纯CPUstandard：约2GB，内存8GBtorch+vLLM：约3GB，内存16GBDocker部署详见官方文档（Linux/WinWSL2）；8GB内存是日常跑standard的甜点配置04怎么用USAGE·CLI/PythonSDK/V1API/WebUI04/COMMANDLINEmineruparse：最常用的一条命令#解析全部页（4.0新语法）mineruparseinput.pdfsall-ooutput.md#默认前10页，返回next_request续读mineruparseinput.pdf-ooutput.md#指定tier与页码范围mineruparseinput.pdf--tieradvanced-oout.mdmineruparseinput.pdfs"1-5,8,r3-r1"-oout.md默认本地解析；只有显式加--remote才会上传到远程服务，隐私边界清晰。04/SEARCH&READ文档入库后：搜索与按定位符续读search：在已入库文档全文检索关键词，--json输出结构化结果。read：按稳定定位符读取指定文档、档位、页和区块，支持图片导出。这两个命令让Agent可以像查数据库一样查文档。#全文搜索minerusearch

"大模型"--json#按定位符续读某页mineruread"doc:ab12cd3/tier:standard/page:11"--json定位符可跨会话复用：同一份文档即使重启进程，仍能精确定位到之前读到的区块04/PYTHONSDKPythonSDK：三行代码完成解析frompathlibimportPathfrommineru.parserimport

parse,ParseResultresult=parse("document.pdf",tier="standard",ocr_mode="txt",page_range="1-3")Path("document.md").write_text(result.markdown(),encoding="utf-8")SDK还提供异步入口parse_async云端客户端MineruApiParser结果对象可序列化回放04/V1HTTPAPIV1API请求周期：上传→任务→轮询→取产物POST/v1/uploads上传文件字节POST/v1/parse/jobs提交解析任务轮询任务状态等待完成GET/v1/files/{id}下载解析产物#自托管V1服务（默认本地匿名）mineru-kitapi-server--host--port8000--tierstandard加--api-key启动后，请求头带Authorization:Bearer$MINERU_API_KEY；默认本地匿名启动，适合内网自用。04/ROUTER&WEBUI多GPU路由与Gradio网页界面mineru-router：多GPU负载均衡mineru-router\--host--port8002\--local-gpusauto\--worker-tierstandard自动发现本机GPU，按worker-tier拉起工作进程，请求自动负载均衡。mineru-kitwebui：Gradio界面mineru-kitwebui\--server-name\--server-port7860浏览器上传文档、选档位、直接看解析结果，适合非工程师快速试用。Router面向生产环境多卡调度，WebUI面向个人试用与轻量协作，两者可单独部署也可组合。04/AGENTINTEGRATION通过MCP协议接入主流Agent框架Agent框架Dify/Notion/OpenClaw等MCP模型上下文协议MinerU本地解析结构化数据回传AgentMinerUSkill：新版技能让Agent自动完成本地安装与能力调用，文档上传由用户显式授权，避免静默读取。这使得"扔给Agent一份PDF，它自己读完、引用、回答"成为默认体验，而不是需要人工写解析管线。05实测对比BENCH·OmniDocBench跑分、短板与选型建议05/OMNIDOCBENCH用什么基准衡量：OmniDocBenchOmniDocBench是文档解析综合基准，覆盖多类型、多排版、多语言真实PDF，对文本、表格、公式、阅读顺序分别打分，是目前开源圈最常被引用的横向评测。981PDF页面9种文档类型4种排版3种语言四个打分维度：文本编辑距离、表格TEDS、公式CDM、阅读顺序编辑距离。下面的横向对比基于开源评测，对比对象包括MinerU、Marker、Docling、olmOCR等主流开源工具。05/OVERALLSCORE综合跑分：MinerU双语整体最优0.15英文整体编辑距离，主流工具中最低0.357中文整体编辑距离，双语场景最佳0.909Docling中文整体编辑距离，主流工具中最差05/PER-DIMENSION分项看：文本领先，公式均衡，中文阅读顺序偏弱纯文本0.061英文编辑距离，五款第一；中文0.215同样第一表格TEDS78.6英文表格结构还原度；中文62.1，复杂表格仍有提升空间公式CDM57.3/42.9英文/中文，双语较均衡；olmOCR英文74.3但中文骤降到43.2阅读顺序0.079英文极佳；中文复杂排版与竖排场景误差率上升纯文本场景MinerU全面领先；公式双语均衡是它区别于olmOCR的重要优势——后者英文强但中文断档。05/C