MinerU项目快速使用指南：从命令行到高级功能
项目地址: https://gitcode.com/OpenDataLab/MinerU 项目概述
MinerU是一个强大的PDF和图像解析工具，支持多种后端处理引擎，能够帮助用户高效提取文档中的结构化信息。本文将详细介绍MinerU的多种使用方式，从基础命令行操作到高级API调用，帮助用户快速上手并充分发挥其功能。
基础配置
模型源设置
MinerU默认使用huggingface作为模型源，若因网络限制无法访问，可通过环境变量切换至modelscope：
export MINERU_MODEL_SOURCE=modelscope
对于需要完全离线使用的场景，MinerU还支持配置本地模型路径，只需在配置文件中指定模型目录即可。
命令行快速使用
基本解析命令
mineru -p <输入路径> -o <输出路径>
参数说明：
<输入路径>：支持单个PDF/图像文件或包含多个文件的目录<输出路径>：解析结果的输出目录
加速选项
MinerU会自动检测并尝试使用CUDA/MPS加速：
- Linux/macOS系统：自动启用加速
- Windows系统：需手动安装支持CUDA的PyTorch版本
指定后端引擎
mineru -p <输入路径> -o <输出路径> -b vlm-transformers
对于追求极致性能的用户，推荐使用sglang后端，可获得20-30倍的性能提升。安装方法详见扩展模块文档。
高级使用方式
Python API调用
开发者可直接在Python代码中调用MinerU的API，实现更灵活的集成和控制。
FastAPI服务
启动RESTful API服务：
mineru-api --host 0.0.0.0 --port 8000
启动后可通过浏览器访问http://127.0.0.1:8000/docs查看完整的API文档。
Web界面
启动Gradio可视化界面：
# 基础版本
mineru-gradio --server-name 0.0.0.0 --server-port 7860
# 启用sglang引擎版本
mineru-gradio --server-name 0.0.0.0 --server-port 7860 --enable-sglang-engine true
分布式处理架构
对于大规模处理需求，可采用sglang的client-server架构：
- 启动服务端：
mineru-sglang-server --port 30000
- 客户端连接：
mineru -p <输入路径> -o <输出路径> -b vlm-sglang-client -u http://127.0.0.1:30000
功能扩展配置
通过编辑用户目录下的mineru.json配置文件，可以扩展MinerU的功能：
-
LaTeX公式分隔符：修改
latex-delimiter-config可自定义公式识别符号 -
LLM辅助标题分级：配置
llm-aided-config启用大语言模型辅助分析，支持所有兼容OpenAI协议的模型 -
本地模型路径：通过
models-dir指定本地模型存储位置，配合环境变量MINERU_MODEL_SOURCE=local使用
性能优化建议
- 对于批量处理任务，推荐使用sglang后端
- 确保正确配置GPU加速环境
- 根据文档类型调整解析参数
- 对于固定格式文档，可自定义配置文件优化解析效果
常见问题
- 模型下载问题：可通过
mineru-models-download命令自动下载所需模型 - 加速不生效：检查CUDA环境和PyTorch版本
- 特殊格式支持：通过配置文件可扩展支持的文档格式
MinerU提供了灵活多样的使用方式，从简单的命令行工具到可编程API，再到分布式处理架构，能够满足不同场景下的文档解析需求。通过合理配置和优化，可以充分发挥其性能优势。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
