# spring-ai-explore

**Repository Path**: zhudunfeng/spring-ai-explore

## Basic Information

- **Project Name**: spring-ai-explore
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# spring-ai-explore

一个基于 **Spring Boot 4**、**Java 21**、**Spring AI 2.0** 与 **AgentScope-Java** 的探索型示例仓库，用于实践 Spring AI 核心能力，并尝试以 AgentScope 风格构建多智能体能力栈。

本仓库面向希望快速理解 Spring AI 2.0 模型接入、RAG、Tool Calling、结构化输出、多模型切换，以及面向 Agent 编排设计思路的开发者。

---

## 项目定位

本仓库不是框架选型产物，而是一个可运行的最小可行示例集，重点回答以下问题：

- 在 Spring 生态里，如何统一接入多模型？
- Spring AI 的 ChatClient、Advisor、VectorStore 如何组合出生产级能力？
- 当业务从“单轮问答”升级到“Agent 路由 + 工具调用 + 记忆 + RAG”时，代码结构应该如何演进？
- Spring AI 与 AgentScope-Java 结合时，模型层、Agent 层、接口层如何分层？

---

## 模块说明

| 模块 | 定位 | 重点能力 |
|------|------|----------|
| `spring-ai-full-example` | Spring AI 2.0 核心示例 | ChatClient、Advisor、RAG、结构化输出、多模型切换、自定义 Advisor |
| `spring-ai-and-agentscope-stype` | 参考 AgentScope 风格实现 | ReAct Agent、RAG 开关、事件系统、工具调用、记忆管理 |
| `spring-ai-and-agentscope` | Spring AI 与 AgentScope-Java 结合 | 模型适配器、Agent 编排、事件监听、多模型路由 |

---

## 技术栈

- Java 21
- Spring Boot 4.1.0
- Spring AI 2.0.0
- PostgreSQL + pgvector
- Maven
- AgentScope-Java：`spring-ai-and-agentscope` 引入，版本 `1.0.12`
- 运行时环境：WSL Ubuntu 22.04

---

## 快速开始

### 环境变量

建议在运行前设置：

```bash
export OPENAI_API_KEY=your_key
export ANTHROPIC_API_KEY=your_key
export DEEPSEEK_API_KEY=your_key
export DB_PASSWORD=your_password
```

> 提示：若暂不使用 PostgreSQL/pgvector，可在对应模块的 `application.yml` 中注释 `spring.datasource.*` 与 `spring.ai.vectorstore.pgvector.*`。

### 构建

```bash
mvn clean package
```

### 运行单个模块

```bash
mvn spring-boot:run -pl spring-ai-full-example
mvn spring-boot:run -pl spring-ai-and-agentscope-stype
mvn spring-boot:run -pl spring-ai-and-agentscope
```

---

## 模块详解

### spring-ai-full-example

这是仓库的主示例模块，集中展示 Spring AI 2.0 的典型用法。

**核心代码路径：**

```text
spring-ai-full-example/src/main/java/com/adun/ai/
├── ChatController.java
├── CodeReviewRequest.java
├── ProductAnalysis.java
├── TechStack.java
├── SpringAiFullExampleApplication.java
├── config/
│   ├── AuditAdvisor.java
│   ├── AuditLogRepository.java
│   ├── ChatClientConfig.java
│   └── VectorStoreAdvisor.java
├── customer/
│   ├── ChatRequest.java
│   ├── ChatResponse.java
│   └── CustomerServiceController.java
├── multimodel/
│   ├── MultiModelConfig.java
│   └── MultiModelService.java
├── rag/
│   ├── DocumentIngestionService.java
│   └── KnowledgeBaseController.java
```

**重点功能：**

- **基础对话与流式输出**
  - `ChatController.chat()`：普通对话
  - `ChatController.streamChat()`：流式响应

- **结构化输出**
  - `ChatController.analyzeProduct()`：映射到 `ProductAnalysis`
  - `ChatController.recommendTechStacks()`：映射到 `List<TechStack>`

- **多模型切换**
  - `MultiModelConfig`：注册 OpenAI、Anthropic、Ollama 的 `ChatClient`
  - `MultiModelService.chat()`：按 `modelProvider` 动态切换

- **RAG 知识库**
  - `KnowledgeBaseController`：文档检索问答
  - `DocumentIngestionService`：文档摄入

- **Advisor 链**
  - `VectorStoreAdvisor`：检索增强
  - `AuditAdvisor`：审计埋点，记录请求与响应

- **智能客服示例**
  - `CustomerServiceController`：组合记忆、RAG 与工具调用

---

### spring-ai-and-agentscope-stype

该模块在不引入 AgentScope-Java 的前提下，以“AgentScope 风格”手写轻量 Agent 能力栈，适合理解 ReAct、RAG 开关、事件系统与记忆管理的内部运作。

**核心代码路径：**

```text
spring-ai-and-agentscope-stype/src/main/java/com/adun/ai/springaiandagentscope/
├── ChatController.java
├── SpringAiAndAgentscopeStyleApplication.java
├── agent/
│   ├── AgentEvent.java
│   ├── AgentEventListener.java
│   └── ReActAgent.java
├── config/
│   ├── AgentScopeConfig.java
│   ├── MemoryConfig.java
│   └── MultiModelConfig.java
├── multimodel/
│   ├── MultiModelConfig.java
│   └── MultiModelService.java
├── rag/
│   ├── RagConfig.java
│   ├── DocumentIngestionService.java
│   └── KnowledgeBaseController.java
└── tools/
    ├── OrderTool.java
    └── WeatherTool.java
```

**重点能力：**

- **ReActAgent**
  - 基于推理-行动循环实现 Agent 执行
  - 支持配置最大迭代次数、RAG 开关、TopK 等参数

- **事件系统**
  - `AgentEvent`：定义 Agent 生命周期事件
  - `AgentEventListener`：收集执行轨迹，便于可视化或接入可观测平台

- **RAG 能力**
  - `KnowledgeBaseController`：普通问答与 RAG 增强问答
  - `DocumentIngestionService`：文档摄入

- **接口示例**
  - `GET /api/chat?message=xxx`
  - `GET /api/chat/agent/ask?question=xxx`
  - `GET /api/chat/rag/enabled?message=xxx`
  - `GET /api/chat/rag/disabled?message=xxx`
  - `GET /api/knowledge/ask?question=xxx`
  - `GET /api/knowledge/rag/ask?question=xxx`
  - `GET /api/knowledge/ingest?content=xxx&id=xxx`

---

### spring-ai-and-agentscope

该模块引入 **AgentScope-Java**，展示如何将 Spring AI 作为模型接入层，AgentScope 作为 Agent 编排层，两层协作构建多智能体系统。

**核心代码路径：**

```text
spring-ai-and-agentscope/src/main/java/com/adun/ai/springaiandagentscope/
├── ChatController.java
├── SpringAiAndAgentscopeApplication.java
├── agent/
│   ├── AgentEvent.java
│   ├── AgentEventListener.java
│   ├── AgentEventPublisher.java
│   └── SpringAiChatModelAdapter.java
├── config/
│   └── AgentScopeConfig.java
├── multimodel/
│   ├── MultiModelConfig.java
│   └── MultiModelService.java
└── tools/
    ├── OrderTool.java
    └── WeatherTool.java
```

**重点能力：**

- **SpringAiChatModelAdapter**
  - 将 Spring AI 的 `ChatModel` 适配为 AgentScope 的 `Model`
  - 负责消息格式映射与响应转换

- **AgentScopeConfig**
  - 组装 Agent、Memory、Model
  - 展示 Spring 容器与 AgentScope 框架的集成方式

- **多模型路由**
  - `MultiModelConfig`：注册多模型 `ChatClient`
  - `MultiModelService`：按 provider 切换模型

- **事件系统**
  - `AgentEventPublisher`：在 Agent 执行阶段发布事件
  - `AgentEventListener`：记录执行轨迹

- **接口示例**
  - `GET /api/chat?message=xxx`
  - `GET /api/chat/stream?message=xxx`
  - `GET /api/chat/weather?city=北京`
  - `GET /api/chat/order?orderId=123`

---

## 配置说明

各模块的 `application.yml` 中已预设：

- **模型配置**
  - `spring.ai.openai`：OpenAI / DeepSeek 兼容配置
  - `spring.ai.anthropic`：Claude 模型配置
  - `spring.ai.ollama`：本地 Ollama 模型配置

- **向量库配置**
  - `spring.ai.vectorstore.pgvector`：索引类型、距离类型、维度
  - `spring.datasource`：PostgreSQL 连接配置

- **并发配置**
  - `spring.threads.virtual.enabled`：启用虚拟线程

---

## 模块关系与运行方式

```text
spring-ai-explore
├── spring-ai-full-example            # Spring AI 核心示例，建议先跑通
├── spring-ai-and-agentscope-stype    # 手写 AgentScope 风格，适合理解 Agent 内部机制
└── spring-ai-and-agentscope          # 引入 AgentScope-Java，适合理解框架集成方式
```

建议按以下顺序学习：

1. 先运行 `spring-ai-full-example`，理解 ChatClient、Advisor、RAG、结构化输出
2. 再阅读 `spring-ai-and-agentscope-stype`，理解 ReAct 与事件系统
3. 最后研究 `spring-ai-and-agentscope`，理解模型适配器与 AgentScope-Java 集成

---

## 补充文档

仓库内还包含两份可作为延伸阅读的文档：

- `SpringAi2_案例1.md`：Spring AI 2.0 系列教程，涵盖基础对话、流式输出、结构化输出、Tool Calling、RAG、Advisor 链、多模型切换与 Spring Boot 4 新特性
- `框架比对文档.md`：Spring AI、Spring AI Alibaba、AgentScope Java 的核心特性、适用场景与选型建议对比

---

## 注意事项

- 本项目为探索型示例，未包含完整鉴权、异常处理、容错与重试机制
- 部分工具返回为模拟数据，接入真实业务前需替换为实际服务调用
- 模块内存在包名书写风格差异，遵循历史代码现状，不做统一重命名
- PostgreSQL 与 pgvector 相关依赖已声明，是否启用可根据环境按需调整

---

## 协议

Apache 2.0