8268071fdc
- config.py: INTENT_MODEL 从 deepseek-v4-flash 切换至 mimo-v2.5 - config.py: get_intent_client() 从百炼 API 切换至 mimo API - RAG系统完整指南.md: v4.0→v4.1，新增图片检索子系统、P0安全网、 救援管线、五层缓存架构文档；替换所有旧模型名和API地址 - RAG数据流程.md: 完全重写，匹配实际代码逻辑 - curl测试手册.md: 更新模型名和Reranker配置 - MinerU模型部署指南.md: VLM_MODEL 更新为 mimo-v2.5 - 开发与系统模块说明.md: API地址和模型名更新 - 测试指南.md: API地址和模型名更新
550 lines
14 KiB
Markdown
550 lines
14 KiB
Markdown
# 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=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 检查模型路径
|
||
|
||
进入容器检查：
|
||
|
||
```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 服务开发组
|