# 模型统一管理方案

> 将所有模型文件统一放在 `models/` 目录下，便于管理和部署

---

## 一、当前模型目录结构

```
models/
├── bge-base-zh-v1.5/          # BGE 向量模型（已存在）
├── bge-reranker-base/         # BGE 重排序模型（已存在）
└── mineru/                    # MinerU 解析模型（需迁移）
    ├── pipeline/              # Pipeline 模式模型
    │   ├── Layout/
    │   ├── MFD/
    │   ├── MFR/
    │   ├── OCR/
    │   └── TableRec/
    └── vlm/                   # VLM 高精度模式模型
        └── ...
```

---

## 二、迁移步骤

### Step 1: 运行迁移脚本

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

# 运行迁移脚本
python scripts/migrate_mineru_models.py
```

**脚本功能**：
1. 读取当前 `~/mineru.json` 配置
2. 从 HuggingFace 缓存复制模型到 `models/mineru/`
3. 更新配置文件指向新路径
4. 验证迁移结果

### Step 2: 验证迁移

```bash
# 检查模型目录
ls models/mineru/pipeline
ls models/mineru/vlm

# 检查配置文件
cat mineru.json
```

### Step 3: 测试解析

```bash
# 测试 MinerU 解析
python parsers/mineru_parser.py documents/test.pdf
```

---

## 三、配置文件说明

### 3.1 项目配置文件 `mineru.json`

**位置**：项目根目录 `C:\Users\qq318\Desktop\rag-agent\mineru.json`

**内容**：
```json
{
  "models-dir": {
    "pipeline": "C:\\Users\\qq318\\Desktop\\rag-agent\\models\\mineru\\pipeline",
    "vlm": "C:\\Users\\qq318\\Desktop\\rag-agent\\models\\mineru\\vlm"
  },
  "config_version": "1.3.1"
}
```

**说明**：
- 使用**绝对路径**指向项目内模型
- 开发环境使用此配置
- 不提交到 Git（已加入 `.gitignore`）

### 3.2 用户配置文件 `~/mineru.json`

**位置**：`C:\Users\qq318\mineru.json`

**说明**：
- 迁移后会自动更新
- 与项目配置保持一致
- 系统级配置，影响所有 MinerU 调用

### 3.3 配置文件模板 `mineru.json.template`

**位置**：项目根目录

**用途**：
- 提供配置文件示例
- 部署时复制并修改路径
- 提交到 Git 供团队参考

---

## 四、环境变量配置

### 4.1 开发环境

在项目根目录创建 `.env` 文件（或使用 `.env.mineru`）：

```bash
# 使用本地模型
MINERU_MODEL_SOURCE=local

# 配置文件路径（相对于项目根目录）
MINERU_TOOLS_CONFIG_JSON=mineru.json
```

### 4.2 生产环境（Docker）

在 `docker-compose.yml` 或 Dockerfile 中设置：

```yaml
environment:
  - MINERU_MODEL_SOURCE=local
  - MINERU_TOOLS_CONFIG_JSON=/root/mineru.json
```

---

## 五、代码中的配置

### 5.1 `config.py` 配置

```python
# MinerU 模型路径（重要：部署时需要配置）
MINERU_MODELS_DIR = os.getenv(
    "MINERU_MODELS_DIR",
    os.path.join(PROJECT_ROOT, "models", "mineru")  # 默认使用项目内路径
)
```

**说明**：
- 优先使用环境变量 `MINERU_MODELS_DIR`
- 默认使用项目内 `models/mineru/`
- 此配置会被 `mineru.json` 覆盖（MinerU 优先读取配置文件）

### 5.2 `parsers/mineru_parser.py` 调用

```python
# 第 186-197 行
cmd = [
    str(mineru_exe),
    "-p", str(file_path),
    "-o", str(output_dir),
    "-m", "auto",
    "-b", backend,
    "-l", lang,
    # ...
]
```

**说明**：
- 使用命令行调用 `mineru` 可执行文件
- MinerU 自动读取配置文件 `~/mineru.json`
- 无需在代码中指定模型路径

---

## 六、部署配置

### 6.1 Docker 镜像构建

**Dockerfile**：

```dockerfile
# 复制模型文件
COPY models /app/models

# 复制配置文件（使用绝对路径）
COPY mineru.json.template /root/mineru.json

# 修改配置文件中的路径为容器内路径
RUN sed -i 's|C:\\\\Users\\\\qq318\\\\Desktop\\\\rag-agent|/app|g' /root/mineru.json

# 设置环境变量
ENV MINERU_MODEL_SOURCE=local
ENV MINERU_TOOLS_CONFIG_JSON=/root/mineru.json
```

### 6.2 生产环境配置文件

**容器内 `/root/mineru.json`**：

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

---

## 七、常见问题

### Q1: 迁移后原来的缓存可以删除吗？

**A**: 可以。迁移完成后，可以删除 HuggingFace 缓存以节省空间：

```bash
# Windows
rmdir /s "C:\Users\qq318\.cache\huggingface\hub\models--opendatalab--PDF-Extract-Kit-1.0"
rmdir /s "C:\Users\qq318\.cache\huggingface\hub\models--opendatalab--MinerU2.5-2509-1.2B"
```

### Q2: 如何验证配置是否生效？

**A**: 运行测试：

```bash
# 查看 MinerU 读取的配置
python -c "from mineru.utils.config_reader import read_config; import json; print(json.dumps(read_config(), indent=2))"

# 测试解析
python parsers/mineru_parser.py documents/test.pdf
```

### Q3: 配置文件路径优先级？

**A**: MinerU 配置文件查找顺序：

1. 环境变量 `MINERU_TOOLS_CONFIG_JSON` 指定的路径
2. 当前目录 `./mineru.json`
3. 用户主目录 `~/mineru.json`

### Q4: 模型文件太大，Git 提交失败？

**A**: 确认 `.gitignore` 已包含：

```gitignore
# 模型文件（需单独下载）
models/
```

模型文件不应提交到 Git，部署时单独处理。

### Q5: 团队其他成员如何配置？

**A**: 提供两种方式：

**方式 1：运行迁移脚本**
```bash
python scripts/migrate_mineru_models.py
```

**方式 2：手动配置**
1. 下载模型到 `models/mineru/`
2. 复制 `mineru.json.template` 为 `mineru.json`
3. 修改路径为本机绝对路径

---

## 八、检查清单

迁移完成后检查：

- [ ] `models/mineru/pipeline/` 目录存在且包含模型文件
- [ ] `models/mineru/vlm/` 目录存在且包含模型文件
- [ ] `mineru.json` 配置文件存在且路径正确
- [ ] `~/mineru.json` 已更新为新路径
- [ ] `.gitignore` 包含 `mineru.json`
- [ ] 测试解析功能正常
- [ ] 模型总大小约 3-8GB

---

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