Skip to main content

【中级】部署 Mineru

更新日志​

版本日期变更描述
1.0.02026-02-09初始版本，包含在 MTT AIBOOK 上安装和部署 Mineru 的完整指南。

1. 项目简介​

本教程旨在指导开发者在 MTT AIBOOK 上部署并运行 Mineru，帮助您快速体验用 Mineru 批量转化复杂的 PDF 文件为 Markdown 格式。

Mineru 简介： MinerU 是一款功能强大的开源智能文档结构化解析工具，专为 AI 场景文档处理和高效信息提取设计。它整合了智能版面分析、多模态内容提取、多语言 OCR 识别和多格式精准输出等核心功能，支持 PDF、图片等多类型文档向 Markdown、JSON 等机器可读格式的高质量转换。

2. 前置条件​

在开始本教程之前，请确保您已满足以下所有条件：

  • 硬件:
    • AI 算力本 MTT AIBOOK，型号 A141
    • 网络连接（用于下载模型及依赖包）
    • 充足的存储空间（模型文件通常需要数 GB 到几十 GB 空间）
  • 软件:
    • MTT AIBOOK 操作系统 AIOS（1.3.3-B17）及以上版本

3. 环境部署​

本章节描述如何部署 Mineru 的环境。

3.1 检查并安装 Conda​

  1. 检查 Conda 是否已安装：

    conda --version

    若已安装则终端会返回类似下方这样的版本信息，您可以直接跳到 3.2 节：

    conda 25.11.1

  2. 安装 Conda：

    wget https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease/Miniforge3-Linux-aarch64.sh

    chmod +x Miniforge3-Linux-aarch64.sh

    ./Miniforge3-Linux-aarch64.sh
    # 安装过程中需要输入 `yes` 并回车确认安装路径，默认安装路径在 `/home/$User`。
    source ~/.bashrc  # 激活 conda

3.2 创建并激活 Conda 环境​

创建 Conda 虚拟环境：

conda create -n Mineru python=3.10
conda activate Mineru

请确保接下来的操作都是在激活 Mineru 虚拟环境后的操作，命令行前面应该有您创建的 conda 环境名字 (Mineru)。若没有可以执行以下命令激活：

conda activate Mineru

激活 Conda 环境

3.3 下载 Mineru 源码​

git clone https://github.com/opendatalab/MinerU.git

若无法从 GitHub 站点下载源码工程，可从 Gitee 站点下载：

git clone https://gitee.com/open-data-lab/MinerU.git

3.4 安装 Mineru 依赖​

进入 Mineru 源码文件夹安装相关依赖：

cd MinerU
pip install -e .[core] -i https://mirrors.aliyun.com/pypi/simple

确认安装依赖

3.5 安装 PyTorch 和 vLLM 来支持 MUSA 加速​

安装 Mineru 的依赖后，为适配 MUSA 算力加速，请按照以下步骤安装 MUSA 适配的 PyTorch 和 vLLM。

  1. 安装应用包：

    sudo apt update
    sudo apt install python3-pip git cmake wget build-essential g++ libstdc++-12-dev libnuma-dev

  2. 安装 torch_musa 和 vLLM 的相关依赖：

    wget -c https://mt-ai-data.tos-cn-shanghai.volces.com/vllm_musa/v1.2/release_1.3.0/20251011/release_1.3.0+vllm_musa+m1000_v1.2+torch2.1.0.tar.gz
    tar zxvf release_1.3.0+vllm_musa+m1000_v1.2+torch2.1.0.tar.gz
    cd release_1.3.0+vllm_musa+m1000_v1.2+torch2.1.0

    # 设置国内镜像源加速
    pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

    # 安装当前包内离线包
    pip install *.whl

    # 安装剩余依赖
    pip3 install -r requirements.txt
    pip install https://apollo-appstore-pre.tos-cn-beijing.volces.com/appstore/release/pip/torch_compat/torch_compat-1.0.0-cp310-cp310-linux_aarch64.whl

    # 为确保 numpy 版本是 1.26，防止前面依赖安装后自动更新 numpy 版本
    pip install numpy==1.26

  3. 验证 Torch 环境：

    python3 -c "import torch;import torch_musa;print(torch.musa.is_available())"

    预期输出：

    Torch环境

    True 证明 torch_musa 环境安装正确。

  4. 验证 vLLM 环境：

    python3 -c "from vllm_musa import _musa_custom_ops;_musa_custom_ops.decode_mla"

    预期输出：

    vLLM环境

    无报错即表示环境配置正确。

3.6 下载模型​

运行以下脚本：

mineru-models-download

建议选择 ModelScope（国内下载源更快）：

Please select the model download source: (huggingface, modelscope) [huggingface]: modelscope
Please select the model type to download: (pipeline, vlm, all) [all]: all
#自己选择源,直接回车默认是 huggingface

下载模型

4. 最佳实践​

本章节指导您完成 Mineru 的开发、配置和使用流程。

场景 1: 命令行启动 Mineru 的 Pipeline 模式解析对应文件夹的所有 PDF​

  1. 激活 Conda 虚拟环境：

    conda activate Mineru

  2. 准备好你想解析的 PDF 文件并执行以下命令：

    mineru -p ./pdfs/ -o ./output -b pipeline --source local -d musa:0

    参数说明：

    参数说明示例
    -p指定待解析的 PDF 文件/文件夹位置./pdfs/demo1.pdf 或 ./pdfs/
    -o指定结果输出位置./output
    -b指定启动模式pipeline
    --source模型来源local（本地已有模型）
    -d musa:0MUSA 加速参数不建议更改或删除

    执行后会看到下面类似输出：

    Pipeline 模式输出

  3. 结果展示：（后续场景使用中的结果与其类似）

    解析产物会存放在当前目录的 /output 文件夹内：(是上面 -o 对应的位置)。

    解析产物说明：

    产物说明示例
    *.mdMineru 解析后的 Markdown 文件demo2.md
    *_origin.pdf原始输入 PDF 的副本，方便对照检查demo2_origin.pdf
    *_span.pdf可视化调试文件，用细框标出最小粒度的文本/元素边界框demo2_span.pdf
    *_layout.pdf可视化调试文件，用色块标出识别到的版面结构demo2_layout.pdf
    images/存放从文档中提取的图片、公式截图、图表-
    • 解析产物一: Markdown 文件 Markdown 文件
    • 解析产物二：*_origin.pdf(*代表你通过 Mineru 选定的 PDF 文件名，后面出现类似格式)。 原始输入 PDF 的副本，方便对照检查解析结果 原始 PDF
    • 解析产物三：·*_span.pdf： 可视化调试文件，用细框标出最小粒度的文本 / 元素边界框，用排查识别问题： Layout 分析
    • 解析产物四：*_layout.pdf 可视化调试文件，用色块标出识别到的版面结构（标题、文本、图片、表格等）： Layout 解析结果
    • 解析产物五：images/ 存放的是从文档中提取的图片、公式截图、图表，与 *.md 中的图片引用关联提取的表格： 提取的表格

场景 2: Hybrid-Auto-Engine 模式​

与场景 1 类似，使用 -b 选择 hybrid-auto-engine 模式：

mineru -p ./pdfs/ -o ./output -b hybrid-auto-engine --source local -d musa:0

hybrid-auto-engine模式

结果展示请参考场景1。

场景 3: 命令行参数详解​

参数参数说明推荐/建议值
-p指定要分析的 PDF 文件路径，可以是包含多个 PDF 文件的文件夹路径按需填写实际的文件/文件夹路径
-o指定解析后产物的存放路径按需填写实际的存放路径
-b指定要启动的 Mineru 模式pipeline / hybrid-auto-engine
--source指定 Mineru 启动模型的位置local（本地已有模型，无需检验下载，节省时间）；模型更新后可选用 modelscope / huggingface
-d musa:0MUSA 加速参数不建议更改或删除

场景 4: FastAPI 方式调用​

  1. 设置环境变量

    export MINERU_MODEL_SOURCE=local
    export MINERU_DEVICE_MODE=musa:0
    export VLLM_USE_V1=1

  2. 执行命令启动服务

    mineru-api --host 0.0.0.0 --port 8000

    fastapi

    tip

    注意事项：

    • --port 是端口参数，可通过 sudo lsof -i:8000 来查询 8000 端口是否被占用。
    • 若占用则选择其他端口。

    host

  3. 访问对应网址 http://0.0.0.0:8000/docs

    FastAPI 文档

  4. 点击 try it out：

    tryitout

  5. 参数选择：

    • 选择对应的要解析的文件。
    • 设置 output_dir 为对应的输出目录。
    • 模式 backend 只推荐使用 pipeline 模式。

    参数选择

    运行时后台有相关日志，显示对应产出结果位置。 具体最终产出结果文件的意义参考场景一的结果展示。

场景 5: 启动Gradio WebUI 可视化前端​

  1. 配置环境变量：

    export MINERU_MODEL_SOURCE=local
    export MINERU_DEVICE_MODE=musa:0
    export VLLM_USE_V1=1

  2. 启动服务：

    mineru-gradio --server-name 0.0.0.0 --server-port 7860

    若 7860 端口被占用请选择其他端口。更多关于端口是否被占用，可参考场景四的注意事项。

    Mineru Gradio 界面

  3. 访问 WebUI：

    打开浏览器访问 http://0.0.0.0:7860。

    Mineru Gradio 界面

  4. 上传你要解析的 PDF：

    1. 上传你要解析的 PDF。
    2. 选择 hybrid-auto-engine 或者 pipeline 模式。
    3. 点击启用（vLLM 模式暂不支持）。

    解析结果：

    Mineru Demo UI

常用操作命令​

操作命令
检查 Condaconda --version
激活 Conda 环境conda activate Mineru
下载 Mineru 源码git clone https://gitee.com/open-data-lab/MinerU.git
安装 Mineru 依赖pip install -e .[core] -i https://mirrors.aliyun.com/pypi/simple
Pipeline 模式解析mineru -p ./pdfs/ -o ./output -b pipeline --source local -d musa:0
Hybrid 模式解析mineru -p ./pdfs/ -o ./output -b hybrid-auto-engine --source local -d musa:0
启动 FastAPI 服务mineru-api --host 0.0.0.0 --port 8000
启动 Gradio WebUImineru-gradio --server-name 0.0.0.0 --server-port 7860
下载模型mineru-models-download
查询端口占用sudo lsof -i:8000

5. 附录​

5.1 Mineru 亮点​

  1. 文档解析精准且全面：

    • 可高精度还原含合并单元格、跨页单元格的表格。
    • 输出标准 HTML 或 Markdown 格式以便后续分析。
    • 对文档中的数学公式，能精准转换为可编辑的 LaTeX 格式。

  2. 轻量化部署适配性广：

    • 基于仅 1.2B 参数量的模型构建。
    • 资源消耗低。

  3. 适配多元实用场景：

    • 能自动清理页眉、页脚、水印等干扰内容，提升提取内容的纯净度。
    • 输出格式丰富，包含 JSON、Markdown 等。

5.2 常见问题​

问题描述可能原因解决方案
依赖安装失败网络问题或 pip 源不可用1. 使用国内镜像源：pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple。
2. 检查网络连接。
NumPy 版本冲突NumPy 版本过高（2.x）与 PyTorch 不兼容安装指定版本：pip install numpy==1.26
Mineru 命令行模式启动过慢或报错网络问题或未添加指定的启动参数1. 检查网络连接。
2. 确认添加参数 -d musa:0 和参数 --source local
Mineru 的 Gradio 和 FastAPI 模式访问对应网址报错端口被占用，环境变量未添加1. 确保在当前命令行配置环境变量。
2. 切换其他端口，或者停掉对应端口服务

5.3 相关资源​

版权所有 2024 摩尔线程，本文档受国际版权法保护。

摩尔线程和摩尔线程徽标是摩尔线程智能科技 (北京)有限责任公司的注册商标。

免责声明

本文档提供有关摩尔线程产品的信息。本文档并未授权任何知识产权的许可，并未以明示或暗示，或以禁止反言或其他方式授予任何知识产权许可。