rag/docs/多源信息融合指南.md

# 多源信息融合设计指南

> **⚠️ 路径说明**：本文档描述的 `AgenticRAG.process()` 多源融合路径是**备用路径**（需启用网络搜索）。生产环境的 `/rag` 问答接口使用 `chat_routes.py` 的轻量编排路径（详见 [RAG数据流程.md](RAG数据流程.md)），不经过 `AgenticRAG.process()`。两条路径的区别见 [Agentic_RAG完整指南.md](Agentic_RAG完整指南.md)。

## 一、问题背景

当 Agentic RAG 同时使用知识库和网络搜索时，会遇到以下情况：

```
┌─────────────────────────────────────────────────────────────┐
│                      多源信息融合挑战                         │
├─────────────────────────────────────────────────────────────┤
│  情况1: 完全一致                                              │
│    知识库: 出差伙食补助每天100元                               │
│    网络:   出差伙食补助每天100元                               │
│    → 简单，任意选用一个                                        │
├─────────────────────────────────────────────────────────────┤
│  情况2: 内容冲突                                              │
│    知识库: 出差伙食补助每天100元（2020年规定）                  │
│    网络:   出差伙食补助每天120元（2024年新规）                  │
│    → 需要判断时效性，说明差异                                   │
├─────────────────────────────────────────────────────────────┤
│  情况3: 完整度不同                                            │
│    知识库: 出差补助包含伙食费、交通费...                       │
│    网络:   出差补助=伙食费+交通费+住宿费，伙食费标准是...       │
│    → 以完整为主，另一方补充验证                                 │
├─────────────────────────────────────────────────────────────┤
│  情况4: 适用范围不同                                          │
│    知识库: XX学院出差规定（仅适用于该校）                       │
│    网络:   国家出差管理规定（通用）                             │
│    → 需要说明适用范围                                          │
└─────────────────────────────────────────────────────────────┘
```

---

## 二、信息融合策略

### 2.1 来源优先级规则

| 优先级 | 来源类型 | 适用场景 |
|--------|---------|---------|
| 最高 | 官方文件、法律法规 | 政策、制度类问题 |
| 高 | 权威网站（政府、行业协会） | 标准、规范类问题 |
| 中 | 知识库文档 | 内部规定、历史资料 |
| 低 | 普通网页、论坛 | 补充信息、参考意见 |

### 2.2 时效性判断

```
时效性判断逻辑：

1. 检查文档日期
   - 知识库：元数据中的日期
   - 网络：搜索结果中的 date 字段

2. 比较日期
   - 新 > 旧（通常情况）
   - 但法律、政策可能有过渡期

3. 输出格式
   - "根据2024年最新规定..."
   - "（注：知识库为2020年版本，可能已更新）"
```

### 2.3 冲突处理模板

```python
CONFLICT_TEMPLATES = {
    "时效性冲突": """
关于{topic}，存在不同时期的规定：

- **较早版本**（{old_date}）：{old_content}
  来源：{old_source}

- **最新版本**（{new_date}）：{new_content}
  来源：{new_source}

建议以最新版本为准。
""",

    "适用范围冲突": """
关于{topic}，存在不同适用范围的规定：

- **通用规定**：{general_content}
  适用范围：全国/全行业

- **特定规定**：{specific_content}
  适用范围：{specific_scope}

请根据您的具体情况选择适用。
""",

    "来源权威性冲突": """
关于{topic}，存在不同说法：

- **来源A**（{source_a}，权威性：{auth_a}）：{content_a}
- **来源B**（{source_b}，权威性：{auth_b}）：{content_b}

建议优先采信权威性更高的来源。
"""
}
```

---

## 三、代码实现

### 3.1 核心模块位置

Agentic RAG 已拆分为多个子模块（位于 `core/` 目录），入口仍为 `core/agentic.py`：

| 子模块 | 职责 |
|--------|------|
| `core/agentic.py` | 入口文件，组合所有 Mixin，提供 `AgenticRAG.process()` 主流程 |
| `core/agentic_base.py` | 常量定义、共享配置（API Key 读取、模型选择等） |
| `core/agentic_search.py` | 检索 Mixin — 知识库检索、网络搜索（`_web_search`） |
| `core/agentic_answer.py` | 答案生成 Mixin — 多源融合答案生成（`_generate_fused_answer`） |
| `core/agentic_query.py` | 查询重写 Mixin — 查询改写、实体补全、专业术语映射 |
| `core/agentic_context.py` | 上下文处理 Mixin — 上下文压缩、去重、Token 控制 |
| `core/agentic_quality.py` | 质量评估 Mixin — 置信度门控、质量评估、推理反思 |
| `core/agentic_meta.py` | 元问题处理 Mixin — 元问题判断和知识库元数据回答 |
| `core/agentic_citation.py` | 引用处理 Mixin — 来源提取、引用构建、引用附加 |
| `core/agentic_media.py` | 富媒体处理 Mixin — 图表查找、图片提取、富媒体附加 |

```python
from core.agentic import AgenticRAG

# 初始化（自动检测网络搜索配置，通过 .env 环境变量注入）
rag = AgenticRAG()

# 处理查询（自动融合多源信息）
result = rag.process("出差补助标准是什么？")
print(result["answer"])
print(result["sources"])  # 显示来源列表
```

### 3.2 数据结构

```python
# 上下文数据结构
context = {
    'doc': '文档内容',
    'meta': {
        'source': '文件名/URL',
        'page': 123,           # 知识库特有
        'title': '标题',        # 网络特有
        'date': '2024-01-01'   # 时间信息
    },
    'source_type': '知识库' or '网络搜索',
    'query': '检索用的查询词'
}
```

### 3.3 融合答案生成

`AgenticRAG._generate_fused_answer()` 方法处理多源融合（位于 `core/agentic_answer.py` 的 `AnswerMixin` 中）：

```python
def _generate_fused_answer(self, query: str, contexts: list, allowed_levels: list = None) -> str:
    """
    生成融合答案 - 智能处理多源信息

    处理策略：
    1. 区分知识库和网络来源
    2. 检测内容冲突
    3. 判断时效性
    4. 智能融合
    5. 权限限制检测
    """
    # 分离不同来源
    kb_contexts = [c for c in contexts if c.get('source_type') == self.SOURCE_KB]
    web_contexts = [c for c in contexts if c.get('source_type') == self.SOURCE_WEB]
    # ...
```

---

## 四、Agent 决策机制

### 4.1 决策类型

Agentic RAG 的 `_think()` 方法决定下一步操作：

| 决策 | 说明 | 适用场景 |
|------|------|----------|
| `kb_search` | 检索知识库 | 首次检索、内部文档、公司制度 |
| `web_search` | 网络搜索 | 实时信息、外部知识、最新政策 |
| `answer` | 生成答案 | 信息足够 |
| `rewrite` | 改写查询 | 查询词不准确 |
| `decompose` | 分解问题 | 多个子问题 |

### 4.2 决策原则

```
1. 元问题识别（重要！）
   - "有哪些文件"、"能查看什么"、"有什么权限" → 直接回答
   - 不需要检索内容

2. 检索优先级
   - 首轮优先检索知识库（kb_search）
   - 实时信息、外部知识 → 网络搜索（web_search）

3. 知识库结果评估（关键！）
   - 知识库结果足够 → 直接 answer
   - 不进行不必要的网络搜索

4. 效率原则
   - 信息足够时立即 answer
   - 避免重复检索
```

---

## 五、配置与使用

### 5.1 配置网络搜索

API Key 通过 `.env` 文件（开发环境）或 `deploy/.env.production`（生产环境）环境变量注入，不在代码中硬编码：

```bash
# .env（开发环境）
SERPER_API_KEY=your-serper-api-key

# deploy/.env.production（生产环境）
ENABLE_WEB_SEARCH=true
SERPER_API_KEY=your-serper-api-key
```

系统通过 `core/agentic_base.py` 读取环境变量，自动判断是否启用网络搜索功能。

### 5.2 运行命令

```bash
# 交互模式
python -m core.agentic

# 单次问答
python -m core.agentic "出差补助标准"

# 仅知识库（禁用网络）
/kb 出差补助标准

# 强制网络搜索
/web 2024年出差补助标准
```

### 5.3 API 调用

```bash
# 知识库问答（自动融合）
curl -X POST http://localhost:5001/rag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mock-token-admin" \
  -d '{"message": "出差补助标准是多少？"}'

# 智能聊天（支持网络搜索）
curl -X POST http://localhost:5001/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mock-token-admin" \
  -d '{"message": "今天北京的天气怎么样？"}'
```

---

## 六、输出示例

```
📖 答案:
----------------------------------------

### 核心答案
根据多个来源，出差补助标准如下：
- 伙食补助费：100元/天（[差旅费管理办法 第5页]）
- 公杂费：50元/天（[差旅费管理办法 第6页]）

### 详细说明
1. 伙食补助费标准为每人每天100元...
2. 公杂费包括市内交通、通讯等...

### 来源汇总
- 知识库：3条（XX学院2007年规定）
- 网络搜索：2条（2024年国家规定）

### 注意事项
⚠️ 知识库为2007年版本，国家已于2024年更新标准。
建议参考最新国家规定，或咨询财务部门确认。
```

---

## 七、最佳实践

### 7.1 何时使用网络搜索

| 问题类型 | 知识库 | 网络 |
|---------|--------|------|
| 公司内部规定 | ✅ 优先 | ❌ 不需要 |
| 国家政策法规 | △ 参考 | ✅ 优先 |
| 技术标准 | △ 参考 | ✅ 优先 |
| 行业动态 | ❌ 没有 | ✅ 必须 |
| 历史资料 | ✅ 优先 | △ 补充 |
| 实时信息（天气、新闻） | ❌ 没有 | ✅ 必须 |

### 7.2 提高融合质量的技巧

1. **标注来源时间**：让LLM知道信息的新旧
2. **标注来源权威性**：官方 > 权威媒体 > 普通
3. **明确适用范围**：本单位/本市/全国
4. **冲突时列举双方**：让用户自行判断

### 7.3 避免的问题

1. ❌ 不加区分地混合来源
2. ❌ 忽略时效性差异
3. ❌ 隐瞒冲突信息
4. ❌ 来源标注不清晰

---

## 八、相关代码文件

| 文件 | 说明 |
|------|------|
| `core/agentic.py` | Agentic RAG 入口，组合所有 Mixin 子模块 |
| `core/agentic_base.py` | 常量定义与共享配置（API Key、模型名等） |
| `core/agentic_search.py` | 检索 Mixin — 知识库检索、网络搜索 |
| `core/agentic_answer.py` | 答案生成 Mixin — 多源融合答案生成 |
| `core/agentic_query.py` | 查询重写 Mixin — 查询改写与术语映射 |
| `core/agentic_context.py` | 上下文处理 Mixin — 压缩、去重、Token 控制 |
| `core/agentic_quality.py` | 质量评估 Mixin — 置信度门控与推理反思 |
| `core/agentic_meta.py` | 元问题处理 Mixin — 知识库元数据问答 |
| `core/agentic_citation.py` | 引用处理 Mixin — 来源提取与引用构建 |
| `core/agentic_media.py` | 富媒体处理 Mixin — 图表查找与图片提取 |
| `core/engine.py` | 检索引擎封装 |
| `knowledge/manager.py` | 多向量库管理（组合各 Mixin） |
| `knowledge/search.py` | 多源融合检索与 RRF 打分 |
| `knowledge/router.py` | 知识库智能路由 |

---

## 变更记录

| 日期 | 版本 | 变更内容 |
|------|------|----------|
| 2026-06-04 | 3.0 | 更新 Agentic RAG 子模块拆分说明；配置改为 .env 环境变量注入；移除图谱检索内容 |
| 2026-04-13 | 2.0 | 更新代码路径（agentic_rag_v2.py → core/agentic.py） |
| 2025-03-30 | 1.0 | 初始版本 |