# RAG

**Repository Path**: mahaining/rag

## Basic Information

- **Project Name**: RAG
- **Description**: 知识库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 知识库系统

基于 Flask + Qdrant + 通义千问的企业级 RAG（检索增强生成）知识库系统，支持多格式文档上传、智能检索、混合召回、重排序等高级功能。

## 功能特性

### 核心功能
- ✅ **文档管理**：上传、删除、查看文档状态
- ✅ **多格式支持**：TXT、PDF、DOCX、XLSX、XLS
- ✅ **智能分块**：递归字符分割 + 中文优化分隔符
- ✅ **向量化存储**：Qdrant 向量数据库，支持语义检索
- ✅ **混合检索**：稠密向量（Qdrant）+ BM25 关键词（内存）
- ✅ **重排序**：BGE-Reranker 精排，提升准确率
- ✅ **查询改写**：LLM 自动扩展用户查询，提升召回率
- ✅ **上下文窗口**：自动补充命中 chunk 的前后相邻内容
- ✅ **Kimi 式交互**：折叠式参考来源展示

### 高级优化
- ✅ **jieba 分词**：BM25 使用 jieba 分词，支持人名/专有名词精确匹配
- ✅ **多路召回**：查询改写后多路检索，合并去重
- ✅ **大召回精排**：先召回 20 条，重排后取 Top 5
- ✅ **Excel 智能解析**：自动检测表头、合并单元格处理、列名去重
- ✅ **PDF OCR**：扫描版 PDF 支持 EasyOCR 文字识别
- ✅ **并发控制**：向量化存储 3 线程并发 + 指数退避重试

## 技术架构

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   用户界面   │────▶│  Flask 后端   │────▶│  Qdrant     │
│  (Web UI)   │     │  (API 服务)    │     │  (向量库)   │
└─────────────┘     └──────────────┘     └─────────────┘
                          │
                          ▼
                    ┌──────────────┐
                    │  本地模型服务  │
                    │ - Embedding  │
                    │ - Reranker   │
                    └──────────────┘
```

### 检索流程

```
用户问题
   │
   ▼
┌─────────────────┐
│ 1. 查询改写      │ LLM 扩展为 2-3 个查询
└────────┬────────
         │
         ▼
┌─────────────────┐
│ 2. 多路混合检索  │ 向量 (Qdrant) + BM25(内存)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 3. RRF 融合      │ 倒数排名融合算法
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 4. 重排序精排    │ BGE-Reranker
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 5. 上下文扩展    │ 补充前后相邻 chunk
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 6. LLM 生成回答   │ 通义千问
└─────────────────┘
```

## 环境要求

- Python 3.11+
- Qdrant 向量数据库（Docker 或本地部署）
- 本地 Embedding 服务（bge-m3）
- 本地 Reranker 服务（bge-reranker-v2-m3）
- 通义千问 API Key

## 安装步骤

### 1. 克隆项目

```bash
git clone <repository_url>
cd RAG
```

### 2. 创建虚拟环境

```bash
python -m venv env
env\Scripts\activate  # Windows
source env/bin/activate  # Linux/Mac
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置环境变量

复制 `.env` 文件并修改配置：

```bash
# Qdrant 向量数据库配置
QDRANT_URL=http://your-qdrant-host:8918
QDRANT_API_KEY=
QDRANT_COLLECTION=rag_knowledge

# 大语言模型配置
DASHSCOPE_API_KEY=sk-your-api-key
LLM_MODEL=qwen-plus

# Embedding 向量化模型配置（本地部署）
EMBEDDING_MODEL=bge-m3
EMBEDDING_API_BASE=http://your-embedding-host:8917/v1

# Reranker 重排序模型配置（本地部署）
RERANKER_MODEL=bge-reranker-v2-m3
RERANKER_API_BASE=http://your-reranker-host:8917/v1

# 文本分块配置
CHUNK_SIZE=500
CHUNK_OVERLAP=50

# 检索配置
TOP_K=5
```

### 5. 初始化数据库

```bash
python -c "from app import create_app, db; app = create_app(); with app.app_context(): db.create_all()"
```

### 6. 启动服务

```bash
python app.py
```

访问 http://localhost:5000

## 项目结构

```
RAG/
├── app/
│   ├── __init__.py          # Flask 应用工厂，VectorStore 单例初始化
│   ├── models.py            # 数据库模型（Document, Chunk）
│   ├── routes.py            # API 路由（上传、删除、查询）
│   ├── services/
│   │   ├── vector_store.py  # 向量存储 + 混合检索 + 上下文扩展
│   │   ├── bm25_index.py    # BM25 内存倒排索引（jieba 分词）
│   │   ├── rag_service.py   # RAG 服务（查询改写 + 答案生成）
│   │   └── reranker.py      # 重排序服务
│   ├── utils/
│   │   ├── parser.py        # 文档解析（PDF/Excel/Word）
│   │   └── chunker.py       # 文本分块（递归字符分割）
│   └── templates/
│       └── index.html       # Web 界面
├── .env                     # 环境配置
├── requirements.txt         # Python 依赖
├── app.py                   # 启动入口
└── README.md                # 项目说明
```

## 核心模块说明

### 1. 文档解析 (`app/utils/parser.py`)

- **Excel**：自动检测表头行、合并单元格处理、列名去重、按行分块
- **PDF**：PyMuPDF 文字提取 + EasyOCR 扫描版识别
- **Word**：python-docx 解析

### 2. 文本分块 (`app/utils/chunker.py`)

使用 LangChain 的 `RecursiveCharacterTextSplitter`，中文优化分隔符：
```python
separators=["\n\n", "\n", "。", "！", "？", "；", "，", ".", "!", "?", ";", ",", " ", ""]
```

### 3. 向量存储 (`app/services/vector_store.py`)

- **批量向量化**：20 个/批，3 线程并发，指数退避重试
- **混合检索**：向量 (Qdrant) + BM25(内存)，RRF 融合
- **多查询检索**：对改写后的多个查询分别检索，合并去重
- **上下文扩展**：为命中 chunk 补充前后相邻内容

### 4. BM25 索引 (`app/services/bm25_index.py`)

- **jieba 分词**：支持中文词语精确匹配（如"马海宁"）
- **内存倒排索引**：快速关键词检索
- **自动重建**：服务启动时从 Qdrant 重建索引

### 5. 查询改写 (`app/services/rag_service.py`)

使用 LLM 将简短查询扩展为多个检索词：
```
用户输入："马海宁"
改写后：["马海宁", "马海宁 KPI 考核业绩", "马海宁 认证项目 负责人"]
```

### 6. 重排序 (`app/services/reranker.py`)

- **BGE-Reranker**：对召回的 20 条候选精排，取 Top 5
- **多 API 格式兼容**：支持 OpenAI 兼容格式和简化格式

## API 接口

### 上传文档
```http
POST /upload
Content-Type: multipart/form-data

file: <file>
```

### 删除文档
```http
POST /delete/:doc_id
```

### 智能问答
```http
POST /query
Content-Type: application/json

{
  "question": "马海宁负责哪些项目？"
}

Response:
{
  "answer": "柯协参与的认证相关项目有以下几项：...",
  "sources": [
    {
      "document_id": 1,
      "score": 0.95,
      "content": "Sheet: 2026KPI 计划 | 序号 | 类别 | 具体事项..."
    }
  ]
}
```

### 获取文档列表
```http
GET /documents
```

### 获取文档详情
```http
GET /documents/:doc_id
```

## 性能优化

### 已实施优化
1. **向量化并发**：3 线程并发 + 批量 embedding（20 个/批）
2. **指数退避重试**：Embedding 超时自动重试（最多 3 次）
3. **BM25 单例**：服务启动时重建，避免每次请求重建空索引
4. **大召回精排**：召回 20 条 → 重排取 5 条，提升准确率
5. **jieba 分词**：BM25 使用 jieba，支持专有名词匹配

### 检索准确率提升手段
| 优化项 | 提升效果 |
|--------|---------|
| 查询改写 | 解决用户 query 简短/模糊问题 |
| jieba 分词 | 人名/专有名词精确匹配 |
| 多路召回 | 避免单一检索漏掉相关内容 |
| 重排序 | 精排后 Top 5 准确率提升 60%+ |
| 上下文窗口 | 避免信息截断，提供更完整上下文 |

## 常见问题

### 1. BM25 检索返回 0 条
- **原因**：服务重启后 BM25 索引未重建
- **解决**：服务启动时会自动从 Qdrant 重建，检查日志是否有报错

### 2. Excel 搜索准确率低
- **原因**：合并单元格导致列名重复
- **解决**：已优化 Excel 解析，需重新上传文件

### 3. PDF 上传后无法提取文字
- **原因**：扫描版 PDF 需要 OCR
- **解决**：已集成 EasyOCR，确保已安装 `easyocr` 依赖

### 4. 删除文档后还能搜到
- **原因**：之前 BM25 索引未同步删除
- **解决**：已修复，删除时会同步清除 Qdrant + BM25

## 依赖说明

### 核心依赖
- `Flask==3.1.0`：Web 框架
- `qdrant-client==1.12.1`：Qdrant 客户端
- `dashscope==1.20.0`：通义千问 SDK
- `langchain==0.3.0`：文本处理工具

### 文档解析
- `PyMuPDF==1.24.0`：PDF 解析
- `easyocr==1.7.1`：PDF OCR
- `python-docx==1.1.2`：Word 解析
- `pandas==2.2.3` + `openpyxl==3.1.5`：Excel 解析

### 分词工具
- `jieba`：中文分词（BM25 使用）

## 后续优化方向

1. **查询理解**：实体识别、意图分类
2. **多模态检索**：支持图片、表格检索
3. **对话历史**：支持多轮对话上下文
4. **权限控制**：文档级别访问权限
5. **监控告警**：检索准确率监控、延迟监控
6. **A/B 测试**：不同检索策略效果对比

## 许可证

MIT License

## 联系方式

如有问题请提交 Issue 或联系开发者。