# 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](IMPROVEMENT_SUMMARY.md) ### 2. 结构化JSON输出 - **输出格式**：完整的执行记录JSON，包含输入、执行过程、结果和元数据 - **双文件保存**： - `execution_record.json` - 格式化的JSON，易于阅读 - `final_result.json` - 系统缓存 - **优势**：可追溯、可调试、可审计 ### 3. Prompt和LLM交互追踪（新）⭐ - **完整记录**：每个LLM调用都记录prompt和response - **透明度**：可以看到系统如何与LLM交互 - **调试利器**：快速定位问题，优化prompt效果 - **详细说明**：[DETAILED_TRACKING.md](DETAILED_TRACKING.md) - **示例**：[example_detailed_output.json](example_detailed_output.json) **示例结构**： ```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'] ``` ### 禁用缓存 ```python 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 ``` 可以直接打开查看完整的执行过程。 ### 清除缓存 ```python 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. **备份重要**：可备份常用问题的缓存