# 水利智学・本地 RAG 引擎 — 完整安装与使用说明

## 一、组件清单（全部已安装，一个不缺）



| 组件                    | 版本                  | 用途                                       | 状态   |
| --------------------- | ------------------- | ---------------------------------------- | ---- |
| **MinerU**            | 4.0.10              | 扫描件 OCR：教材双栏 / 公式→LaTeX / 自动去页眉页脚 / 图片提取 | ✅ 已装 |
| **BGE-M3**            | FlagEmbedding 1.4.2 | 稠密 + 稀疏 (BM25) 混合嵌入，1024 维，8192 上下文      | ✅ 已装 |
| **BGE-Reranker-base** | FlagEmbedding 1.4.2 | 交叉编码器重排，过滤 OCR 噪声垃圾块                     | ✅ 已装 |
| **Qdrant**            | client 1.19.1       | 本地嵌入模式向量库（无需 Docker），支持稠密 + 稀疏混合检索       | ✅ 已装 |
| **CLIP**              | transformers 内置     | 多模态图文检索，教材插图 / 原理图 / 表格单独建索引             | ✅ 已装 |
| **Ollama**            | 便携版                 | 本地 LLM 推理（qwen2.5:7b），复用现有               | ✅ 已有 |

## 二、硬件适配



* **当前机器**：i5-12500H + 16G 内存 + Intel Iris Xe 核显（**无 NVIDIA GPU**）

* **运行模式**：全部组件走 **CPU 推理**，torch 线程限制为 4，防内存溢出

* **性能预期**：


  * MinerU OCR：约 5-15 秒 / 页（CPU 模式，建议分批处理）

  * BGE-M3 嵌入：约 0.5-2 秒 / 块（批量 4 条）

  * Reranker 重排：约 0.3 秒 / 对

  * Qdrant 检索：<100ms

  * LLM 回答：qwen2.5:7b CPU 约 10-30 秒 / 题

* **模型缓存**：`backend/ai_models/`（首次使用自动下载，约 2GB，随软件迁移）

## 三、完整流水线

### 索引阶段（扫描教材）



```
扫描PDF
  ↓ MinerU OCR（版面分析+公式识别+图片提取）
结构化Markdown + 裁剪图片 + LaTeX公式
  ↓ 文本清洗（去乱码/合并断句/保留LaTeX/删页码页眉）
  ↓ 父子语义分块（按标题切，子块600token检索，父块1800token送LLM，重叠150token）
  ↓ BGE-M3 稠密+稀疏混合嵌入
  ↓ 存入 Qdrant（子块建索引，父块完整文本存payload）
  ↓ CLIP 图片嵌入 → 存入 Qdrant 图片集合
```

### 问答阶段



```
用户提问
  ↓ BGE-M3 生成 query 稠密+稀疏向量
  ↓ Qdrant Hybrid 检索 top10（稠密0.6 + 稀疏0.4 加权融合）
  ↓ BGE-Reranker 重排，筛选 top3
  ↓ 取出 top3 对应的【父块完整章节】（子块→父块回溯）
  ↓ CLIP 图文联合检索（涉及图时可选）
  ↓ 本地 Ollama LLM（qwen2.5:7b），结合教材原文回答
```

## 四、API 端点

所有端点前缀：`http://localhost:8000/api/rag`



| 方法       | 端点               | 用途                                            |
| -------- | ---------------- | --------------------------------------------- |
| `POST`   | `/index-pdf`     | 索引扫描教材 PDF（上传文件，完整 OCR→分块→嵌入→入库）              |
| `POST`   | `/index-text`    | 索引纯文本 / 讲义                                    |
| `POST`   | `/query`         | 一键问答（检索 + 重排 + LLM 回答）                        |
| `POST`   | `/retrieve`      | 纯检索（不调用 LLM，返回上下文，调试用）                        |
| `GET`    | `/status`        | 各组件状态（MinerU/BGE-M3/Reranker/Qdrant/CLIP/ 设备） |
| `GET`    | `/sources`       | 已索引来源列表                                       |
| `DELETE` | `/source/{name}` | 删除指定来源的索引（重新索引用）                              |

### 调用示例



```
# 查看组件状态
curl http://localhost:8000/api/rag/status

# 索引扫描教材PDF
curl -X POST http://localhost:8000/api/rag/index-pdf \
  -F "file=@水利工程经济评价.pdf" \
  -F "enable_clip=true"

# 提问
curl -X POST http://localhost:8000/api/rag/query \
  -H "Content-Type: application/json" \
  -d '{"question": "什么是资金时间价值？", "enable_image": false}'
```

## 五、关键设计决策

### 1. 为什么用 Qdrant 本地嵌入模式而不是 Docker？



* 本机无 Docker，Qdrant-client 支持 `path=` 本地嵌入模式，零依赖启动

* 数据持久化到 `backend/data/qdrant_local/`，随软件迁移

* 支持稠密向量 + 稀疏向量 + payload 过滤 + RRF 混合融合

### 2. 为什么用父子块策略？



* 子块（600token）：粒度细，检索精度高，用于 embedding

* 父块（1800token）：完整小节，语义完整，最终送 LLM

* 子块记录 parent\_id，检索到子块后回溯取完整父块

* 避免固定长度粗暴切割切断定义 / 公式 / 例题

### 3. 为什么必须有 Reranker？



* OCR 文本自带噪声（错字、断行、页眉残留）

* 向量检索 top10 中可能混入垃圾块

* Reranker 用交叉编码器对 (query, passage) 逐对打分，精度远高于向量相似度

* 轻量 base 模型，CPU 可跑

### 4. 优雅降级链



* BGE-M3 不可用 → 降级现有 Ollama bge-small-zh + SQLite semantic\_store

* Reranker 不可用 → 跳过重排，取原始 top\_n

* Qdrant 不可用 → 降级现有检索

* MinerU 不可用 → 降级 PyMuPDF 文本提取（非扫描 PDF）

* CLIP 不可用 → 跳过图片检索

## 六、文件结构



```
backend/modules/rag_engine/
├── __init__.py          # 模块入口
├── config.py            # 统一配置（路径/模型名/超参数）
├── ocr_mineru.py        # MinerU OCR 扫描件识别管线
├── text_cleaner.py      # OCR 文本清洗（去乱码/合并断句/保留LaTeX）
├── chunking.py          # 父子语义分块（按标题切+重叠）
├── embedding_bgem3.py   # BGE-M3 稠密+稀疏混合嵌入
├── reranker_bge.py      # BGE-Reranker-base 重排
├── vector_qdrant.py     # Qdrant 本地向量库（混合检索）
├── multimodal_clip.py   # CLIP 多模态图文检索
├── pipeline.py          # 端到端 RAG 流水线（索引+问答统一入口）
└── routes.py            # FastAPI 路由（/api/rag/*）

backend/data/
├── qdrant_local/        # Qdrant 向量库持久化
├── mineru_output/       # MinerU OCR 输出（markdown+图片）
└── ai_models/           # 模型缓存（BGE-M3/Reranker/CLIP，首次自动下载）

requirements-ai.txt      # AI组件依赖清单
install_ai_components.bat # 一键安装脚本
```

## 七、避坑清单（已在代码中处理）



* ✅ 不直接把 OCR 原始文本入库 → 必须清洗（text\_cleaner.py）

* ✅ 不用大 chunk 直接 embedding → 子块 600token，父块 1800token

* ✅ 不跳过 Reranker → OCR 噪声场景下提升明显

* ✅ 不用纯 BM25 检索 → BGE-M3 混合检索（稠密 + 稀疏）

* ✅ 不一次性丢整本教材给 MinerU → 分批 20 页处理（batch\_pages）

* ✅ LaTeX 公式不删除 → 清洗时用占位符保护

* ✅ OCR 断句合并 → 清洗时自动合并被分页打断的句子

* ✅ 内存溢出防护 → torch 线程限制 4，批量小，模型懒加载

## 八、首次使用步骤



1. **启动系统**：双击 `start.bat`（AI 组件已预装，自动跳过安装）

2. **查看状态**：浏览器访问 `http://localhost:8000/api/rag/status`，确认 5 个组件全部 available

3. **索引教材**：调用 `POST /api/rag/index-pdf` 上传扫描 PDF（首次会自动下载 BGE-M3 等模型，约 2GB）

4. **开始问答**：调用 `POST /api/rag/query` 提问

> **注意**
>
> ：首次索引时模型下载需要网络，后续完全离线可用。模型缓存于 
>
> `backend/ai_models/`
>
> 。