Sagent - 智能 RAG 问答系统

Sagent 是一个基于 Spring Boot 和 React 的智能文档检索与问答系统，集成向量数据库（Milvus）、大语言模型（MCP 协议工具调用）、多 AI 供应商支持，提供流式 SSE 对话、知识库管理、深度思考模式、会话记忆等企业级 RAG 功能。

项目概述

本项目旨在构建一个 RAG（Retrieval-Augmented Generation）综合智能体，核心能力包括：

智能问答：基于向量检索增强生成，支持流式 SSE 输出
深度思考模式：调用具备思考能力的大模型（如 Qwen3-Max、GLM-4.7）
会话记忆：多轮对话上下文管理，自动摘要历史消息
MCP 工具生态：通过 MCP（Model Context Protocol）协议与外部工具/服务集成,现已经支持小红书mcp,天气查询mcp, 自动预约mcp
多 AI 供应商：支持阿里百炼、SiliconFlow、Ollama 本地模型，按优先级自动切换
知识库管理：文档解析（PDF/DOC/Markdown）、向量存储、相似度检索、重排序
管理后台：客户信息管理、数据看板

技术架构

技术栈

层级	技术选型	说明
后端框架	Spring Boot 3.5	Java 17+，Web + Jdbc
向量数据库	Milvus 2.6.6	高性能向量检索引擎
对象存储	RustFS（MinIO 兼容）	S3 协议文件存储
关系数据库	MySQL 5.7	结构化数据持久化
缓存	Redis	会话缓存、分布式锁
安全认证	Sa-Token	轻量级权限认证框架
ORM	MyBatis-Plus 3.5	敏捷 CRUD 开发
前端框架	React 18 + TypeScript	现代 SPA 应用
UI 组件	Radix UI + TailwindCSS	无头组件 + 原子化 CSS
状态管理	Zustand	轻量级状态管理
构建工具	Vite 5	极速前端构建
容器化	Docker Compose	一键部署全套基础设施

模块划分

sagent/
├── bootstrap/          # 主服务 - RAG 对话核心逻辑
│   ├── rag/           # RAG 检索与生成
│   │   ├── controller/ # SSE 对话接口
│   │   ├── service/    # 对话服务、流式输出
│   │   ├── core/
│   │   │   ├── mcp/    # MCP 客户端实现
│   │   │   └── prompt/ # Prompt 工程
│   │   └── config/     # Web 配置
│   └── customer/       # 客户管理后台
├── mcp-server/        # MCP Server - 工具服务层
│   ├── executor/       # MCP 工具执行器（客户创建等）
│   ├── service/       # 业务服务层
│   ├── repository/    # 数据访问层
│   └── endpoint/      # MCP 协议端点
├── framework/         # 框架公共模块
│   └── (公共组件、工具类)
├── infra-ai/          # AI 基础设施层
│   └── (AI 调用封装)
└── frontend/          # React 前端应用
    ├── components/    # UI 组件
    ├── pages/         # 页面路由
    ├── services/      # API 调用
    ├── stores/        # 状态管理
    └── styles/        # 全局样式

系统架构图

┌──────────────────────────────────────────────────────────────┐
│                        用户 / 前端                            │
│                    (React + SSE 流式)                        │
└────────────────────────────┬─────────────────────────────────┘
                             │ HTTP / SSE
┌────────────────────────────▼─────────────────────────────────┐
│                    bootstrap (主服务)                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │ RAGChatController │ │ 客户管理接口  │  │ MCP HTTP Client      │ │
│  │  (SSE 流式)   │  │              │  │ (Streamable HTTP)     │ │
│  └──────┬───────┘  └──────────────┘  └──────────┬───────────┘ │
│         │                                          │           │
│  ┌──────▼───────┐                         ┌───────▼────────┐  │
│  │ RAGChatService│                         │  MCP Server   │  │
│  │ ├─ 检索引擎    │                         │ (9099 端口)    │  │
│  │ ├─ Prompt 工程 │                         │ ├─ Customer   │  │
│  │ ├─ AI 调度器   │                         │ │  Executor   │  │
│  │ └─ 流式输出器  │                         │ └─ 工具注册表  │  │
│  └──────┬───────┘                         └───────┬────────┘  │
│         │                                          │           │
│  ┌──────▼────────────────────┐            ┌────────▼────────┐  │
│  │ Milvus SDK               │            │ MySQL           │  │
│  │ (向量检索 + 重排序)       │            │ (结构化数据)     │  │
│  └──────────────────────────┘            └─────────────────┘  │
└──────────────────────────────────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              │     AI 供应商（多路切换）      │
              │  ┌─────────┐ ┌────────────┐  │
              │  │ 阿里百炼  │ │ SiliconFlow│  │
              │  │(Qwen3-Max)│ │ (GLM-4.7) │  │
              │  └─────────┘ └────────────┘  │
              │  ┌─────────────────────────┐ │
              │  │ Ollama (本地模型)       │ │
              │  │ Qwen3-8B + Embedding   │ │
              │  └─────────────────────────┘ │
              └─────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                   基础设施 (Docker Compose)                   │
│  ┌────────────┐ ┌──────────┐ ┌─────────┐ ┌─────────────────┐ │
│  │ Milvus     │ │ RustFS   │ │ MySQL   │ │ Redis           │ │
│  │ :19530     │ │ :9002    │ │ :3306   │ │ :6379           │ │
│  └────────────┘ └──────────┘ └─────────┘ └─────────────────┘ │
│  ┌────────────┐ ┌──────────┐                                  │
│  │ Etcd       │ │ Attu     │                                  │
│  │ (元数据)   │ │ :8001    │                                  │
│  └────────────┘ └──────────┘                                  │
└──────────────────────────────────────────────────────────────┘

快速开始

环境要求

依赖	版本要求	说明
JDK	17+	推荐 Adoptium Eclipse Temurin
Node.js	18+	推荐 LTS 版本
npm / pnpm	最新稳定版
Docker	24+	用于启动基础设施
Docker Compose	2.20+

第一步：启动基础设施

# 进入项目根目录
cd sagent

# 启动全套基础设施（Milvus、MySQL、Redis、RustFS、Etcd）
docker compose -f resources/docker/milvus-stack-2.6.6.compose.yaml up -d

# 等待所有服务健康（约 2 分钟）
docker compose -f resources/docker/milvus-stack-2.6.6.compose.yaml ps

基础设施端口映射：

Milvus: 19530（向量数据库）

Attu（Milvus 可视化）: 8001

RustFS（对象存储）: 9000（S3）、9001（控制台）

MySQL: 13306

Redis: 6379

第二步：创建 MySQL 数据库

-- 连接 MySQL（密码: MilvusUser2026）
mysql -h 127.0.0.1 -P 13306 -u root -pMilvusUser2026

-- 创建数据库
CREATE DATABASE IF NOT EXISTS ragent CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
USE ragent;

-- （后续表结构由 MyBatis-Plus 自动创建或手动导入 SQL 脚本）

第三步：配置 AI 供应商

编辑 bootstrap/src/main/resources/application.yaml，配置你的 AI API Key：

ai:
  providers:
    bailian:
      api-key: sk-your-aliyun-api-key    # 替换为你的阿里云百炼 API Key
    siliconflow:
      api-key: sk-your-siliconflow-key   # 替换为你的 SiliconFlow API Key
    ollama:
      url: http://localhost:11434         # 本地 Ollama 地址

免费方案：推荐使用 SiliconFlow 或阿里百炼，均有免费额度。 本地方案：安装 Ollama 后运行 ollama pull qwen3:8b-fp16。

第四步：启动后端服务

# 编译整个项目（根目录）
mvn clean install -DskipTests

# 启动 MCP Server（工具服务，端口 9099）
cd mcp-server
mvn spring-boot:run
# 或者打包后运行：
# java -jar mcp-server/target/mcp-server-0.0.1-SNAPSHOT.jar

# 新开终端，启动 Bootstrap 主服务（端口 9090）
cd bootstrap
mvn spring-boot:run
# 或者打包后运行：
# java -jar bootstrap/target/bootstrap-0.0.1-SNAPSHOT.jar

第五步：启动前端

cd frontend

# 安装依赖
npm install

# 开发模式启动
npm run dev

# 生产构建
npm run build

前端启动后访问 http://localhost:5173。

Docker 一键部署（生产环境）

# 确保网络已创建
docker network create milvus-net

# 启动基础设施
docker compose -f resources/docker/milvus-stack-2.6.6.compose.yaml up -d

# 启动完整应用
docker compose up -d

在线演示

智能问答演示

体验地址：http://www.supersaiyan.online/chat （演示环境，请勿上传敏感数据）

功能演示

功能	演示截图	说明
深度思考		CoT/ToT 推理过程可视化
MCP 工具调用		调用小红书MCP，进行发帖和检索小红书内容
知识库管理		文档上传、向量检索配置

核心功能详解

1. RAG 流式问答

通过 SSE（Server-Sent Events）实现实时流式输出：

curl -N "http://localhost:9090/api/ragent/rag/v3/chat?question=什么是RAG？"

响应示例（SSE 流格式）：

data: {"type":"thinking","content":"让我先分析这个问题..."}
data: {"type":"thinking","content":"检索相关知识库..."}
data: {"type":"tool_call","content":"customer_create","arguments":"..."}
data: {"type":"tool_result","content":"客户创建成功，ID: 1"}
data: {"type":"text","content":"RAG（Retrieval-Augmented Generation）是一种..."}
data: {"type":"done"}

开启深度思考模式：

curl -N "http://localhost:9090/api/ragent/rag/v3/chat?question=分析...&deepThinking=true"

2. MCP 工具调用

MCP Server 提供可扩展的工具执行能力。内置工具：

工具 ID	功能	参数
`customer_create`	创建客户信息	name, phone, birthDate

工具调用流程：

用户提问
  → RAGChatService 接收请求
    → 向 AI 发送对话请求（含可用工具描述）
      ← AI 返回 tool_use
        → HttpMCPClient 调用 MCP Server
          → CustomerMCPExecutor 执行工具
            → 返回结果给 AI
              → AI 组织最终回复
                → SSE 流式推送

扩展新 MCP 工具：

// 1. 在 mcp-server 中创建 Executor 实现
@Slf4j
@Component
@RequiredArgsConstructor
public class MyMCPExecutor implements MCPToolExecutor {

    @Override
    public MCPToolDefinition getToolDefinition() {
        // 返回工具的 JSON Schema 定义
    }

    @Override
    public MCPToolResponse execute(MCPToolRequest request) {
        // 工具具体逻辑
    }
}

// 2. 注册到工具注册表（MCPServerApplication）
@Bean
public MCPServer mcpServer(List<MCPToolExecutor> executors) {
    return new MCPServer(executors);
}

3. 向量检索与重排序

检索链路（bootstrap/src/main/java/com/nageoffer/ai/ragent/rag/）：

用户 Query
  → Query Rewrite（历史消息上下文扩展）
    → Embedding 模型向量化
      → Milvus 向量数据库检索（余弦相似度）
        → 重排序（Rerank 模型）
          → 返回 Top-K 最相关文档
            → 注入 Prompt上下文
              → LLM 生成最终回复

4. 会话记忆与摘要

多轮对话历史
  → 保留最近 N 轮（默认 4 轮）
    → 超过阈值触发自动摘要
      → 摘要结果替换完整历史
        → 节省 Token 消耗

目录结构参考

sagent/
├── bootstrap/                    # 主服务
│   └── src/main/
│       ├── java/com/nageoffer/ai/ragent/
│       │   ├── rag/
│       │   │   ├── controller/    # REST 控制器
│       │   │   ├── service/       # 业务逻辑
│       │   │   ├── core/
│       │   │   │   ├── mcp/       # MCP 客户端
│       │   │   │   └── prompt/    # Prompt 管理
│       │   │   └── config/        # Spring 配置
│       │   └── customer/          # 客户管理
│       └── resources/
│           └── application.yaml   # 主配置文件
├── mcp-server/                    # MCP 服务
│   └── src/main/java/
│       └── com/nageoffer/ai/ragent/mcp/
│           ├── core/              # MCP 核心类
│           ├── executor/          # 工具执行器
│           ├── service/           # 业务服务
│           ├── repository/        # 数据访问
│           └── endpoint/          # HTTP 端点
├── framework/                     # 公共框架模块
├── infra-ai/                      # AI 基础设施
├── frontend/                      # React 前端
│   ├── src/
│   │   ├── components/            # UI 组件
│   │   ├── pages/                 # 页面
│   │   ├── services/              # API 服务
│   │   ├── stores/                # 状态管理
│   │   ├── router.tsx             # 路由配置
│   │   └── main.tsx               # 入口文件
│   ├── package.json
│   └── vite.config.ts
├── resources/
│   └── docker/
│       ├── milvus-stack-2.6.6.compose.yaml       # 基础设施
│       └── milvus-stack-2.6.6.compose-local.yaml # 本地开发
├── docker-compose.yml            # 应用编排
├── pom.xml                       # 父 POM
└── README.md

API 接口一览

RAG 对话接口

方法	路径	说明
`GET`	`/api/ragent/rag/v3/chat`	SSE 流式问答
`POST`	`/api/ragent/rag/v3/stop`	停止指定任务

管理后台接口

方法	路径	说明
`GET`	`/api/ragent/admin/customer/page`	客户分页查询
`POST`	`/api/ragent/admin/customer`	创建客户

MCP Server 接口

方法	路径	说明
`POST`	`/mcp`	MCP JSON-RPC 2.0 端点

配置参考

application.yaml 关键配置项

server:
  port: 9090

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:13306/ragent
    username: root
    password: MilvusUser2026
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password: RedisAuth8899

milvus:
  uri: http://127.0.0.1:19530

rag:
  default:
    collection-name: rag_default_store
    dimension: 4096
    metric-type: COSINE
  memory:
    history-keep-turns: 4
    summary-enabled: true
  mcp:
    servers:
      - name: default
        url: http://localhost:9099

ai:
  providers:
    ollama:
      url: http://localhost:11434
    bailian:
      api-key: sk-xxx
    siliconflow:
      api-key: sk-xxx
  chat:
    default-model: qwen3-max
  embedding:
    default-model: qwen-emb-8b

rustfs:
  url: http://localhost:9000
  access-key-id: rustfsadmin
  secret-access-key: rustfsadmin

sa-token:
  token-name: Authorization
  timeout: 2592000

项目亮点

MCP 协议集成：遵循 Model Context Protocol 标准，实现 AI Agent 工具调用框架，支持热插拔扩展工具
多 AI 供应商自动切换：支持阿里百炼、SiliconFlow、Ollama，失败自动降级，保障服务高可用
流式 SSE 输出：后端实时流式推送，前端逐字渲染，用户体验流畅
企业级 RAG 流程：Query Rewrite → Vector Search → Rerank → Context Injection → LLM Generation
会话记忆与摘要：智能管理多轮对话上下文，自动压缩历史信息，降低 Token 消耗
深度思考模式：支持具备 CoT/ToT 能力的大模型，提供更深入的推理分析
容器化部署：全套基础设施 Docker Compose 一键启动，开箱即用
现代前端工程：React 18 + TypeScript + TailwindCSS + Radix UI，打造精良的企业级 UI

开发指南

代码规范

项目使用 Spotless Maven Plugin 强制代码格式：

# 自动格式化（编译阶段自动触发）
mvn spotless:apply

常用开发命令

# 编译并跳过测试
mvn clean install -DskipTests

# 只编译指定模块
mvn clean compile -pl bootstrap -am

# 前端类型检查
cd frontend && npm run lint

# 前端格式化
cd frontend && npm run format

常见问题

Q: 启动报错 `Connection refused: milvus-standalone:19530`？

确认 Milvus 容器已正常运行：

docker compose -f resources/docker/milvus-stack-2.6.6.compose.yaml ps

等待 Milvus 健康检查通过（约 2 分钟）。

Q: SSE 流式接口无响应？

检查后端日志，确认 MCP Server 已启动：

curl http://localhost:9099/mcp

Q: AI 调用失败？

确认 API Key 已正确配置，检查网络是否可以访问 AI 供应商服务器。

Q: 如何查看 Milvus 数据？

访问 Attu 可视化管理界面：http://localhost:8001

许可证

本项目基于 Apache License 2.0 开源，欢迎使用和贡献。

致谢

项目使用了以下优秀的开源技术：

Spring Boot - 后端框架
Milvus - 向量数据库
React - 前端框架
Sa-Token - 权限认证
MyBatis-Plus - ORM 框架
TailwindCSS - CSS 框架
Radix UI - 无头 UI 组件库

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.mvn/wrapper		.mvn/wrapper
bootstrap		bootstrap
framework		framework
frontend		frontend
infra-ai		infra-ai
mcp-server		mcp-server
resources		resources
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
lombok.config		lombok.config
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

Sagent - 智能 RAG 问答系统

项目概述

技术架构

技术栈

模块划分

系统架构图

快速开始

环境要求

第一步：启动基础设施

第二步：创建 MySQL 数据库

第三步：配置 AI 供应商

第四步：启动后端服务

第五步：启动前端

Docker 一键部署（生产环境）

在线演示

智能问答演示

功能演示

核心功能详解

1. RAG 流式问答

2. MCP 工具调用

3. 向量检索与重排序

4. 会话记忆与摘要

目录结构参考

API 接口一览

RAG 对话接口

管理后台接口

MCP Server 接口

配置参考

application.yaml 关键配置项

项目亮点

开发指南

代码规范

常用开发命令

常见问题

Q: 启动报错 Connection refused: milvus-standalone:19530？

Q: SSE 流式接口无响应？

Q: AI 调用失败？

Q: 如何查看 Milvus 数据？

许可证

致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Q: 启动报错 `Connection refused: milvus-standalone:19530`？

Packages