刘洋 | 个人网站
ProjectsApr 1, 20266 分钟/阅读时间

基于Graph Agent的智能聊天助手 - Project Detail

基于Graph Agent的智能聊天助手 - Project Detail
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 请求主链路（聊天）

  1. 前端调用 POST /api/chat-messages 写入用户消息。
  2. ChatMessageFacadeServiceImpl 发布 ChatEvent。
  3. ChatEventListener 异步消费事件，创建 JChatMind 实例并执行 run()。
  4. JChatMindFactory 按 Agent 配置装配模型、工具、知识库、记忆与图节点。
  5. GraphEngine 从 SUPERVISOR 开始调度到 RAG_WORKER / SQL_WORKER / TOOL_WORKER。
  6. 每轮产出的 assistant/tool 消息会持久化并通过 SseService 推送前端。
  7. 结束时统一发送 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，默认不参与工具装配。