基于Graph Agent的智能聊天助手

项目背景

该项目是一个面向复杂业务问答与工具执行的企业级智能体系统，核心目标是让大模型在“检索问答（RAG）+ 数据库分析（SQL）+ 外部工具调用（TOOL）”混合场景下稳定完成多步骤任务。项目早期采用单模型串行调用，随着任务复杂度上升，逐步暴露出路由不准、工具误用、长对话记忆退化和异常恢复能力弱等问题，因此我主导了多智能体图架构、分层记忆和策略化容错的重构工作。

STAR 过程

情境（Situation）：单模型端到端方案在复杂请求中容易出现职责混叠：检索、SQL、工具调用互相串扰，导致错误执行和结果不可解释。多步骤任务在长链路执行中容易失控：交付步骤可能抢跑，中间失败后缺乏可恢复路径，甚至出现循环执行风险。长对话场景下，历史消息不断堆积，既抬高推理成本，也让关键用户事实被噪声淹没，记忆质量随轮次下降。工具调用存在高风险边界：错误工具、越权调用、缺少副作用验证（如“说已发邮件但实际未发”）会直接影响系统可信度。线上异常类型多样（工具执行失败、域判断偏差、结果空输出），如果没有统一评估和降级机制，系统稳定性难以保障。

任务（Task）：将系统从单体 Agent 重构为可治理的多智能体架构，明确 Supervisor 与各类 Worker 的职责边界。设计可控的任务规划与执行机制，让多步骤流程可调度、可追踪、可中断、可恢复。建立可落地的分层记忆体系，平衡上下文成本、对话连续性与长期个性化记忆。形成统一的执行评估标准，对工具调用结果进行策略校验并驱动重试/纠偏/降级。补齐关键评估链路的验证能力，确保容错规则不是“纸面设计”，而是可回归、可复用的工程能力。

行动（Action）：采用 Graph Multi-Agent 架构，引入 Supervisor 统一规划与路由，将任务拆分并分发给 RAG/SQL/TOOL 专属 Worker，同时按运行时能力动态装配可用 Worker。实现 Plan-and-Execute 引擎：基于 TaskPlan/TaskStep 状态机管理步骤生命周期，采用“非交付步骤优先”调度策略，并设置最大步数上限防止死循环。设计并落地分层记忆：短期记忆使用 Redis 热缓存 + DB 冷存储；中期通过异步摘要压缩历史消息；长期将 Facts 向量化入库，并在新一轮推理前按语义召回回灌。将 ReAct 思路工程化为“规划-执行-评估”闭环：Worker 负责行动与证据沉淀，Evaluator 依据策略校验 required/forbidden tools、capability、evidence、side effects，并给出 PASS/RETRY/RECLASSIFY 决策。构建多层容错链路：同 Worker 重试、策略违规反馈重试、候选 Worker fallback、域重分类、失败降级与跳过；同时通过针对性测试覆盖错工具、缺副作用、域不匹配、SQL 执行错误等关键场景。

结果（Result）：系统从“模型自由发挥”升级为“策略驱动执行”，多工具协作过程更可控，路由与执行链路具备可解释性。复杂任务具备了稳定的状态流转和恢复能力，减少了因中间步骤失败导致的整体任务崩溃。长会话下的上下文效率显著提升：通过摘要压缩和分层记忆降低 token 负担，同时保持关键用户事实的可持续利用。工具调用质量与安全性提升：越权/误用工具被及时拦截，关键副作用可被验证，降低“看似完成、实际失败”的风险。整体工程稳定性与可维护性增强：评估与容错逻辑可测试、可回归、可迭代，为后续扩展更多 Worker/工具提供了可复用框架。

JAVASpring AIRAGRedis，LLM

外部链接

演示内容

查看关联博客

基于Graph Agent的智能聊天助手——项目说明文档

1. 项目是什么

本项目是一个基于 Spring Boot + Spring AI 的多智能体聊天系统，核心目标不是“单次对话问答”，而是让 Agent 具备可编排执行能力：

能做任务拆解（Supervisor）
能按任务类型路由到不同 Worker（RAG / SQL / Tool）
能调用工具并根据执行结果重试或回退
能通过 SSE 把执行过程实时推送给前端

前端是 React + Vite + Ant Design，提供会话、Agent 管理、知识库管理与实时消息展示。

2. 核心能力

Agent 图编排执行（GraphEngine）
多模型切换（deepseek-chat / glm-4.6）
工具系统（固定工具 + 可选工具）
知识库检索（PostgreSQL + pgvector + 混合检索）
Redis 热缓存 + DB 冷存储的对话记忆
SSE 实时状态与增量内容推送

3. 技术栈

后端（`graph mind`）

Java 17
Spring Boot 3.5.8
Spring AI 1.1.0
MyBatis
PostgreSQL + pgvector
Redis
Lombok

前端（`ui`）

React 19
TypeScript
Vite（rolldown-vite）
Ant Design 6
Tailwind CSS 4
React Router 7

4. 架构与执行链路

4.1 请求主链路（聊天）

前端调用 POST /api/chat-messages 写入用户消息。
ChatMessageFacadeServiceImpl 发布 ChatEvent。
ChatEventListener 异步消费事件，创建 JChatMind 实例并执行 run()。
JChatMindFactory 按 Agent 配置装配模型、工具、知识库、记忆与图节点。
GraphEngine 从 SUPERVISOR 开始调度到 RAG_WORKER / SQL_WORKER / TOOL_WORKER。
每轮产出的 assistant/tool 消息会持久化并通过 SseService 推送前端。
结束时统一发送 AI_DONE，前端解除输入锁定。

4.2 SSE 消息类型

AI_GENERATED_CONTENT
AI_GENERATED_CONTENT_START
AI_GENERATED_CONTENT_DELTA
AI_GENERATED_CONTENT_END
AI_PLANNING
AI_THINKING
AI_EXECUTING
AI_DONE

5. 目录结构（精简）

JChatMind/
├─ jchatmind/                      # Spring Boot 后端
│  ├─ src/main/java/com/kama/jchatmind/
│  │  ├─ agent/                    # Agent 核心（图编排、工具、记忆）
│  │  ├─ controller/               # REST / SSE 接口
│  │  ├─ service/impl/             # 业务实现
│  │  ├─ mapper/                   # MyBatis Mapper 接口
│  │  ├─ config/                   # 异步、CORS、多模型、Redis 配置
│  │  └─ event/                    # ChatEvent 与监听器
│  └─ src/main/resources/
│     ├─ application.yaml
│     └─ mapper/*.xml              # SQL 映射（agent/chat/kb/document/chunk）
└─ ui/                             # React 前端
   └─ src/
      ├─ api/                      # HTTP 封装与接口定义
      ├─ components/               # 聊天页、知识库页、布局组件
      ├─ hooks/                    # Agents / Sessions / KB / Documents
      └─ contexts/                 # 会话上下文

6. 数据层模型（按 Mapper 推断）

主要表：

agent
chat_session
chat_message
knowledge_base
document
chunk_bge_m3（embedding 为 vector）

说明：

Agent 的 allowed_tools / allowed_kbs / chat_options 存在 JSONB 字段。
向量检索依赖 chunk_bge_m3.embedding <-> query_vector。

7. 关键模块说明

7.1 JChatMindFactory

负责运行时装配：

读取 Agent 配置
选择 ChatClient（按 model 字段）
计算可用工具（固定 + 可选）
根据工具集合决定启用哪些 Worker
构建 GraphEngine

7.2 SupervisorNode

负责：

任务拆分
领域判定（SQL / RAG / TOOL / GENERAL）
工具策略约束与重试
结果评估与最终总结

7.3 DistributedChatMemory

Redis: 热缓存（key: chat:memory:<sessionId>）
PostgreSQL: 冷数据回源
仅保留最近 messageLength 条消息参与上下文

7.4 DocumentFacadeService + RagService

上传 Markdown 后自动解析 section
对 section 标题做 embedding
写入 chunk_bge_m3
检索时执行向量/关键词混合召回

8. 对外接口概览

Agent

GET /api/agents
POST /api/agents
PATCH /api/agents/{agentId}
DELETE /api/agents/{agentId}

会话与消息

GET /api/chat-sessions
GET /api/chat-sessions/{chatSessionId}
GET /api/chat-sessions/agent/{agentId}
POST /api/chat-sessions
PATCH /api/chat-sessions/{chatSessionId}
DELETE /api/chat-sessions/{chatSessionId}
GET /api/chat-messages/session/{sessionId}
POST /api/chat-messages
PATCH /api/chat-messages/{chatMessageId}
DELETE /api/chat-messages/{chatMessageId}

知识库与文档

GET /api/knowledge-bases
POST /api/knowledge-bases
PATCH /api/knowledge-bases/{knowledgeBaseId}
DELETE /api/knowledge-bases/{knowledgeBaseId}
GET /api/documents
GET /api/documents/kb/{kbId}
POST /api/documents
POST /api/documents/upload
PATCH /api/documents/{documentId}
DELETE /api/documents/{documentId}

工具与 SSE

GET /api/tools
GET /sse/connect/{chatSessionId}
GET /health

9. 本地启动（开发环境）

9.1 前置依赖

JDK 17
Maven（或使用 mvnw.cmd）
Node.js 20+
PostgreSQL（需安装 pgvector 扩展）
Redis
Ollama（用于 bge-m3 embedding，默认访问 http://localhost:11434）

9.2 启动后端

cd jchatmind
mvnw.cmd spring-boot:run

默认端口：8080

9.3 启动前端

cd ui
npm install
npm run dev

默认端口通常为：5173

10. 配置说明

核心配置文件：

jchatmind/src/main/resources/application.yaml
jchatmind/src/main/resources/application-dev.yaml

重点配置项：

数据库：spring.datasource.*
Redis：spring.data.redis.*
模型：spring.ai.deepseek.*、spring.ai.zhipuai.*
向量检索参数：vectormodel.*
文档存储目录：document.storage.base-path

建议：

不要把真实 API Key 提交到仓库。
优先使用环境变量注入密钥（如 ${springAI.deepseek.api-key}）。

11. 扩展指南

新增模型：
1. 在 MultiChatClientConfig 增加 ChatClient Bean
2. 保证 Agent model 字段能命中该 Bean 名
新增工具：
1. 实现 com.kama.jchatmind.agent.tools.Tool
2. 用 @org.springframework.ai.tool.annotation.Tool 暴露方法
3. 设置 ToolType（FIXED/OPTIONAL）
4. 在 Agent 配置中控制是否挂载
调整执行策略：
- 修改 SupervisorNode 的领域判定、重试阈值、策略校验逻辑

12. 已知注意事项

目前未发现数据库初始化 SQL 脚本，需要手动建表。
SSE 连接按 chatSessionId 维护，前端应优先建立连接后再发消息。
文件系统工具类当前未启用 @Component，默认不参与工具装配。