100d1a06eb
- 后端 API（Flask + Gunicorn） - RAG 引擎（混合检索 + 云端 Reranker + 引用溯源） - 文档解析（MinerU + 多格式支持） - Docker 生产部署配置 - 排除前端项目、敏感配置、模型文件
285 lines
6.0 KiB
Markdown
285 lines
6.0 KiB
Markdown
# 模型统一管理方案
|
||
|
||
> 将所有模型文件统一放在 `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 服务开发组
|