GustoBot - 智能菜谱客服

<div align="center"> <h2>基于 Multi-Agent 架构的智能菜谱客服</h2>

</div>

项目简介

中华菜谱作为世界饮食文化的瑰宝之一，拥有深厚的历史底蕴与丰富的知识体系。从八大菜系的地域特色，到食材搭配的营养学原理，再到烹饪技法的代际传承，菜谱知识既具有高度结构化的特点（如食材用量、烹饪步骤），又包含大量非结构化的文化典故与经验性描述。这种复杂性使得传统的关键词搜索难以满足用户对菜谱知识的深度探索需求。

随着大语言模型（LLM）与知识增强技术的快速发展，将菜谱知识构建为一个多模态、结构化、可交互的 AI 系统成为可能。本项目以中华菜谱数据为基础，构建出覆盖菜谱名称、食材、烹饪步骤、营养成分、菜系流派、历史典故等元素的多层次知识图谱，并结合大模型的理解与生成能力，打造了一个专注于菜谱领域的智能客服——「GustoBot」。

在技术架构层面，我们融合了 LangGraph 多智能体编排、GraphRAG 图谱检索增强、Text2SQL 结构化查询、以及多源知识融合技术，使用户不仅可以通过自然语言提问获得精确答案（如"宫保鸡丁怎么做？"、"川菜有多少道菜？"），还能探索菜谱的历史文化背景（如"宫保鸡丁的典故"）、获取营养建议、甚至生成菜品图片。

核心价值

本项目致力于打造一个可迁移、可扩展、面向垂直领域的智能客服模板系统。通过清晰的三层架构设计（主路由层 → 多工具子图层 → 原子工具层），你可以轻松将其迁移至其他垂直领域（如「宝可梦百科」、「中医药典」、「法律咨询」、「政务服务」等）中打造专域智能客服。仅需更换知识源与图谱结构，即可实现：

• 智能意图理解：自动识别问题类型，路由到最优处理模块
• 多工具协作：动态组合 Neo4j 图谱查询、MySQL 统计分析、向量检索、外部搜索等多种工具
• PostgreSQL 优先兜底策略：结构化数据优先 → 向量兜底 → 外部搜索，确保答案质量
• 多模态交互：支持文本问答、图片识别/生成、文件解析等多种交互方式
• 知识来源可追溯：每个答案都标注来源，支持多源信息融合
• 安全防护机制：Guardrails 层确保问题在服务范围内，拒绝越界查询

核心功能

| 功能模块 | 说明 | 技术实现 | |---------|------|---------| | 全参微调 | 爬取和收集数据微调大模型 | 微调厨神模型 | | 智能路由 | 自动识别问题类型，路由到合适的处理模块 | 启发式路由 + LLM 结构化输出 | | 知识库查询 | 支持历史文化、菜谱典故等知识查询 | Milvus + PostgreSQL pgvector + Reranker | | 图谱推理 | 基于 Neo4j 的菜谱关系推理 | Cypher 动态生成 + Few-shot 示例检索 | | 统计分析 | MySQL 数据库的统计和聚合查询 | Text2SQL + LLM 自然语言转换 | | 社区检索 | Microsoft GraphRAG 社区摘要检索 | LightRAG Global/Local/Hybrid Search | | 图片处理 | 菜品图片识别与生成 | Vision Model + CogView-4 | | 文件处理 | 支持 Excel、TXT、Markdown 等文件上传分析 | Ingest Service + Knowledge Service | | 对话管理 | 完整的对话历史和会话管理 | LangGraph Checkpointer + Redis |

技术架构

<div align="center"> <img src="data/1.png" alt="GustoBot Multi-Agent 架构图" width="100%"> <p><i>图：GustoBot Multi-Agent 系统架构总览</i></p> </div>

本项目采用 三层 Multi-Agent 架构，将复杂的菜谱知识服务拆解为清晰的层次化设计：

架构分层

| 层级 | 名称 | 职责 | 核心技术 | |-----|------|------|---------| | L1 | 主路由层 | 意图识别与任务分发 | 启发式路由 + LLM 结构化输出 | | L2 | 多工具子图层 | 任务分解与工具编排 | LangGraph Subgraph + Map-Reduce | | L3 | 原子工具层 | 具体工具执行 | Neo4j / MySQL / Milvus / PostgreSQL |

核心执行流程

1. 用户提问 → 主路由层意图识别 (analyze_and_route_query)
2. 路由决策 → 分发至不同子图 (graphrag-query / kb-query / general-query 等)
3. 子图执行 → Guardrails 检查 → Planner 分解 → Tool Selection → 并行工具调用
4. 结果融合 → Summarize Node 聚合 → Final Answer 生成最终回答
5. 返回用户 → 带来源标注的完整答案

项目特色

1. 三层架构设计 - 清晰的职责分离

• 主路由层 (L1): 启发式关键词 + LLM 双重路由保险，快速准确识别用户意图
• 多工具子图层 (L2): LangGraph Subgraph 实现任务分解与并行工具编排
• 原子工具层 (L3): 可插拔的工具设计，轻松扩展新能力

2. PostgreSQL 优先兜底策略 - 确保答案质量

结构化数据 (PostgreSQL pgvector) → 向量检索兜底 (Milvus) → 外部搜索补充 (External API)

• 优先查询 PostgreSQL: 快速返回精准的结构化数据（菜谱名称、菜系、食材等）
• Milvus 兜底: PostgreSQL 无结果时，使用语义检索处理长文本和典故
• 外部搜索: Hybrid 模式下调用外部 API 补充最新知识

3. Map-Reduce 任务分解 - 处理复杂查询

• Planner Node: 将复杂问题拆解为多个独立子任务
• 并行执行: 子任务并行调用不同工具（Cypher / GraphRAG / Text2SQL）
• Summarize Node: 聚合所有工具结果，LLM 融合生成答案

4. Reranker 双阈值过滤 - 提升检索精度

# 双重阈值确保结果质量
similarity >= KB_POSTGRES_SIMILARITY_THRESHOLD  # 相似度阈值
rerank_score >= KB_POSTGRES_RERANK_THRESHOLD    # 重排分数阈值

• 支持 Cohere / Jina / Voyage / BGE 等多种 Reranker
• 有效过滤低质量检索结果，提升答案准确性

5. 多源知识融合 - 全面的信息整合

• 图谱推理 (Neo4j): 菜谱关系、食材搭配、菜系归属
• 统计分析 (MySQL): 数量统计、排行榜、聚合查询
• 语义检索 (Milvus + PostgreSQL): 历史典故、文化背景
• 社区摘要 (Microsoft GraphRAG): 全局/局部/混合检索
• 外部知识 (Search API): 实时互联网信息补充

6. 可迁移的垂直领域模板 - 高度泛化

仅需替换知识源与图谱 Schema，即可快速迁移至其他领域：

| 应用领域 | 知识源示例 | 图谱节点示例 | |---------|-----------|------------| | 菜谱客服 | 菜谱数据、食材库 | 菜品、食材、菜系、烹饪方法 | | 宝可梦百科 | 宝可梦图鉴 | 宝可梦、技能、属性、进化链 | | 中医药典 | 本草纲目、方剂 | 中药、病症、方剂、炮制方法 | | 法律咨询 | 法律条文、案例 | 法条、案件、当事人、判决 | | 政务服务 | 政策文件、办事指南 | 政策、部门、流程、材料 |

7. 多模态交互 - 丰富的用户体验

• 图片识别: Vision Model 识别菜品，返回菜谱信息
• 图片生成: CogView-4 根据描述生成菜品图片
• 文件处理: 支持 Excel、TXT、Markdown、JSON 文件上传与分析
• 对话管理: LangGraph Checkpointer + Redis 维护完整会话历史

8. Guardrails 安全防护 - 拒绝越界查询

• 范围检查: 每个查询都经过 Guardrails 节点检查是否在服务范围内
• Schema 验证: 验证 Neo4j 图谱 Schema，确保查询可执行
• 拒绝策略: 明确拒绝超出菜谱领域的问题，引导用户提供有效输入

---

快速开始

环境要求

• Python 3.10
• Node.js 16+
• Docker & Docker Compose

# 克隆项目
git clone https://github.com/skygazer42/GustoBot.git
cd GustoBot

# 配置环境变量
cp .env.example .env # 编辑 .env 文件，配置必要的 API 密钥


# 启动后端服务（Docker）
docker-compose up -d

# 安装并启动前端（本地）
cd web
npm install
npm run dev

# 访问应用
# 前端: http://localhost:5173 （可通过 VITE_PORT 修改端口）
# 后端API: http://localhost:8000

---

系统架构图

graph TB
    %% ========== 用户入口 ==========
    Start([用户提问]) --> MainGraph[LangGraph 主工作流]

    %% ========== 第一层：主路由层 ==========
    MainGraph --> RouterNode["analyze_and_route_query<br/>━━━━━━━━━━━━━━━━<br/>系统提示: ROUTER_SYSTEM_PROMPT<br/>启发式路由 + LLM 路由双保险<br/>结构化输出: Router Pydantic Model"]

    RouterNode --> RouteDecision{"route_query<br/>条件路由"}

    RouteDecision -->|general-query| GeneralNode["respond_to_general_query<br/>━━━━━━━━━━━━━━━━<br/>GENERAL_QUERY_SYSTEM_PROMPT<br/>纯 LLM 生成回复<br/>不调用任何外部工具"]

    RouteDecision -->|additional-query| AdditionalNode["get_additional_info<br/>━━━━━━━━━━━━━━━━<br/>GET_ADDITIONAL_SYSTEM_PROMPT<br/>Guardrails 安全检查<br/>引导用户提供更多信息"]

    RouteDecision -->|graphrag-query<br/>text2sql-query| ResearchNode["create_research_plan<br/>━━━━━━━━━━━━━━━━<br/>调用 GraphRAG 多工具子图"]

    RouteDecision -->|kb-query| KBNode["create_kb_query<br/>━━━━━━━━━━━━━━━━<br/>调用知识库多工具子图"]

    RouteDecision -->|image-query| ImageNode["create_image_query<br/>━━━━━━━━━━━━━━━━<br/>图片识别: Vision Model<br/>图片生成: CogView-4"]

    RouteDecision -->|file-query| FileNode["create_file_query<br/>━━━━━━━━━━━━━━━━<br/>Excel: 外部 Ingest Service<br/>TXT/MD/JSON: KnowledgeService"]

    %% ========== 第二层A：GraphRAG 多工具子图 ==========
    ResearchNode --> SubGraph1["╔═══════════════════════════════════════╗<br/>║  GraphRAG 多工具子图 (create_multi_tool_workflow)  ║<br/>╚═══════════════════════════════════════╝"]

    SubGraph1 --> SG1_Guardrails["Guardrails Node<br/>━━━━━━━━━━━━━━━━<br/>GUARDRAILS_SYSTEM_PROMPT<br/>检查问题范围<br/>图谱 Schema 验证"]

    SG1_Guardrails --> SG1_GuardCheck{"通过检查?"}
    SG1_GuardCheck -->|拒绝 end| SG1_FinalAnswer_Reject["直接返回拒绝消息"]
    SG1_GuardCheck -->|通过 proceed| SG1_Planner["Planner Node<br/>━━━━━━━━━━━━━━━━<br/>任务分解提示<br/>Map-Reduce 模式<br/>将复杂问题拆解为子任务"]

    SG1_Planner --> SG1_MapReduce["map_reduce_planner_to_tool_selection<br/>━━━━━━━━━━━━━━━━<br/>条件边逻辑<br/>遍历每个子任务"]

    SG1_MapReduce --> SG1_ToolSelection["Tool Selection Node<br/>━━━━━━━━━━━━━━━━<br/>根据 tool_schemas 选择工具<br/>LLM structured output<br/>工具列表:<br/>  • cypher_query<br/>  • predefined_cypher<br/>  • microsoft_graphrag_query<br/>  • text2sql_query"]

    SG1_ToolSelection --> SG1_ToolDecision{"选择的工具?"}

    SG1_ToolDecision -->|cypher_query| SG1_Cypher["Cypher Query Node<br/>━━━━━━━━━━━━━━━━<br/>动态生成 Cypher<br/>BaseCypherExampleRetriever<br/>  检索 Few-shot 示例<br/>LLM 生成查询语句<br/>Cypher 验证 (可选)<br/>Neo4j 执行查询<br/>返回图谱数据"]

    SG1_ToolDecision -->|predefined_cypher| SG1_Predefined["Predefined Cypher Node<br/>━━━━━━━━━━━━━━━━<br/>predefined_cypher_dict<br/>匹配预定义查询<br/>Neo4j 直接执行<br/>快速、准确"]

    SG1_ToolDecision -->|microsoft_graphrag_query| SG1_GraphRAG["Microsoft GraphRAG Node<br/>━━━━━━━━━━━━━━━━<br/>LightRAG 社区检索<br/>Global Search (全局)<br/>Local Search (局部)<br/>Hybrid Search (混合)<br/>社区摘要 + 实体关系"]

    SG1_ToolDecision -->|text2sql_query| SG1_Text2SQL["Text2SQL Query Node<br/>━━━━━━━━━━━━━━━━<br/>自然语言转 SQL<br/>LLM 生成 SQL 语句<br/>支持统计、聚合、排名<br/>MySQL 执行查询<br/>返回结构化数据"]

    SG1_Cypher --> SG1_Summarize["Summarize Node<br/>━━━━━━━━━━━━━━━━<br/>聚合所有工具结果<br/>合并 data 字段<br/>LLM 初步整理"]
    SG1_Predefined --> SG1_Summarize
    SG1_GraphRAG --> SG1_Summarize
    SG1_Text2SQL --> SG1_Summarize

    SG1_Summarize --> SG1_FinalAnswer["Final Answer Node<br/>━━━━━━━━━━━━━━━━<br/>RAGSEARCH_SYSTEM_PROMPT<br/>LLM 生成最终回答<br/>引用来源标注<br/>幻觉检查 (可选)"]

    SG1_FinalAnswer --> SG1_End["返回到主工作流<br/>answer 字段"]
    SG1_FinalAnswer_Reject --> SG1_End

    %% ========== 第二层B：知识库多工具子图 ==========
    KBNode --> SubGraph2["╔═══════════════════════════════════════╗<br/>║  知识库多工具子图 (create_kb_multi_tool_workflow)  ║<br/>╚═══════════════════════════════════════╝"]

    SubGraph2 --> SG2_Guardrails["KB Guardrails Node<br/>━━━━━━━━━━━━━━━━<br/>KBGuardrailsDecision<br/>scope_description 范围检查<br/>仅处理历史文化典故类问题"]

    SG2_Guardrails --> SG2_GuardCheck{"通过检查?"}
    SG2_GuardCheck -->|decision=end| SG2_Finalize_Reject["直接返回拒绝<br/>返回 summary"]
    SG2_GuardCheck -->|decision=proceed| SG2_Router["KB Router Node<br/>━━━━━━━━━━━━━━━━<br/>KBRouteDecision<br/>LLM 路由决策<br/>路由类型:<br/>  • local (本地检索)<br/>  • external (外部API)<br/>  • hybrid (混合)<br/>工具选择:<br/>  • postgres (优先)<br/>  • milvus (兜底)"]

    SG2_Router --> SG2_RouteCheck{"路由类型?"}

    SG2_RouteCheck -->|local/hybrid| SG2_LocalSearch["Local Search Node<br/>━━━━━━━━━━━━━━━━<br/>PostgreSQL 优先策略:<br/>━━━━━━━━━━━━━━━━<br/>Step 1: 查询 PostgreSQL pgvector<br/>  • 结构化数据 (Excel 导入)<br/>  • 菜谱名称、菜系、枚举字段<br/>  • 快速、精准<br/>  • threshold 阈值过滤<br/>━━━━━━━━━━━━━━━━<br/>Step 2: 如果 PG 有结果<br/>  → 直接使用，跳过 Milvus<br/>━━