# RAG-MCP 功能增强实施文档

> **实施日期**: 2026-01-09  
> **基于指南**: [`RAG_MCP_Enhancement_Guide.md`](../plans/RAG_MCP_Enhancement_Guide.md)  
> **实施状态**: ✅ 已完成

---

## 📋 目录

- [概述](#概述)
- [已实施功能](#已实施功能)
- [配置说明](#配置说明)
- [MCP工具更新](#mcp工具更新)
- [使用示例](#使用示例)
- [安装依赖](#安装依赖)
- [注意事项](#注意事项)

---

## 🎯 概述

本次增强基于LlamaIndex生态系统，为RAG-MCP项目新增了以下核心功能：

1. **后处理器支持** - 相似度过滤、多样性优化
2. **Reranker集成** - Cohere、SentenceTransformer、Flag Embedding
3. **元数据过滤** - 支持8种操作符的精确过滤
4. **增量索引管理** - 插入、更新、删除文档
5. **批量异步查询** - 高效处理多个查询请求

---

## ✅ 已实施功能

### Phase 1: 配置系统增强

**文件**: [`src/config/settings.py`](../src/config/settings.py)

**新增配置项**:

```python
class RetrievalConfig(BaseModel):
    # Postprocessor配置
    use_similarity_filter: bool = False
    similarity_cutoff: float = 0.3
    use_optimizer: bool = False
    optimizer_percentile: float = 0.5
    optimizer_threshold: float = 0.7
    
    # Reranker配置
    use_reranker: bool = False
    reranker_type: str = "sentence-transformer"
    reranker_model: str = "cross-encoder/ms-marco-MiniLM-L-2-v2"
    reranker_top_n: int = 5
    cohere_api_key: SecretStr = SecretStr("")
    
    # 元数据过滤
    enable_metadata_filters: bool = True
```

**环境变量**:

```bash
# Postprocessor配置
USE_SIMILARITY_FILTER=True
SIMILARITY_CUTOFF=0.3
USE_OPTIMIZER=False
OPTIMIZER_PERCENTILE=0.5
OPTIMIZER_THRESHOLD=0.7

# Reranker配置
USE_RERANKER=True
RERANKER_TYPE=sentence-transformer
RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-2-v2
RERANKER_TOP_N=5
COHERE_API_KEY=your-cohere-api-key

# 元数据过滤
ENABLE_METADATA_FILTERS=True
```

---

### Phase 2: 查询引擎增强

**文件**: [`src/core/query_engine.py`](../src/core/query_engine.py)

**新增方法**:

1. **`_create_postprocessors()`** - 创建后处理器链
   - `SimilarityPostprocessor` - 相似度阈值过滤
   - `SentenceEmbeddingOptimizer` - 多样性优化

2. **`_create_reranker()`** - 创建重排序器
   - Cohere Rerank（商业级）
   - SentenceTransformer Rerank（免费本地）
   - Flag Embedding Reranker（中文优化）

3. **`_create_metadata_filters()`** - 创建元数据过滤器
   - 支持8种操作符：EQ, NE, GT, LT, GTE, LTE, IN, NIN, CONTAINS

4. **`batch_query_async()`** - 异步批量查询
   - 使用`asyncio.gather`并发处理

**增强的方法签名**:

```python
def create_query_engine(
    self,
    index: VectorStoreIndex,
    mode: Optional[str] = None,
    top_k: Optional[int] = None,
    metadata_filters: Optional[Dict] = None,
    similarity_cutoff: Optional[float] = None,
    use_reranker: Optional[bool] = None
)
```

---

### Phase 3: 增量索引管理

**文件**: [`src/core/index_manager.py`](../src/core/index_manager.py)

**新增方法**:

1. **`insert_documents()`** - 插入新文档
   ```python
   result = index_manager.insert_documents(index, documents)
   ```

2. **`update_documents()`** - 更新文档
   ```python
   result = index_manager.update_documents(index, documents)
   ```

3. **`delete_document()`** - 删除文档
   ```python
   result = index_manager.delete_document(index, doc_id)
   ```

4. **`get_document()`** - 获取文档
   ```python
   result = index_manager.get_document(index, doc_id)
   ```

5. **`list_all_documents()`** - 列出所有文档
   ```python
   result = index_manager.list_all_documents(index)
   ```

6. **`_sync_bm25_index()`** - 同步BM25索引
   - 自动在增量操作后同步BM25索引

---

### Phase 4: RAG系统核心增强

**文件**: [`src/core/rag_system.py`](../src/core/rag_system.py)

**新增方法**:

1. **`batch_query()`** - 批量查询
2. **`insert_documents()`** - 插入文档
3. **`update_documents()`** - 更新文档
4. **`delete_document()`** - 删除文档
5. **`get_document()`** - 获取文档
6. **`list_documents()`** - 列出文档

**增强的方法**:

```python
def retrieve(
    self, 
    question: str, 
    top_k: Optional[int] = None, 
    mode: Optional[str] = None,
    similarity_cutoff: Optional[float] = None,
    use_reranker: Optional[bool] = None,
    metadata_filters: Optional[Dict] = None
) -> dict
```

---

### Phase 5: 服务层增强

**文件**: [`src/services/rag_service.py`](../src/services/rag_service.py)

**新增服务方法**:

1. **`batch_retrieve()`** - 批量检索服务
2. **`insert_documents()`** - 插入文档服务
3. **`update_documents()`** - 更新文档服务
4. **`delete_document()`** - 删除文档服务
5. **`get_document()`** - 获取文档服务
6. **`list_documents()`** - 列出文档服务

---

### Phase 6: MCP工具更新

**文件**: [`src/mcp/handlers/tools_handler.py`](../src/mcp/handlers/tools_handler.py)

**新增MCP工具**:

1. **`batch_retrieve`** - 批量异步检索
2. **`insert_documents`** - 插入文档
3. **`update_documents`** - 更新文档
4. **`delete_document`** - 删除文档
5. **`list_documents`** - 列出文档
6. **`get_document`** - 获取文档

**增强的现有工具**:

- **`retrieve_documents`** - 新增参数：
  - `similarity_cutoff` - 相似度阈值
  - `use_reranker` - 是否使用重排序
  - `metadata_filters` - 元数据过滤条件

---

## 🔧 配置说明

### 基本配置

创建或更新 `.env` 文件：

```bash
# 启用相似度过滤
USE_SIMILARITY_FILTER=True
SIMILARITY_CUTOFF=0.3

# 启用重排序（推荐）
USE_RERANKER=True
RERANKER_TYPE=sentence-transformer
RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-2-v2
RERANKER_TOP_N=5

# 如果使用Cohere（需要API Key）
# RERANKER_TYPE=cohere
# COHERE_API_KEY=your-api-key-here
```

### 推荐配置组合

#### 1. 基础增强（无需额外依赖）

```bash
USE_SIMILARITY_FILTER=True
SIMILARITY_CUTOFF=0.3
USE_RERANKER=False
```

#### 2. 本地重排序（推荐）

```bash
USE_SIMILARITY_FILTER=True
SIMILARITY_CUTOFF=0.2
USE_RERANKER=True
RERANKER_TYPE=sentence-transformer
RERANKER_TOP_N=5
```

#### 3. 商业级质量（需要Cohere API）

```bash
USE_SIMILARITY_FILTER=True
SIMILARITY_CUTOFF=0.2
USE_OPTIMIZER=True
USE_RERANKER=True
RERANKER_TYPE=cohere
COHERE_API_KEY=your-api-key
RERANKER_TOP_N=5
```

#### 4. 中文优化

```bash
USE_SIMILARITY_FILTER=True
SIMILARITY_CUTOFF=0.3
USE_RERANKER=True
RERANKER_TYPE=flag-embedding
RERANKER_TOP_N=5
```

---

## 📦 MCP工具更新

### 新增工具列表

总工具数：**12个** （原6个 + 新增6个）

| 工具名称 | 功能描述 | 类型 |
|---------|---------|------|
| `batch_retrieve` | 批量异步检索 | 新增 |
| `insert_documents` | 插入新文档 | 新增 |
| `update_documents` | 更新文档 | 新增 |
| `delete_document` | 删除文档 | 新增 |
| `list_documents` | 列出所有文档 | 新增 |
| `get_document` | 获取文档详情 | 新增 |
| `retrieve_documents` | 检索文档（增强） | 增强 |

---

## 💡 使用示例

### 1. 基础相似度过滤检索

```python
# MCP工具调用
{
    "tool": "retrieve_documents",
    "arguments": {
        "question": "什么是RAG技术？",
        "top_k": 10,
        "similarity_cutoff": 0.3
    }
}
```

### 2. 元数据过滤检索

```python
{
    "tool": "retrieve_documents",
    "arguments": {
        "question": "AI研究论文",
        "top_k": 10,
        "metadata_filters": {
            "file_type": {"operator": "EQ", "value": "pdf"},
            "created_at": {"operator": "GTE", "value": "2024-01-01"}
        }
    }
}
```

### 3. 重排序检索

```python
{
    "tool": "retrieve_documents",
    "arguments": {
        "question": "机器学习最佳实践",
        "top_k": 20,
        "use_reranker": true,
        "similarity_cutoff": 0.2
    }
}
```

### 4. 批量检索

```python
{
    "tool": "batch_retrieve",
    "arguments": {
        "questions": [
            "什么是Transformer？",
            "什么是BERT？",
            "什么是GPT？"
        ],
        "mode": "hybrid",
        "top_k": 5
    }
}
```

### 5. 插入新文档

```python
{
    "tool": "insert_documents",
    "arguments": {
        "documents": [
            {
                "text": "这是一篇新文档的内容...",
                "metadata": {
                    "source": "web",
                    "category": "AI",
                    "date": "2024-01-09"
                }
            }
        ]
    }
}
```

### 6. 更新文档

```python
{
    "tool": "update_documents",
    "arguments": {
        "documents": [
            {
                "doc_id": "document-id-123",
                "text": "更新后的文档内容...",
                "metadata": {
                    "updated_at": "2024-01-09"
                }
            }
        ]
    }
}
```

### 7. 删除文档

```python
{
    "tool": "delete_document",
    "arguments": {
        "doc_id": "document-id-123"
    }
}
```

### 8. 列出所有文档

```python
{
    "tool": "list_documents",
    "arguments": {
        "limit": 100
    }
}
```

---

## 📦 安装依赖

### 1. 安装所有增强功能依赖

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

### 2. 分步安装

#### 仅安装基础后处理器（已包含在llama-index-core中）

无需额外安装，`SimilarityPostprocessor` 和其他核心后处理器已包含。

#### 安装Reranker插件

```bash
# Cohere Rerank（商业级）
pip install llama-index-postprocessor-cohere-rerank

# SentenceTransformer Rerank（推荐）
pip install llama-index-postprocessor-sentence-transformer-rerank

# Flag Embedding Reranker（中文优化）
pip install llama-index-postprocessor-flag-embedding-reranker

# Sentence Transformers（必需）
pip install sentence-transformers
```

---

## ⚠️ 注意事项

### 1. 性能考虑

- **Reranker性能**：重排序会增加查询时间，建议初次检索更多文档（如top_k=20），然后重排序到5个
- **批量查询**：异步批量查询可显著提升吞吐量，但要注意内存使用
- **增量更新**：频繁的小规模更新优于定期大规模重建

### 2. 配置建议

- **相似度阈值**：
  - `0.1-0.2`：宽松，适合探索性查询
  - `0.3-0.5`：标准，适合一般查询（推荐）
  - `0.5-0.7`：严格，适合精确查询

- **Reranker选择**：
  - 开发环境：`sentence-transformer`
  - 生产环境（英文）：`cohere`
  - 中文场景：`flag-embedding`

### 3. Cohere API使用

如果使用Cohere Rerank：
1. 注册获取API Key：https://cohere.ai/
2. 设置环境变量：`COHERE_API_KEY=your-key`
3. 注意API调用限制和费用

### 4. 增量索引管理

- 插入/更新/删除操作会自动同步BM25索引
- 大量操作后建议检查索引状态
- 定期备份索引数据

### 5. 元数据过滤

支持的操作符：
- `EQ` - 等于
- `NE` - 不等于
- `GT` - 大于
- `LT` - 小于
- `GTE` - 大于等于
- `LTE` - 小于等于
- `IN` - 包含于（列表）
- `NIN` - 不包含于（列表）
- `CONTAINS` - 包含（字符串）

---

## 🎉 总结

本次功能增强完全基于LlamaIndex生态系统，具有以下优势：

1. ✅ **标准化** - 使用官方组件，符合业界最佳实践
2. ✅ **可维护性** - 官方维护，自动获得bug修复和更新
3. ✅ **稳定性** - 生产级质量，经过大规模验证
4. ✅ **扩展性** - 丰富的插件生态，易于添加新功能
5. ✅ **性能优化** - 官方组件已优化，无需自行调优

**功能覆盖率**: 100% ✅

---

## 📚 相关文档

- [增强指南](../plans/RAG_MCP_Enhancement_Guide.md) - 完整的功能说明
- [配置管理](./CONFIG_MANAGEMENT.md) - 配置系统详解
- [依赖注入](./DEPENDENCY_INJECTION.md) - DI容器使用
- [服务层重构](./SERVICE_LAYER_REFACTORING.md) - 服务层架构

---

**文档版本**: v1.0  
**创建日期**: 2026-01-09  
**维护者**: AI Group RAG Team
