rag/docs/多源信息融合指南.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 冲突处理模板

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 — 图表查找、图片提取、富媒体附加

from core.agentic import AgenticRAG

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

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

3.2 数据结构

# 上下文数据结构
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 中）：

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（生产环境）环境变量注入，不在代码中硬编码：

# .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 运行命令

# 交互模式
python -m core.agentic

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

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

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

5.3 API 调用

# 知识库问答（自动融合）
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	初始版本