rag/docs/模型统一管理方案.md

模型统一管理方案

将所有模型文件统一放在 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: 运行迁移脚本

# 激活虚拟环境
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: 验证迁移

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

# 检查配置文件
cat mineru.json

Step 3: 测试解析

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

---

三、配置文件说明

3.1 项目配置文件 mineru.json

位置：项目根目录 C:\Users\qq318\Desktop\rag-agent\mineru.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）：

# 使用本地模型
MINERU_MODEL_SOURCE=local

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

4.2 生产环境（Docker）

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

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

---

五、代码中的配置

5.1 config.py 配置

# 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 调用

# 第 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：

# 复制模型文件
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：

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

---

七、常见问题

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

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

# 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: 运行测试：

# 查看 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 已包含：

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

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

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

A: 提供两种方式：

方式 1：运行迁移脚本

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 服务开发组