MinerU 系列教程 第一课走进 MinerU – 核心功能与整体架构概览MinerU 系列教程 第一篇本篇教程作为模块一基础入门与架构概览的第一课全面介绍 MinerU 的核心功能与整体架构。无论你是刚接触文档解析领域的新手还是正在寻找高质量 PDF 解析方案的工程师本文都将帮助你建立对 MinerU 的全局认知为后续的实战操作打下坚实基础。学习目标完成本课学习后你将能够理解 MinerU 的基本定位与核心价值了解 MinerU 的三大推理后端Pipeline / VLM / Hybrid及其适用场景掌握 MinerU 支持的输入格式、输出格式与主要特性熟悉 MinerU 的部署方式和交互入口了解 MinerU 的项目背景与应用场景一、MinerU 是什么1.1 基本定位MinerU 是一款面向LLM / RAG / Agent场景构建的高精度文档解析引擎能够将 PDF、图片、DOCX 等非结构化文档转化为机器可读的结构化格式如 Markdown、JSON便于后续的检索、抽取与二次处理。用一句话来概括MinerU 将人能看懂的文档变为机器能理解的数据。1.2 解决什么问题在大模型LLM时代高质量的训练数据和知识库构建都依赖于对海量文档的精准解析。然而现实中的文档面临诸多挑战挑战具体表现格式多样PDF、扫描件、Word、PPT、图片、网页等多种来源版面复杂多栏布局、跨页表格、嵌套公式、混排图文内容异构公式、表格、图片、代码块、手写体混合出现语言多样需覆盖中文、英文、日文、阿拉伯文等多种语言MinerU 正是为解决这些问题而生。它通过 VLM OCR 双引擎架构在保持高精度的同时支持109 种语言的识别与解析。二、核心技术栈三大推理后端MinerU 的解析能力建立在三套推理后端之上用户可以根据硬件条件和精度需求灵活选择。2.1 Pipeline 后端特点快速稳定无幻觉CPU / GPU 均可运行Pipeline 后端采用传统的模块化流水线架构将文档解析拆解为版面分析、OCR 识别、公式识别、表格解析等独立阶段逐步完成文档的结构化还原。核心特点CPU 友好无需 GPU 即可运行适合资源受限的环境无幻觉基于规则与传统模型的组合不会产生大模型的编造问题高性价比在 OmniDocBench (v1.5) 上取得 86.2 分精度超过上一代主流 VLM低资源占用最低 4GB 显存使用 GPU 加速时纯 CPU 环境同样可用技术组件包括版面分析模型Layout DetectionOCR 引擎支持 109 种语言公式识别输出 LaTeX表格结构识别输出 HTML阅读顺序排序文档分类器2.2 VLM 后端vlm-engine特点高精度支持 vLLM / LMDeploy / mlx 推理生态VLMVision-Language Model后端直接利用视觉语言大模型对文档页面进行端到端的理解与转化在复杂版面上具有更强的语义理解能力。核心特点高精度在 OmniDocBench (v1.5) 上得分 90端到端无需拆解为多个子任务直接从图像到结构化输出多推理框架支持 vLLM、LMDeploy、mlx-vlm 等主流推理引擎硬件要求较高需要 8GB 以上显存的 GPU 或 Apple Silicon2.3 Hybrid 后端hybrid-engine特点高精度 原生文本提取低幻觉Hybrid 后端是 Pipeline 与 VLM 的融合方案结合了两者的优势原生文本提取对于文本型 PDF直接提取原生文字避免 OCR 或 VLM 的识别误差VLM 辅助对于图片、扫描件等非文本内容调用 VLM 进行高精度解析低幻觉通过原生文本兜底显著降低大模型可能产生的幻觉问题2.4 三大后端对比维度PipelineVLMHybrid精度OmniDocBench v1.5869090是否支持纯 CPU是否否GPU 显存最低要求4GB8GB8GB幻觉风险无较高低适用场景通用文档、资源受限环境复杂版面、高精度需求兼顾精度与可靠性2.5 Office 后端除上述三大核心后端外MinerU 还提供了Office 后端支持 DOCX 和 PPTX 的原生解析。相较于先将 DOCX 转为 PDF 再解析的传统流程原生解析在无幻觉的前提下实现高精度且端到端速度提升数十倍以上。三、主要特性3.1 输入格式支持MinerU 支持多种文档格式作为输入PDF文本型 PDF、扫描型 PDF、混合型 PDF图片JPG、PNG 等常见图片格式DOCXWord 文档原生解析3.0 新增PPTXPowerPoint 文档原生解析3.2 输出格式支持输出格式说明Markdown适合 NLP 和多模态场景保留标题、段落、列表等结构JSON按阅读顺序排序的结构化数据含丰富的元信息中间格式包含版面坐标、span 信息等详细数据便于二次开发3.3 解析能力亮点公式还原自动识别文档中的数学公式并转换为 LaTeX 格式表格还原自动识别表格结构并转换为 HTML 格式支持跨页表格合并版面理解支持单栏、多栏、复杂排版输出符合人类阅读顺序元素过滤自动去除页眉、页脚、脚注、页码等干扰元素确保语义连贯扫描件支持自动检测扫描版 PDF 和乱码 PDF并启用 OCR多语言支持OCR 引擎支持 109 种语言的检测与识别可视化质检提供 layout 可视化、span 可视化等多种检查工具3.4 部署方式MinerU 提供了从本地到云端的多层次部署方案部署方式 ├── 本地部署 │ ├── pip / uv 安装 │ └── 源码安装 ├── 容器化部署 │ └── Docker ├── 服务化部署 │ ├── mineru-apiFastAPI 服务核心支持同步 / 异步接口 │ └── mineru-router多 GPU 负载均衡路由 └── 在线体验 ├── mineru.net 官网在线版 ├── ModelScope / HuggingFace Demo └── Google Colab3.5 交互入口入口说明mineruCLI命令行工具支持本地文件/目录输入可指定后端与输出格式mineru-api基于 FastAPI 的 REST API 服务支持同步POST /file_parse与异步POST /tasks接口mineru-gradio基于 Gradio 的 Web UI提供可视化的文档解析体验mineru-router多服务、多 GPU 的统一入口接口与mineru-api兼容支持自动负载均衡MCP Server支持 Cursor、Claude Desktop、Windsurf 等 AI 编程工具接入SDK 集成Python / Go / TypeScript SDK可嵌入自有系统四、应用场景MinerU 的输出结果天然适配下游的知识处理流程以下是几个典型应用场景4.1 RAG检索增强生成这是 MinerU 最核心的应用场景。通过将文档转为结构化 Markdown/JSON可以直接接入 RAG 框架进行知识检索与问答RAGFlow深度集成作为文档解析前端LangChain / LlamaIndex通过 SDK 或 API 接入解析结果Dify / FastGPT原生集成 MinerU 解析能力4.2 LLM 预训练数据MinerU 诞生于书生-浦语InternLM的预训练过程中专注于解决科技文献中的符号转化问题可将海量 PDF 文献高质量地转化为模型可用的训练数据。4.3 知识库构建企业可利用 MinerU 将内部文档技术手册、合同、报告等批量转化为结构化数据构建可检索的知识库。4.4 科技文献处理针对学术论文中常见的数学公式、化学式、复杂表格等特殊内容MinerU 提供了专门的识别与转化能力特别适合科研场景。五、项目背景与发展5.1 诞生背景MinerU 诞生于上海人工智能实验室 OpenDataLab 团队在 书生-浦语InternLM 大模型的预训练过程中孕育而生。团队在处理海量科技文献时发现传统的 PDF 解析工具在面对公式、表格、复杂版面时表现不佳大量有价值的知识无法被准确提取。为了解决这一瓶颈MinerU 应运而生最初专注于科技文献中的符号转化问题如数学公式转 LaTeX随后逐步发展为功能完备的通用文档解析引擎。5.2 架构演进MinerU 的架构经历了重要的演进过程早期版本 └── 单一 magic-pdf 解析库 2.x 版本 └── Pipeline VLM 双引擎 3.0 版本当前 ├── mineru-api ← 服务核心 ├── mineru ← CLI 编排客户端 └── mineru-router ← 多 GPU 负载均衡3.0 版本是一次关键跃迁不仅提升了解析能力更在系统架构层面实现了从单机工具到可规模化部署的解析基座的转变。主要突破包括滑动窗口 流式落盘解决长文档上万页的内存峰值问题线程安全优化全面支持多线程并发推理多卡部署通过mineru-router一键实现多 GPU 负载均衡DOCX 原生解析端到端速度提升数十倍5.3 技术栈概览MinerU 基于 Python 3.10 ~ 3.13 开发核心技术栈包括层级主要技术Web 服务FastAPI、Uvicorn、HTTPX文档解析pdfminer.six、pypdfium2、python-docx图像/OCR/VLMPillow、OpenCV、PyTorch、Transformers推理引擎vLLM、LMDeploy、mlx-vlm、ONNXRuntime输出处理ReportLab、Pandas、BeautifulSoup、pylatexenc5.4 硬件与平台支持操作系统Windows / Linux / macOS硬件加速CPU纯 CPU 可运行、GPUCUDA、NPUCANN、Apple MPS国产算力适配昇腾、寒武纪、燧原、沐曦、摩尔线程、昆仑芯、天数智芯、瀚博、太初元碁、海光、平头哥部署模式支持私有化部署和完全离线运行小结本课我们全面了解了 MinerU 的核心全貌定位明确MinerU 是面向 LLM/RAG/Agent 场景的高精度文档解析引擎将非结构化文档转为结构化的 Markdown/JSON三大后端PipelineCPU 友好、无幻觉、VLM高精度、Hybrid兼顾精度与可靠性用户可按需选择能力全面支持 PDF/图片/DOCX/PPTX 输入覆盖公式、表格、多语言、复杂版面等场景部署灵活从 CLI 到 API、从本地到 Docker、从单机到多 GPU 集群提供完整的部署链路背景扎实诞生于书生-浦语预训练实践经过大规模科技文献解析的实战验证MinerU 不仅是一个工具更是连接非结构化文档与大模型生态的关键桥梁。理解了这些基础概念你就为后续的安装部署和实战操作做好了准备。下一课预告第二课环境搭建与快速上手我们将动手实践完成 MinerU 的安装部署pip/Docker运行第一个文档解析任务并深入了解 CLI 的各项参数与输出结构。准备好一份 PDF 文档下一课见