一、项目简介MinerU 是一个面向PDF、图片及复杂文档解析的开源工具主要用于将非结构化文档转换为适合后续处理的结构化内容。它不仅能够进行 OCR还能够处理文档中的文字图片表格公式标题和段落结构文档版面信息最终可以输出 Markdown、JSON 等格式因此非常适合用于RAG 知识库构建、文档解析、数据清洗和 AI 应用。项目 GitHubhttps://github.com/opendatalab/MinerU官方文档MinerU - MinerU整体处理流程MinerU 的 VLM 模式可以使用 vLLM 作为推理引擎因此能够利用 GPU 加速文档解析。二、Docker 部署推荐使用 Docker 部署 MinerU这样可以避免 Python、CUDA、PyTorch、vLLM 等依赖之间产生环境冲突。1. 创建工作目录mkdir -p /home/mineru/{input,output,models,cache} cd /home/mineru目录结构/home/mineru/ ├── input/ ├── output/ ├── models/ └── cache/其中input/ 待解析文件 output/ 解析结果 models/ 模型文件 cache/ 缓存文件2. 检查 Docker GPU 环境如果使用 GPU 推理需要先确认 Docker 可以访问 NVIDIA GPUdocker run --rm --gpus all \ nvidia/cuda:13.0.0-base-ubuntu24.04 \ nvidia-smi能够正常显示 GPU 信息就说明 Docker GPU 环境已经配置完成。三、获取 MinerU Dockerfile进入 MinerU 工作目录cd /home/mineru下载官方 Dockerfilewget https://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/Dockerfile查看 Dockerfilehead -20 Dockerfile官方 Dockerfile 使用 vLLM 作为基础镜像例如FROM docker.m.daocloud.io/vllm/vllm-openai:v0.21.0因此 MinerU 容器内部已经包含 vLLM不需要另外安装一套 vLLM。四、构建 MinerU 镜像执行docker build \ --networkhost \ -t mineru:latest \ -f Dockerfile .构建完成后检查docker images | grep mineru看到mineru latest说明镜像构建完成。五、验证 MinerU 环境启动临时容器docker run --rm -it \ --gpus all \ --ipchost \ --shm-size32g \ mineru:latest \ /bin/bash检查 MinerUmineru --version检查 PyTorch 是否能够使用 GPUpython3 -c import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else NO GPU)正常情况下应该输出True GPU名称六、测试文档解析退出容器exit将测试 PDF 放入/home/mineru/input/test.pdf重新启动容器docker run --rm -it \ --gpus all \ --ipchost \ --shm-size32g \ -v /home/mineru/input:/input \ -v /home/mineru/output:/output \ mineru:latest \ /bin/bash执行解析mineru \ -p /input/test.pdf \ -o /output如果 GPU 显存比较紧张可以降低 MinerU 内部 vLLM 的显存使用比例mineru \ -p /input/test.pdf \ -o /output \ --gpu_memory_utilization 0.15其中--gpu_memory_utilization 0.15表示降低 vLLM 的 GPU 显存使用目标。解析过程中如果日志出现Using vllm-async-engine as the inference engine for VLM.说明 MinerU 当前正在使用 vLLM 作为 VLM 推理引擎。七、启动 HTTP 服务测试解析正常后可以将 MinerU 作为长期运行的 HTTP 服务。先删除已有的 MinerU 容器docker rm -f mineru 2/dev/null || true启动docker run -d \ --name mineru \ --restart unless-stopped \ --gpus all \ --ipchost \ --shm-size32g \ -p 8000:8000 \ -v /home/mineru/input:/input \ -v /home/mineru/output:/output \ -e MINERU_MODEL_SOURCEmodelscope \ mineru:latest \ mineru-api \ --host 0.0.0.0 \ --port 8000 \ --gpu_memory_utilization 0.15如果不需要限制显存可以根据实际资源情况调整--gpu_memory_utilization 0.2 --gpu_memory_utilization 0.3八、检查 HTTP 服务查看容器docker ps | grep mineru查看日志docker logs -f mineru正常情况下可以看到Application startup complete. Uvicorn running on http://0.0.0.0:8000检查健康状态curl http://127.0.0.1:8000/health也可以通过浏览器访问http://服务器地址:8000/docs/docs是 FastAPI 自动生成的 Swagger 接口文档可以直接查看当前版本支持的接口、参数以及请求格式。九、HTTP 调用将 MinerU 作为独立服务之后业务系统不需要再直接执行 MinerU 命令只需要通过 HTTP 调用即可。典型流程业务系统 ↓ HTTP MinerU API ↓ 文档解析 ↓ Markdown / JSON1. 查询服务状态curl http://127.0.0.1:8000/health2. 提交文档解析任务MinerU 提供任务接口可以通过 HTTP 提交文件。例如curl -X POST http://127.0.0.1:8000/tasks \ -F filestest.pdf服务返回任务信息后可以根据返回的task_id查询任务状态。3. 查询任务状态curl http://127.0.0.1:8000/tasks/{task_id}例如curl http://127.0.0.1:8000/tasks/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx4. 获取解析结果任务完成后curl http://127.0.0.1:8000/tasks/{task_id}/result最终得到 Markdown、JSON 或其他解析结果。具体请求参数和返回结构以当前版本的http://服务器地址:8000/docs为准。十、Python 调用示例业务系统可以直接使用 HTTP 调用 MinerU。import requests url http://服务器地址:8000/tasks with open(test.pdf, rb) as f: response requests.post( url, files{ files: (test.pdf, f, application/pdf) } ) print(response.status_code) print(response.text)如果返回任务 IDtask_id response.json()[task_id]继续查询status requests.get( fhttp://服务器地址:8000/tasks/{task_id} ) print(status.json())任务完成后获取结果result requests.get( fhttp://服务器地址:8000/tasks/{task_id}/result ) print(result.text)十一、在 RAG 中的使用MinerU 最典型的应用场景就是作为 RAG 的文档解析层。完整链路用户上传 PDF ↓ Java ↓ HTTP 调用 MinerU ↓ MinerU ↓ OCR / 版面分析 / 表格 / 公式 ↓ Markdown / JSON ↓ 文本清洗 ↓ Chunk ↓ Embedding ↓ Vector DB ↓ RAG这样可以将文档解析与RAG 业务完全解耦。Java 后端只需要知道 MinerU 的 HTTP 地址例如http://服务器地址:8000而不需要关心 MinerU 的 Python、PyTorch、vLLM 等底层运行环境。十二、常用 Docker 命令查看状态docker ps | grep mineru查看日志docker logs -f mineru重启docker restart mineru停止docker stop mineru启动docker start mineru删除docker rm -f mineru查看 GPUnvidia-smi十三、总结MinerU 的部署可以简单理解为Docker ↓ MinerU ↓ vLLM ↓ MinerU2.5 ↓ OCR / 文档解析部署完成后PDF / 图片 ↓ HTTP ↓ MinerU ↓ Markdown / JSON ↓ RAG对于 RAG 项目来说推荐将 MinerU 独立部署成一个文档解析服务。业务系统只负责通过 HTTP 上传文件、查询任务并获取解析结果从而实现文档解析与 RAG 业务的解耦。