# BM25混合检索功能使用指南

## 功能概述

本RAG系统现已支持三种检索模式：

1. **向量检索（vector）** - 基于语义相似度的密集向量检索
2. **BM25检索（bm25）** - 基于关键词匹配的稀疏检索
3. **混合检索（hybrid）** - 结合向量检索和BM25检索，提供更准确的结果

## 核心特性

### 🎯 中文分词支持
- 使用 `jieba` 进行中文分词
- 支持自定义停用词过滤
- 智能处理中英文混合文本

### 🔍 多种检索模式
- **纯向量检索**：适合语义理解和相似概念匹配
- **纯BM25检索**：适合精确关键词匹配和专业术语查找
- **混合检索**：结合两种方法的优势，提供最佳检索效果

### 💾 持久化存储
- BM25索引自动持久化到 `storage/bm25/` 目录
- 支持快速加载，无需重建索引

## 快速开始

### 1. 安装依赖

确保已安装所有必需的依赖包（已在 `requirements.txt` 中包含）：

```bash
pip install llama-index-retrievers-bm25
pip install PyStemmer
pip install jieba
```

### 2. 配置检索模式

在 `.env` 文件中配置默认检索模式：

```bash
# 检索模式：vector, bm25, hybrid
RETRIEVAL_MODE=hybrid

# BM25分词语言：chinese, english
BM25_LANGUAGE=chinese

# BM25检索的top_k
BM25_TOP_K=5
```

### 3. 构建索引

使用以下命令构建包含向量索引和BM25索引的完整索引：

```bash
python cli.py index --dir ./my_knowledge_base
```

构建过程会自动创建：
- 向量索引（存储在 `storage/`）
- BM25索引（存储在 `storage/bm25/`）

### 4. 查询知识库

#### 使用默认混合检索模式

```bash
python cli.py query --question "什么是RAG技术？"
```

#### 指定检索模式

**混合检索（推荐）**：
```bash
python cli.py query --question "什么是RAG技术？" --mode hybrid
```

**纯向量检索**：
```bash
python cli.py query --question "什么是RAG技术？" --mode vector
```

**纯BM25检索**：
```bash
python cli.py query --question "什么是RAG技术？" --mode bm25
```

#### 显示源文档

```bash
python cli.py query --question "什么是RAG技术？" --mode hybrid --sources
```

## 配置参数说明

### config.py 中的配置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `RETRIEVAL_MODE` | 检索模式：vector/bm25/hybrid | hybrid |
| `USE_BM25` | 是否启用BM25检索器 | True |
| `BM25_TOP_K` | BM25检索返回的文档数量 | 5 |
| `BM25_LANGUAGE` | 分词语言：chinese/english | chinese |
| `BM25_STORAGE_DIR` | BM25索引存储目录 | storage/bm25 |

## 检索模式对比

### 向量检索 (Vector)
✅ **优势**：
- 语义理解能力强
- 能匹配相似概念
- 适合模糊查询

❌ **劣势**：
- 对精确关键词匹配不够敏感
- 需要embedding计算

### BM25检索
✅ **优势**：
- 精确关键词匹配
- 速度快，无需embedding
- 适合专业术语查找

❌ **劣势**：
- 无法理解语义
- 对同义词不敏感

### 混合检索 (Hybrid) 🌟
✅ **优势**：
- 结合语义理解和关键词匹配
- 更全面的检索覆盖
- 提供最佳检索效果

❌ **劣势**：
- 计算开销略大（但仍然高效）

## 示例场景

### 场景1：概念性问题 - 推荐使用混合检索

```bash
python cli.py query --question "RAG技术的核心思想是什么？" --mode hybrid
```

### 场景2：精确术语查找 - 可使用BM25

```bash
python cli.py query --question "BM25算法" --mode bm25
```

### 场景3：语义相似查询 - 可使用向量检索

```bash
python cli.py query --question "如何提升模型性能" --mode vector
```

## 系统状态查看

查看索引状态（包括BM25索引）：

```bash
python cli.py status --verbose
```

输出示例：
```
索引状态:
============================================================
🔍 检索模式: hybrid

📊 向量索引:
  ✅ 已存在
  📁 存储类型: 本地
  📂 存储路径: D:\aigroup-rag-mcp\storage
  📄 文件数量: 6
  💾 加载状态: 未加载

📊 BM25索引:
  ✅ 已存在
  📂 存储路径: D:\aigroup-rag-mcp\storage\bm25
  🌐 分词语言: chinese
  💾 加载状态: 未加载
============================================================
```

## 技术实现

### 架构组件

1. **jieba_tokenizer.py** - 中文分词器
   - 支持中文jieba分词
   - 英文词干提取
   - 停用词过滤

2. **rag_system.py** - 核心检索逻辑
   - BM25检索器初始化
   - 混合检索器（QueryFusionRetriever）
   - 多模式查询支持

3. **config.py** - 配置管理
   - 检索模式配置
   - BM25参数配置

4. **cli.py** - 命令行界面
   - 支持 `--mode` 参数
   - 显示检索模式信息

## 常见问题

### Q1: 如何选择检索模式？
**A**: 建议默认使用 `hybrid` 混合检索模式，它结合了两种检索方法的优势。

### Q2: BM25支持中文吗？
**A**: 完全支持！系统使用jieba进行中文分词，针对中文文档优化。

### Q3: 混合检索会慢很多吗？
**A**: 不会。混合检索虽然结合了两种方法，但系统做了优化，查询时间仅略有增加。

### Q4: 可以只使用BM25而不用向量检索吗？
**A**: 可以。设置 `--mode bm25` 即可只使用BM25检索，无需embedding计算。

## 性能优化建议

1. **文档数量较少（<1000）**：使用混合检索
2. **文档数量较大（>10000）**：可考虑使用BM25进行初筛
3. **精确查询场景**：优先使用BM25
4. **语义理解场景**：优先使用向量检索

## 更新日志

### v2.0 (2026-01-08)
- ✅ 添加BM25检索器支持
- ✅ 实现混合检索（BM25 + 向量）
- ✅ 添加中文分词器（jieba）
- ✅ 支持多种检索模式切换
- ✅ BM25索引持久化存储

## 技术栈

- **LlamaIndex**: RAG框架
- **llama-index-retrievers-bm25**: BM25检索器
- **jieba**: 中文分词
- **PyStemmer**: 英文词干提取
- **bm25s**: BM25算法实现

## 贡献与反馈

如有问题或建议，欢迎提出Issue或Pull Request。

---

**Happy Retrieving! 🚀**
