MinerU/README_zh-CN.md

English | 简体中文

🚀MinerU 官网入口→✅ 免装在线版 ✅ 全功能客户端 ✅ 开发者API在线调用，省去部署麻烦，多种产品形态一键get，速冲！

👋 join us on Discord and WeChat

更新记录

• 2025/12/31 2.7.0 发布
  • 简化安装流程，现在不再需要单独安装vlm加速引擎依赖包，安装时使用uv pip install mineru[all]即可安装所有可选后端的依赖包。
  • 增加全新后端hybrid，该后端结合了pipeline和vlm后端的优势，在vlm的基础上，融入了pipeline的部分能力，在高精度的基础上增加了额外的扩展性：
    • 从文本pdf中直接抽取文本，在文本pdf场景原生支持多语言识别，并极大减少解析幻觉；
    • 通过指定ocr语言，在扫描pdf场景下支持109种语言的文本识别；
    • 独立的行内公式识别开关，在不需要行内公式识别的场景下可单独关闭，提升解析结果视觉效果。
  • 简化vlm/hybrid后端的引擎选择逻辑，用户只需指定后端为*-auto-engine，系统会根据当前环境自动选择合适的引擎进行推理加速，提升易用性.
  • 默认解析后端从pipeline切换至hybrid-auto-engine，提升新用户开箱即用的结果一致性，避免出现解析结果认知差异。
  • gradio应用增加i18n适配，支持中英文两种语言切换。

📝 查看完整的 更新日志 了解更多历史版本信息

MinerU

项目简介

MinerU是一款将PDF转化为机器可读格式的工具（如markdown、json），可以很方便地抽取为任意格式。 MinerU诞生于书生-浦语的预训练过程中，我们将会集中精力解决科技文献中的符号转化问题，希望在大模型时代为科技发展做出贡献。 相比国内外知名商用产品MinerU还很年轻，如果遇到问题或者结果不及预期请到issue提交问题，同时附上相关PDF。

https://github.com/user-attachments/assets/4bea02c9-6d54-4cd6-97ed-dff14340982c

主要功能

• 删除页眉、页脚、脚注、页码等元素，确保语义连贯
• 输出符合人类阅读顺序的文本，适用于单栏、多栏及复杂排版
• 保留原文档的结构，包括标题、段落、列表等
• 提取图像、图片描述、表格、表格标题及脚注
• 自动识别并转换文档中的公式为LaTeX格式
• 自动识别并转换文档中的表格为HTML格式
• 自动检测扫描版PDF和乱码PDF，并启用OCR功能
• OCR支持109种语言的检测与识别
• 支持多种输出格式，如多模态与NLP的Markdown、按阅读顺序排序的JSON、含有丰富信息的中间格式等
• 支持多种可视化结果，包括layout可视化、span可视化等，便于高效确认输出效果与质检
• 支持纯CPU环境运行，并支持 GPU(CUDA)/NPU(CANN)/MPS 加速
• 兼容Windows、Linux和Mac平台

快速开始

如果安装或使用中遇到任何问题，请先查询 FAQ
如果遇到解析效果不及预期，参考 Known Issues

在线体验

官网在线应用

官网在线版功能与客户端一致，界面美观，功能丰富，需要登录使用

• 

基于Gradio的在线demo

基于gradio开发的webui，界面简洁，仅包含核心解析功能，免登录

• 
• 

本地部署

Warning

安装前必看——软硬件环境支持说明

为了确保项目的稳定性和可靠性，我们在开发过程中仅对特定的软硬件环境进行优化和测试。这样当用户在推荐的系统配置上部署和运行项目时，能够获得最佳的性能表现和最少的兼容性问题。

通过集中资源和精力于主线环境，我们团队能够更高效地解决潜在的BUG，及时开发新功能。

在非主线环境中，由于硬件、软件配置的多样性，以及第三方依赖项的兼容性问题，我们无法100%保证项目的完全可用性。因此，对于希望在非推荐环境中使用本项目的用户，我们建议先仔细阅读文档以及FAQ，大多数问题已经在FAQ中有对应的解决方案，除此之外我们鼓励社区反馈问题，以便我们能够逐步扩大支持范围。

解析后端	pipeline	*-auto-engine		*-http-client
		hybrid	vlm	hybrid	vlm
后端特性	兼容性好	配置要求较高		适用于OpenAI兼容服务器2
精度指标1	82+	90+
操作系统	Linux3 / Windows4 / macOS5
纯CPU平台支持	✅	❌		✅
GPU加速支持	Volta及以后架构GPU或Apple Silicon				不需要
显存最低要求	6GB	10GB	8GB	3GB
内存要求	最低16GB以上,推荐32GB以上			8GB
磁盘空间要求	20GB以上,推荐使用SSD			2GB
python版本	3.10-3.13

¹ 精度指标为OmniDocBench (v1.5)的End-to-End Evaluation Overall分数，基于MinerU最新版本测试
² 兼容OpenAI API的服务器，如通过vLLM/SGLang/LMDeploy等推理框架部署的本地模型服务器或远程模型服务
³ Linux仅支持2019年及以后发行版
⁴ 由于关键依赖ray未能在windows平台支持Python 3.13，故仅支持至3.10~3.12版本
⁵ macOS 需使用14.0以上版本

Tip

除以上主流环境与平台外，我们也收录了一些社区用户反馈的其他平台支持情况，详情请参考其他加速卡适配。
如果您有意将自己的环境适配经验分享给社区，欢迎通过show-and-tell提交或提交PR至其他加速卡适配文档。

安装 MinerU

使用pip或uv安装MinerU

pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple
pip install uv -i https://mirrors.aliyun.com/pypi/simple
uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple 

通过源码安装MinerU

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all] -i https://mirrors.aliyun.com/pypi/simple

Tip

mineru[all]包含所有核心功能，兼容Windows / Linux / macOS系统，适合绝大多数用户。 如果您需要指定vlm模型的推理框架，或是仅准备在边缘设备安装轻量版client端，可以参考文档扩展模块安装指南。

---

使用docker部署Mineru

MinerU提供了便捷的docker部署方式，这有助于快速搭建环境并解决一些棘手的环境兼容问题。 您可以在文档中获取Docker部署说明。

---

使用 MinerU

最简单的命令行调用方式:

mineru -p <input_path> -o <output_path>

您可以通过命令行、API、WebUI等多种方式使用MinerU进行PDF解析，具体使用方法请参考使用指南。

TODO

• 基于模型的阅读顺序
• 正文中目录、列表识别
• 表格识别
• 标题分级
• 手写文本识别
• 竖排文本识别
• 拉丁字母重音符号识别
• 正文中代码块识别
• 化学式识别(https://mineru.net)
• 图表内容识别

Known Issues

• 阅读顺序基于模型对可阅读内容在空间中的分布进行排序，在极端复杂的排版下可能会部分区域乱序
• 对竖排文字的支持较为有限
• 目录和列表通过规则进行识别，少部分不常见的列表形式可能无法识别
• 代码块在layout模型里还没有支持
• 漫画书、艺术图册、小学教材、习题尚不能很好解析
• 表格识别在复杂表格上可能会出现行/列识别错误
• 在小语种PDF上，OCR识别可能会出现字符不准确的情况（如阿拉伯文易混淆字符等）
• 部分公式可能会无法在markdown中渲染

FAQ

• 如果您在使用过程中遇到问题，可以先查看常见问题是否有解答。
• 如果未能解决您的问题，您也可以使用DeepWiki与AI助手交流，这可以解决大部分常见问题。
• 如果您仍然无法解决问题，您可通过Discord或WeChat加入社区，与其他用户和开发者交流。

All Thanks To Our Contributors

License Information

LICENSE.md

本项目目前部分模型基于YOLO训练，但因其遵循AGPL协议，可能对某些使用场景构成限制。未来版本迭代中，我们计划探索并替换为许可条款更为宽松的模型，以提升用户友好度及灵活性。

Acknowledgments

• PDF-Extract-Kit
• DocLayout-YOLO
• UniMERNet
• RapidTable
• TableStructureRec
• PaddleOCR
• PaddleOCR2Pytorch
• layoutreader
• xy-cut
• fast-langdetect
• pypdfium2
• pdftext
• pdfminer.six
• pypdf
• magika
• vLLM
• LMDeploy

Citation

@misc{niu2025mineru25decoupledvisionlanguagemodel,
      title={MinerU2.5: A Decoupled Vision-Language Model for Efficient High-Resolution Document Parsing}, 
      author={Junbo Niu and Zheng Liu and Zhuangcheng Gu and Bin Wang and Linke Ouyang and Zhiyuan Zhao and Tao Chu and Tianyao He and Fan Wu and Qintong Zhang and Zhenjiang Jin and Guang Liang and Rui Zhang and Wenzheng Zhang and Yuan Qu and Zhifei Ren and Yuefeng Sun and Yuanhong Zheng and Dongsheng Ma and Zirui Tang and Boyu Niu and Ziyang Miao and Hejun Dong and Siyi Qian and Junyuan Zhang and Jingzhou Chen and Fangdong Wang and Xiaomeng Zhao and Liqun Wei and Wei Li and Shasha Wang and Ruiliang Xu and Yuanyuan Cao and Lu Chen and Qianqian Wu and Huaiyu Gu and Lindong Lu and Keming Wang and Dechen Lin and Guanlin Shen and Xuanhe Zhou and Linfeng Zhang and Yuhang Zang and Xiaoyi Dong and Jiaqi Wang and Bo Zhang and Lei Bai and Pei Chu and Weijia Li and Jiang Wu and Lijun Wu and Zhenxiang Li and Guangyu Wang and Zhongying Tu and Chao Xu and Kai Chen and Yu Qiao and Bowen Zhou and Dahua Lin and Wentao Zhang and Conghui He},
      year={2025},
      eprint={2509.22186},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2509.22186}, 
}

@misc{wang2024mineruopensourcesolutionprecise,
      title={MinerU: An Open-Source Solution for Precise Document Content Extraction}, 
      author={Bin Wang and Chao Xu and Xiaomeng Zhao and Linke Ouyang and Fan Wu and Zhiyuan Zhao and Rui Xu and Kaiwen Liu and Yuan Qu and Fukai Shang and Bo Zhang and Liqun Wei and Zhihao Sui and Wei Li and Botian Shi and Yu Qiao and Dahua Lin and Conghui He},
      year={2024},
      eprint={2409.18839},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2409.18839}, 
}

@article{he2024opendatalab,
  title={Opendatalab: Empowering general artificial intelligence with open datasets},
  author={He, Conghui and Li, Wei and Jin, Zhenjiang and Xu, Chao and Wang, Bin and Lin, Dahua},
  journal={arXiv preprint arXiv:2407.13773},
  year={2024}
}

Star History

Links

• Easy Data Preparation with latest LLMs-based Operators and Pipelines
• Vis3 (OSS browser based on s3)
• LabelU (A Lightweight Multi-modal Data Annotation Tool)
• LabelLLM (An Open-source LLM Dialogue Annotation Platform)
• PDF-Extract-Kit (A Comprehensive Toolkit for High-Quality PDF Content Extraction)
• OmniDocBench (A Comprehensive Benchmark for Document Parsing and Evaluation)
• Magic-HTML (Mixed web page extraction tool)
• Magic-Doc (Fast speed ppt/pptx/doc/docx/pdf extraction tool)
• Dingo: A Comprehensive AI Data Quality Evaluation Tool