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

# MinerU 模型部署指南

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

---

## 一、当前配置分析

### 1.1 MinerU 模型路径机制

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

```python
# 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 行：

```python
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：下载模型到项目目录

在**本机**执行：

```bash
# 激活虚拟环境
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`：

```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
# 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：构建镜像

```bash
# 从项目根目录执行构建
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：在服务器上准备模型

```bash
# 在服务器上创建模型目录
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`：

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

#### Step 3：Docker Compose 配置

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

```yaml
# 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：启动服务

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

---

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

**适用场景**：
- 服务器可以访问 HuggingFace
- 不介意首次启动慢

#### 配置

```dockerfile
# 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 示例

```bash
# .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=qwen-vl-plus

# 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 检查模型路径

进入容器检查：

```bash
# 进入容器
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 测试解析

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

### 5.3 查看日志

```bash
# 查看容器日志
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 服务开发组