rag/docs/MinerU模型部署指南.md

MinerU 模型部署指南

解决服务器部署时的模型路径配置问题

---

一、当前配置分析

1.1 MinerU 模型路径机制

MinerU 通过以下方式确定模型路径：

# 1. 读取环境变量 MINERU_MODEL_SOURCE
model_source = os.getenv('MINERU_MODEL_SOURCE', "huggingface")

# 2. 如果是 local 模式，读取配置文件
if model_source == 'local':
    config = read_config()  # 读取 ~/mineru.json
    models_dir = config.get('models-dir')
    
# 3. 否则从 HuggingFace 自动下载到缓存目录
else:
    # 默认下载到 ~/.cache/huggingface/hub/
    pass

1.2 配置文件位置

MinerU 配置文件查找顺序：

1. 环境变量指定：MINERU_TOOLS_CONFIG_JSON
2. 默认位置：~/mineru.json（用户主目录）

Windows：C:\Users\<username>\mineru.json
Linux：/root/mineru.json 或 /home/<user>/mineru.json

1.3 MinerU 在线 API 模式

项目同时支持 MinerU 在线 API 解析，通过 .env.production 中的 MINERU_API_TOKEN 环境变量配置。当设置了该 Token 时，可直接调用 OpenDataLab 云端 API 进行文档解析，无需在本地部署模型。

1.4 当前项目使用方式

查看 parsers/mineru_parser.py 第 186-197 行：

cmd = [
    str(mineru_exe),
    "-p", str(file_path),
    "-o", str(output_dir),
    "-m", "auto",
    "-b", backend,
    "-l", lang,
    # ...
]

关键发现：

• 代码中没有硬编码路径
• 使用命令行调用 mineru 可执行文件
• MinerU 自动读取配置文件或环境变量
• 所有配置均通过 .env.production 环境变量注入，不依赖 config.py 硬编码

---

二、问题场景

场景 1：开发环境（本机）

模型位置：C:\Users\qq318\.cache\huggingface\hub\
配置文件：C:\Users\qq318\mineru.json（可能不存在）
模型来源：首次运行时自动从 HuggingFace 下载

场景 2：生产环境（服务器 Docker）

问题：
1. Docker 容器内用户目录是 /root/
2. 模型没有打包到镜像中
3. 首次启动会尝试下载模型（可能失败或很慢）

---

三、解决方案

方案 A：本地模型模式（推荐）

适用场景：

• 服务器无法访问 HuggingFace
• 需要离线部署
• 希望加快启动速度

Step 1：下载模型到项目目录

在本机执行：

# 激活虚拟环境
cd C:\Users\qq318\Desktop\rag-agent
venv\Scripts\activate

# 创建模型目录
mkdir models\mineru

# 下载所有模型
mineru-models-download -s huggingface -m all -d models\mineru

说明：

• -s huggingface：从 HuggingFace 下载
• -m all：下载所有模型（pipeline + vlm）
• -d models\mineru：指定下载目录

Step 2：创建配置文件

在项目根目录创建 mineru.json：

{
  "models-dir": {
    "pipeline": "/app/models/mineru/pipeline",
    "vlm": "/app/models/mineru/vlm"
  },
  "config_version": "1.3.1"
}

注意：路径使用 Docker 容器内的路径 /app/。

Step 3：生产环境 Dockerfile

当前项目使用 deploy/Dockerfile.prod（基于 Python 3.10-slim，CPU-only PyTorch）：

# Dockerfile.prod - 生产环境优化版
# ================================
# 特点：CPU-only、精简依赖、最小化镜像

FROM python:3.10-slim

WORKDIR /app

# 使用阿里云镜像源
RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources \
    && sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources

# 系统依赖（精简版）
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    poppler-utils \
    libmagic1 \
    curl \
    && rm -rf /var/lib/apt/lists/*

# ==================== PyTorch（CPU 模式） ====================
# 先从阿里云安装 PyTorch 依赖（避免从 PyPI 下载超时）
RUN pip install --no-cache-dir networkx sympy mpmath typing-extensions \
    -i https://mirrors.aliyun.com/pypi/simple/
# 再从 PyTorch 官方源下载 CPU-only 版本（约 200MB），跳过依赖解析
RUN pip install --no-cache-dir --no-deps torch --index-url https://download.pytorch.org/whl/cpu

# 设置 PyTorch 使用 CPU 模式
ENV CUDA_VISIBLE_DEVICES=""

# ==================== Python 依赖 ====================
COPY requirements-prod.txt .
RUN pip install --no-cache-dir -r requirements-prod.txt \
    -i https://mirrors.aliyun.com/pypi/simple/

# ==================== 应用代码 ====================
COPY . .

# ==================== MinerU 配置 ====================
# 生产环境使用本地模型
RUN mkdir -p /root && echo '{\n\
  "models-dir": {\n\
    "pipeline": "/app/models/mineru/pipeline",\n\
    "vlm": "/app/models/mineru/vlm"\n\
  },\n\
  "config_version": "1.3.1"\n\
}' > /root/mineru.json

ENV MINERU_MODEL_SOURCE=local
ENV MINERU_TOOLS_CONFIG_JSON=/root/mineru.json

# ==================== 数据目录 ====================
RUN mkdir -p knowledge/vector_store documents models .data

# ==================== 环境变量 ====================
ENV APP_ENV=prod
ENV PYTHONUNBUFFERED=1

EXPOSE 5001

# 生产模式启动
CMD ["gunicorn", "-c", "deploy/gunicorn.conf.py", "deploy.wsgi:app"]

Step 4：构建镜像

# 从项目根目录执行构建
docker-compose -f deploy/docker-compose.prod.yml up -d --build

# 或单独构建镜像
docker build -f deploy/Dockerfile.prod -t rag-service:latest .

# 查看镜像大小
docker images rag-service

预期镜像大小：约 5-8GB（包含模型）

---

方案 B：挂载模型目录（灵活）

适用场景：

• 多个容器共享模型
• 模型文件太大，不想打包到镜像
• 需要动态更新模型

Step 1：在服务器上准备模型

# 在服务器上创建模型目录
mkdir -p /data/mineru-models

# 方式1：从本机上传
scp -r models/mineru/* user@server:/data/mineru-models/

# 方式2：在服务器上下载
ssh user@server
cd /data/mineru-models
pip install mineru[all]
mineru-models-download -s huggingface -m all -d /data/mineru-models

Step 2：创建配置文件

在服务器上创建 /data/mineru.json：

{
  "models-dir": {
    "pipeline": "/models/pipeline",
    "vlm": "/models/vlm"
  },
  "config_version": "1.3.1"
}

Step 3：Docker Compose 配置

当前项目使用 deploy/docker-compose.prod.yml：

# docker-compose.prod.yml - 生产环境部署配置
version: '3.8'

services:
  rag-service:
    build:
      context: ..
      dockerfile: deploy/Dockerfile.prod
    container_name: rag-service
    env_file:
      - .env.production
    ports:
      - "5001:5001"
    volumes:
      # 数据目录挂载（代码在镜像内，不挂载）
      - ../knowledge/vector_store:/app/knowledge/vector_store
      - ../documents:/app/documents
      - ../models:/app/models
      - ../.data:/app/.data
      - ../data:/app/data
    restart: unless-stopped
    shm_size: '256m'
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 2G
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:5001/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

关键配置说明：

• env_file: .env.production：通过 .env.production 文件注入所有环境变量（包括 MINERU_API_TOKEN、DASHSCOPE_API_KEY 等），不使用 config.py 硬编码
• ../models:/app/models：将宿主机模型目录挂载到容器内，Dockerfile.prod 中已配置 MINERU_MODEL_SOURCE=local 和 MINERU_TOOLS_CONFIG_JSON=/root/mineru.json
• 端口映射 5001:5001，容器名为 rag-service

Step 4：启动服务

# 从项目根目录执行
docker-compose -f deploy/docker-compose.prod.yml up -d

---

方案 C：自动下载模式（不推荐）

适用场景：

• 服务器可以访问 HuggingFace
• 不介意首次启动慢

配置

# Dockerfile 不需要复制模型
# 首次启动时自动下载到 /root/.cache/huggingface/

# docker-compose.yml
services:
  rag-service:
    volumes:
      # 持久化模型缓存
      - mineru-cache:/root/.cache/huggingface
    environment:
      - MINERU_MODEL_SOURCE=huggingface  # 或不设置

volumes:
  mineru-cache:

缺点：

• 首次启动需要下载 5-8GB 模型
• 依赖网络连接
• 可能因为网络问题失败

---

四、环境变量配置（.env.production）

生产环境所有配置通过 deploy/.env.production 文件注入，不依赖 config.py 硬编码。

4.1 .env.production 示例

# .env.production - 生产环境配置
# 部署到服务器时复制到 deploy/.env.production

# 环境标识
APP_ENV=prod

# LLM API
DASHSCOPE_API_KEY=<your-api-key>
DASHSCOPE_BASE_URL=<your-base-url>
DASHSCOPE_MODEL=mimo-v2.5
RAG_CHAT_MODEL=mimo-v2.5
INTENT_MODEL=mimo-v2.5
VLM_MODEL=mimo-v2.5

# MinerU 在线 API（可选，设置后无需本地模型）
MINERU_API_TOKEN=<your-mineru-api-token>

# 网络搜索（按需开启）
ENABLE_WEB_SEARCH=false
SERPER_API_KEY=<your-serper-key>

# Rerank ONNX 加速（CPU 服务器建议关闭）
RERANK_USE_ONNX=false

4.2 MinerU 模型路径配置方式

方式	配置位置	说明
MINERU_API_TOKEN 环境变量	.env.production	使用 MinerU 云端 API，无需本地模型
mineru.json 配置文件	/root/mineru.json（容器内）	指定本地模型路径，Dockerfile.prod 已自动生成
MINERU_MODEL_SOURCE 环境变量	Dockerfile.prod 中设置	local 使用本地模型，huggingface 自动下载

---

五、验证部署

5.1 检查模型路径

进入容器检查：

# 进入容器
docker exec -it rag-service bash

# 检查配置文件
cat /root/mineru.json

# 检查模型目录
ls -lh /app/models/mineru/pipeline/
ls -lh /app/models/mineru/vlm/

# 测试 MinerU
python -c "from mineru.utils.config_reader import read_config; print(read_config())"

5.2 测试解析

# 在容器内测试
cd /app
python parsers/mineru_parser.py documents/test.pdf

5.3 查看日志

# 查看容器日志
docker logs -f rag-service

# 应该看到类似输出：
# [INFO] MinerU 配置: local 模式
# [INFO] 模型路径: /app/models/mineru/pipeline

---

六、模型文件清单

Pipeline 模型（必需）

models/mineru/pipeline/
├── Layout/
│   ├── model.pt
│   └── config.json
├── MFD/
│   ├── yolov8_mfd.pt
│   └── config.json
├── MFR/
│   ├── unimernet_small.pt
│   └── config.json
├── OCR/
│   ├── det_db.pth
│   ├── rec_crnn.pth
│   └── config.json
└── TableRec/
    ├── table_rec.pt
    └── config.json

总大小：约 3-4GB

VLM 模型（可选，高精度模式）

models/mineru/vlm/
├── qwen2-vl/
│   ├── model.safetensors
│   ├── config.json
│   └── tokenizer/
└── ...

总大小：约 4-5GB

---

七、常见问题

Q1: 镜像太大怎么办？

A: 使用方案 B（挂载模型目录），镜像只包含代码，模型在宿主机。

Q2: 如何更新模型？

A:

• 方案 A：重新构建镜像
• 方案 B：直接替换宿主机上的模型文件，重启容器

Q3: 模型下载失败怎么办？

A:

1. 使用国内镜像：export HF_ENDPOINT=https://hf-mirror.com
2. 手动下载后上传到服务器
3. 使用方案 A 在本机下载后打包

Q4: 如何减少模型大小？

A:

• 只下载 pipeline 模型（不下载 vlm）
• 使用 mineru-models-download -m pipeline 而不是 -m all

Q5: 配置文件不生效？

A: 检查：

1. 环境变量 MINERU_MODEL_SOURCE=local 是否设置
2. 配置文件路径是否正确：/root/mineru.json
3. 配置文件格式是否正确（JSON 语法）
4. 模型目录路径是否存在

Q6: 如何使用 MinerU 在线 API 代替本地模型？

A: 在 .env.production 中设置 MINERU_API_TOKEN=<your-token>，无需在本地部署模型。Token 可从 OpenDataLab 平台获取。

---

八、推荐方案总结

方案	优点	缺点	适用场景
方案 A：打包到镜像	部署简单、启动快	镜像大、更新麻烦	单机部署、离线环境
方案 B：挂载目录	灵活、易更新、多容器共享	需要管理宿主机文件	多节点、生产环境
方案 C：自动下载	镜像小	首次启动慢、依赖网络	测试环境
在线 API	无需本地模型、镜像最小	依赖网络、有调用限制	轻量部署、测试环境

生产环境推荐：方案 B（挂载模型目录）+ .env.production 环境变量注入

---

九、部署检查清单

部署前检查：

• 模型文件已下载到 models/mineru/ 目录
• 创建了 deploy/.env.production 配置文件（含 MINERU_API_TOKEN 等环境变量）
• 确认使用 deploy/Dockerfile.prod 和 deploy/docker-compose.prod.yml
• 测试了本地解析功能
• 确认模型文件大小（3-8GB）

部署后检查：

• 容器启动成功：docker ps | grep rag-service
• 配置文件存在：docker exec rag-service cat /root/mineru.json
• 模型目录存在：docker exec rag-service ls /app/models/mineru
• 环境变量正确：docker exec rag-service env | grep MINERU
• 健康检查通过：curl http://localhost:5001/health
• 测试解析功能：上传一个 PDF 测试
• 查看日志无错误：docker logs -f rag-service

---

文档版本: v1.1
最后更新: 2026-06-04
维护者: RAG 服务开发组