kg_agent/knowledge_v2

Knowledge V2 系统架构说明

整体流程梳理

function_knowledge.py (入口)
    ├── [步骤1] generate_query: 生成查询语句
    ├── [步骤2] select_tool: 选择工具
    ├──┬── [有工具]
    │  │    ├── [步骤3] extract_tool_params: 提取工具参数（通过LLM）
    │  │    └── [步骤4] call_tool: 调用工具
    │  └── [无工具] 
    │       └── [步骤4] multi_search_knowledge.py
    │                   ├── llm_search_knowledge.py
    │                   │    ├── generate_queries: 生成多个query
    │                   │    ├── search_knowledge_batch: 批量搜索
    │                   │    └── merge_knowledge: 合并多个query的结果
    │                   └── merge_knowledge: 合并多渠道结果
    └── [后台] generate_and_save_new_tool: 异步生成新工具

核心特性

1. 动态工具参数提取

• 问题：之前工具调用参数是硬编码的 {"keyword": query}
• 解决：使用LLM根据工具信息动态提取参数
• 优势：通用、智能、支持多参数工具
• 详细说明：IMPROVEMENT_SUMMARY.md

2. 结构化JSON输出

• 输出格式：完整的执行记录JSON，包含输入、执行过程、结果和元数据
• 双文件保存：
  • execution_record.json - 格式化的JSON，易于阅读
  • final_result.json - 系统缓存
• 优势：可追溯、可调试、可审计

3. Prompt和LLM交互追踪（新）⭐

• 完整记录：每个LLM调用都记录prompt和response
• 透明度：可以看到系统如何与LLM交互
• 调试利器：快速定位问题，优化prompt效果
• 详细说明：DETAILED_TRACKING.md
• 示例：example_detailed_output.json

示例结构：

{
  "steps": [{
    "name": "generate_query",
    "detail": {
      "prompt": "完整的prompt文本...",
      "response": "LLM的响应..."
    }
  }]
}

4. 完善的缓存系统

• 分级缓存结构
• 支持断点续传
• 节省资源和成本

4. 详细的日志系统

• 结构化日志输出
• 清晰的步骤标记

• 便于调试和监控

  
  ## 缓存策略
  
  ### 缓存目录结构
  

.cache/ ├── {question_hash}/ # 每个问题一个文件夹 │ ├── question.txt # 原始问题文本（方便查看） │ ├── function_knowledge/ # function_knowledge模块缓存 │ │ ├── generated_query.txt # 生成的query │ │ ├── selected_tool.txt # 选择的工具名 │ │ ├── tool_params.json # 提取的工具参数（新） │ │ ├── tool_result.json # 工具执行结果 │ │ └── final_result.txt # 最终结果 │ ├── multi_search/ # multi_search模块缓存 │ │ ├── final_knowledge.txt # 最终合并知识 │ │ └── merged_knowledge.txt # 合并后的知识 │ └── llm_search/ # llm_search模块缓存 │ ├── generated_queries.json # 生成的查询列表 │ ├── merged_knowledge.txt # 合并后的知识 │ └── search_results/ # 搜索结果 │ ├── search_result_001.txt │ ├── search_result_002.txt │ └── search_result_003.txt

### 缓存优点
1. **节省资源**：避免重复调用LLM和搜索引擎
2. **断点续传**：任何步骤失败都可以从缓存恢复
3. **调试方便**：可以查看每个步骤的中间结果
4. **性能提升**：缓存命中时速度大幅提升

### 缓存key设计
- `function_knowledge`: 使用 `question||post_info||persona_info` 组合
- `multi_search`: 使用原始 `question`
- `llm_search`: 使用原始 `question`

## 日志系统

### 日志格式

[模块] 操作状态 - 描述 ↓ 级联操作 ✓ 成功 ✗ 失败 ⚠ 警告 → 正在执行

### 日志层级

#### 1. Function Knowledge (最外层)

================================================================================ Function Knowledge - 开始处理 问题: ... 帖子信息: ...

人设信息: ...

[步骤1] 生成Query... ✓ 使用缓存的Query: ... [步骤2] 选择工具... 当前可用工具数: 1 → 调用Gemini选择工具... ✓ 选择结果: wechat_search_article [步骤3] 调用工具: wechat_search_article → 调用工具，参数: {'keyword': '...'}

✓ 工具调用完成

✓ Function Knowledge 完成 (结果长度: 123)

#### 2. Multi-Search (中层)

============================================================

Multi-Search - 开始处理问题: ...

[渠道1] 调用 LLM Search... (LLM Search 内部日志) ✓ LLM Search 完成 (长度: 456) [Multi-Search] 合并多渠道知识 - 1 个渠道 有效渠道: ['LLM Search'] → 调用Gemini合并多渠道知识...

✓ 多渠道知识合并完成 (长度: 450)

✓ Multi-Search 完成 (最终长度: 450)

#### 3. LLM Search (最内层)

============================================================

LLM Search - 开始处理问题: ...

[步骤1] 生成搜索Query - 问题: ... → 调用Gemini生成query... → 解析生成的query... ✓ 成功生成 3 个query:

1. query1
2. query2

3. query3 [步骤2] 批量搜索 - 共 3 个Query [1] 搜索Query: query1 → 调用搜索引擎... ✓ 获取知识文本 (长度: 100) ... ✓ 批量搜索完成，获得 3 个有效结果 [步骤3] 合并知识 - 共 3 个文本 有效文本数量: 3/3 → 调用Gemini合并知识文本...

   ✓ 成功合并知识文本 (长度: 250)

   ✓ LLM Search 完成 (最终长度: 250)

   
   ## 使用示例
   
   ### 基本使用（启用缓存）
   ```python
   from knowledge_v2.function_knowledge import get_knowledge
   
   result = get_knowledge(
   question="去哪儿搜索微信文章？",
   post_info="无",
   persona_info="游戏博主"
   )
   
   # 访问执行结果
   print(f"结果类型: {result['result']['type']}")
   print(f"执行时间: {result['metadata']['execution_time']:.2f}秒")
   
   # 如果是工具调用
   if result['result']['type'] == 'tool':
   tool_info = result['execution']['tool_info']
   print(f"工具: {tool_info['tool_name']}")
   print(f"参数: {tool_info['parameters']}")
   
   # 获取文本内容
   content = result['result']['content']
   

禁用缓存

from knowledge_v2.function_knowledge import FunctionKnowledge

agent = FunctionKnowledge(use_cache=False)
result = agent.get_knowledge(
    question="...",
    post_info="...",
    persona_info="..."
)

查看执行记录文件

执行后会生成格式化的JSON文件：

.cache/{question_hash}/execution_record.json

可以直接打开查看完整的执行过程。

清除缓存

from knowledge_v2.cache_manager import CacheManager

cache = CacheManager()

# 清除特定问题的缓存
cache.clear("去哪儿搜索微信文章？")

# 清除所有缓存
cache.clear()

性能优化

缓存命中率统计

可通过日志中的 ✓ 使用缓存的... 标记来统计缓存命中情况

建议

1. 首次运行：完整流程，生成所有缓存
2. 后续运行：大部分步骤使用缓存，只在必要时调用LLM
3. 调试时：可关闭缓存或清除特定步骤缓存
4. 生产环境：建议启用缓存，定期清理过期缓存

故障恢复

场景1：LLM调用失败

• 已完成的步骤有缓存
• 重新运行只需重试失败步骤

场景2：搜索引擎超时

• 部分query已有缓存
• 只需重试失败的query

场景3：网络中断

• 所有中间结果都有缓存
• 恢复后从断点继续

维护建议

1. 定期清理：建议每周清理过期缓存（>7天）
2. 监控大小：关注 .cache 目录大小
3. 备份重要：可备份常用问题的缓存