init: RAG 知识库服务初始提交

- 后端 API（Flask + Gunicorn）
- RAG 引擎（混合检索 + 云端 Reranker + 引用溯源）
- 文档解析（MinerU + 多格式支持）
- Docker 生产部署配置
- 排除前端项目、敏感配置、模型文件

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

@@ -0,0 +1,284 @@
+# 模型统一管理方案
+
+> 将所有模型文件统一放在 `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 服务开发组