# RAG-MCP 功能对比与快速参考

## 📊 功能对比表

### 现有功能 vs 增强功能

| 功能类别 | 现有功能 | 新增功能 | 优势 |
|---------|---------|---------|------|
| **检索控制** | ✅ 基础top_k控制 | ✅ 分数阈值过滤
✅ 自适应阈值
✅ 最小/最大分数限制 | 提升结果精准度
减少低质量结果 |
| **结果排序** | ✅ 默认按相关性 | ✅ 8种排序策略
✅ 多样性去重
✅ 加权排序
✅ 时间/长度排序 | 灵活的结果组织
避免内容重复 |
| **高级检索** | ✅ 三种检索模式 | ✅ 元数据过滤
✅ 批量查询
✅ 相似文档搜索
✅ 条件组合查询 | 精确查找
提升效率 |
| **索引管理** | ✅ 全量构建
✅ 删除索引 | ✅ 增量添加
✅ 文档更新
✅ 单文档删除
✅ 索引优化 | 无需重建
维护便利 |
| **监控分析** | ❌ 无 | ✅ 查询统计
✅ 热门话题
✅ 性能监控
✅ 分析报告 | 洞察使用模式
优化策略 |
| **CLI工具** | 6个命令 | 15个命令 | 功能完整
易于使用 |
| **MCP工具** | 6个工具 | 14个工具 | 智能体友好
功能丰富 |

---

## 🚀 快速使用指南

### 1. 分数阈值过滤

**问题**：检索结果包含很多不相关的文档
**解决**：使用分数阈值过滤

```python
# Python API
result = rag.retrieve(
    question="什么是RAG技术？",
    score_threshold=0.3,  # 只保留分数>=0.3的结果
    top_k=10
)

# CLI
python cli.py retrieve --question "什么是RAG?" --threshold 0.3

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

**推荐阈值**：
- `0.1-0.2`：宽松，适合探索性查询
- `0.3-0.5`：标准，适合一般查询
- `0.5-0.7`：严格，适合精确查询
- `0.7+`：非常严格，只返回高度相关结果

---

### 2. 结果排序策略

**问题**：需要不同的结果组织方式
**解决**：使用多种排序策略

```python
# 多样性排序 - 避免重复内容
result = rag.retrieve(
    question="AI技术",
    sort_strategy="diversity",
    diversity_threshold=0.7,
    top_k=20
)

# 按时间排序 - 最新优先
result = rag.retrieve(
    question="2024年AI研究",
    sort_strategy="time_desc",
    metadata_filters={"created_at": {"operator": "gte", "value": "2024-01-01"}}
)

# 加权排序 - 结合多个因素
result = rag.retrieve(
    question="重要文档",
    sort_strategy="weighted",
    weights={"priority": 0.5, "views": 0.0001}
)
```

**排序策略选择指南**：

| 场景 | 推荐策略 | 说明 |
|-----|---------|------|
| 一般查询 | `score_desc` | 按相关性降序（默认） |
| 需要多样性 | `diversity` | 去重相似内容 |
| 时间敏感 | `time_desc` | 最新优先 |
| 历史查询 | `time_asc` | 最早优先 |
| 需要详细内容 | `length_desc` | 长文档优先 |
| 需要简洁 | `length_asc` | 短文档优先 |
| 自定义权重 | `weighted` | 结合元数据 |

---

### 3. 元数据过滤

**问题**：需要根据文档属性筛选
**解决**：使用元数据过滤器

```python
# 只查找PDF文档
result = rag.retrieve(
    question="研究论文",
    metadata_filters={
        "file_type": {"operator": "eq", "value": "pdf"}
    }
)

# 查找特定日期范围的文档
result = rag.retrieve(
    question="最近的研究",
    metadata_filters={
        "created_at": {"operator": "gte", "value": "2024-01-01"},
        "priority": {"operator": "eq", "value": "high"}
    }
)

# CLI
python cli.py retrieve \
  --question "研究论文" \
  --filter "file_type:pdf,created_at:>=2024-01-01"
```

**支持的操作符**：
- `eq` (等于)
- `ne` (不等于)
- `gt` (大于)
- `lt` (小于)
- `gte` (大于等于)
- `lte` (小于等于)
- `in` (包含于)
- `contains` (包含)

---

### 4. 批量查询

**问题**：需要同时查询多个问题
**解决**：使用批量查询

```python
# Python API
questions = [
    "什么是Transformer？",
    "什么是注意力机制？",
    "什么是BERT？"
]

results = rag.batch_retrieve(
    questions=questions,
    mode="hybrid",
    top_k=5,
    score_threshold=0.3
)

# 处理结果
for q, r in zip(questions, results["results"]):
    print(f"问题: {q}")
    print(f"找到 {r['count']} 个相关文档")

# CLI
python cli.py batch --file questions.txt --threshold 0.3

# MCP工具
{
    "tool": "batch_retrieve",
    "arguments": {
        "questions": [
            "什么是Transformer？",
            "什么是注意力机制？"
        ],
        "mode": "hybrid",
        "top_k": 5
    }
}
```

---

### 5. 增量索引管理

**问题**：添加新文档需要重建整个索引
**解决**：使用增量更新

```python
# 添加新文档
result = rag.add_documents(
    documents=["新文档内容1", "新文档内容2"],
    metadata_list=[
        {"source": "arxiv", "category": "AI"},
        {"source": "blog", "category": "tutorial"}
    ]
)

# 更新文档
result = rag.update_document(
    document_id="doc_123",
    new_content="更新后的内容",
    new_metadata={"updated_at": "2024-12-01"}
)

# 删除文档
result = rag.delete_document(document_id="doc_123")

# CLI
python cli.py add --file new_doc.txt --metadata "category:research,priority:high"
python cli.py update --id doc_123 --file updated.txt
python cli.py remove --id doc_123
```

---

### 6. 相似文档搜索

**问题**：找到与某个文档相似的其他文档
**解决**：使用相似文档搜索

```python
# Python API
similar = rag.find_similar_documents(
    document_id="doc_123",
    top_k=5,
    similarity_threshold=0.6
)

# CLI
python cli.py similar --id doc_123 --top-k 5

# MCP工具
{
    "tool": "find_similar",
    "arguments": {
        "document_id": "doc_123",
        "top_k": 5,
        "similarity_threshold": 0.6
    }
}
```

---

### 7. 查询分析和监控

**问题**：不了解用户查询模式和系统使用情况
**解决**：使用查询分析功能

```python
# 获取统计报告
stats = rag.get_analytics(days=7, report_type="summary")

# 查看热门话题
hot_topics = rag.get_analytics(report_type="hot_topics")

# CLI
python cli.py analyze --days 7 --report detailed --output report.json
```

---

## 🎯 最佳实践组合

### 场景1: 精准文档检索
```python
result = rag.retrieve(
    question="深度学习最新进展",
    mode="hybrid",              # 混合检索
    top_k=20,                   # 初始检索20个
    score_threshold=0.4,        # 过滤低分结果
    sort_strategy="diversity",  # 多样性排序
    diversity_threshold=0.7,    # 去重阈值
    metadata_filters={          # 只要PDF和最近的
        "file_type": {"operator": "eq", "value": "pdf"},
        "created_at": {"operator": "gte", "value": "2024-01-01"}
    }
)
```

### 场景2: 时间敏感查询
```python
result = rag.retrieve(
    question="最新AI突破",
    mode="hybrid",
    top_k=10,
    sort_strategy="time_desc",  # 时间降序
    score_threshold=0.3,
    metadata_filters={
        "created_at": {"operator": "gte", "value": "2024-06-01"}
    }
)
```

### 场景3: 高质量精选
```python
result = rag.retrieve(
    question="权威研究论文",
    mode="vector",
    top_k=15,
    score_threshold=0.6,        # 高阈值
    sort_strategy="weighted",   # 加权排序
    weights={
        "citation_count": 0.001,  # 引用数权重
        "impact_factor": 0.1,     # 影响因子权重
        "priority": 0.3           # 优先级权重
    }
)
```

---

## 📋 完整MCP工具列表

### 现有工具（已有，建议保持）
| 工具 | 功能 | 状态 |
|-----|------|------|
| `build_index` | 构建索引 | ✅ 保持 |
| `query_knowledge` | LLM问答 | ✅ 保持 |
| `retrieve_documents` | 检索文档 | 🔄 增强参数 |
| `get_index_status` | 索引状态 | ✅ 保持 |
| `get_config` | 系统配置 | ✅ 保持 |
| `delete_index` | 删除索引 | ✅ 保持 |

### 新增工具（推荐添加）
| 工具 | 功能 | 优先级 |
|-----|------|-------|
| `retrieve_with_filters` | 高级检索（阈值+排序+过滤） | 🔥 高 |
| `batch_retrieve` | 批量检索 | 🔥 高 |
| `add_documents` | 增量添加文档 | ⭐ 中 |
| `update_document` | 更新文档 | ⭐ 中 |
| `delete_document` | 删除单个文档 | ⭐ 中 |
| `find_similar` | 相似文档搜索 | ⭐ 中 |
| `optimize_index` | 优化索引 | 💡 低 |
| `get_analytics` | 查询分析报告 | 💡 低 |

---

## 🔧 配置参数速查

### 检索参数

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| `question` | string | 必填 | 查询问题 |
| `mode` | enum | hybrid | vector/bm25/hybrid |
| `top_k` | int | 5 | 返回结果数 |
| `score_threshold` | float | 0.0 | 分数阈值(0-1) |
| `use_adaptive_threshold` | bool | false | 自适应阈值 |
| `sort_strategy` | enum | score_desc | 排序策略 |
| `diversity_threshold` | float | 0.8 | 多样性阈值(0-1) |
| `metadata_filters` | object | null | 元数据过滤器 |

### 环境变量配置

```env
# 新增配置项
SCORE_THRESHOLD=0.0
USE_ADAPTIVE_THRESHOLD=False
ADAPTIVE_THRESHOLD_PERCENTILE=0.5
DEFAULT_SORT_STRATEGY=score_desc
DIVERSITY_THRESHOLD=0.8
BATCH_QUERY_LIMIT=50
ENABLE_QUERY_ANALYTICS=True
ANALYTICS_STORAGE_PATH=logs/query_analytics.json
```

---

## 💡 性能优化建议

### 1. 检索优化
- **使用阈值过滤**：减少后处理开销
- **合理设置top_k**：过大会影响性能
- **选择合适模式**：
  - `vector`：语义查询（较慢但准确）
  - `bm25`：关键词查询（快速但简单）
  - `hybrid`：综合查询（平衡）

### 2. 排序优化
- **diversity排序**：在结果数<100时使用
- **weighted排序**：避免过多的权重计算
- **时间排序**：确保元数据包含时间字段

### 3. 批量查询优化
- 设置合理的批量大小（建议<50）
- 考虑使用异步处理
- 共享配置参数以减少重复计算

---

## 🎓 学习路径

### 初级使用
1. ✅ 基础检索（现有功能）
2. ✅ 使用分数阈值过滤
3. ✅ 尝试不同排序策略

### 中级使用
4. ✅ 元数据过滤
5. ✅ 批量查询
6. ✅ 增量索引管理

### 高级使用
7. ✅ 组合使用多个功能
8. ✅ 自定义加权排序
9. ✅ 查询分析和优化

---

## 📖 常见问题

### Q1: 如何选择合适的分数阈值？
**A**: 
- 先不设阈值，查看结果分数分布
- 一般建议从0.3开始，根据结果质量调整
- 使用自适应阈值进行自动调整

### Q2: diversity排序会不会过滤太多结果？
**A**: 
- diversity_threshold控制相似度阈值
- 0.8为推荐值（较松）
- 0.9更松（保留更多结果）
- 0.6更严（更强的去重）

### Q3: 元数据过滤器如何定义？
**A**: 
```python
{
    "field_name": {
        "operator": "eq/ne/gt/lt/gte/lte/in/contains",
        "value": "filter_value"
    }
}
```

### Q4: 批量查询有数量限制吗？
**A**: 
- 建议单次<50个查询
- 可通过BATCH_QUERY_LIMIT配置
- 超大批量考虑分批处理

### Q5: 增量更新会影响BM25索引吗？
**A**: 
- 会自动同步更新BM25索引
- 建议定期执行optimize_index
- 大量更新后重建可能更高效

---

## 🔗 相关文档链接

- [详细功能设计文档](./feature_enhancement_plan.md)
- [实施计划](./feature_enhancement_plan.md#实施计划)
- [系统架构图](./feature_enhancement_plan.md#系统架构图)
- [使用场景示例](./feature_enhancement_plan.md#使用场景示例)

---

## 📅 版本信息

- **当前版本**: v1.0 (现有功能)
- **计划版本**: v2.0 (增强功能)
- **建议升级**: 渐进式，保持向后兼容

---

**最后更新**: 2026-01-09
