# spring-ai-alibaba-example

**Repository Path**: 21501428/spring-ai-alibaba-example

## Basic Information

- **Project Name**: spring-ai-alibaba-example
- **Description**: Spring ai alibaba的示例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI Alibaba Example

基于 Spring AI Alibaba 的分布式 AI 代理通信示例项目，展示了 Agent-to-Agent (A2A) 通信、Model Context Protocol (MCP)、图计算工作流、RAG、记忆管理等核心能力的完整实现。

## 项目架构

### 模块结构

```
spring-ai-alibaba-example/
├── spring-ai-alibaba-common/              # 公共配置模块
├── spring-ai-alibaba-agent/               # AI 代理模块 (A2A 通信)
│   ├── agent-nacos-register/              # 标准 A2A 代理注册服务 (9999)
│   ├── agent-nacos-a2a-discovery/         # 标准 A2A 代理发现服务
│   ├── agent-nacos-agentcard-register/    # AgentCard 注册服务 (9093)
│   └── agent-nacos-agentcard-discovery/   # AgentCard 发现服务 (9098)
├── spring-ai-alibaba-graph/               # AI 图计算模块 (StateGraph 工作流)
│   ├── human-node/                        # 人机交互节点 (8081)
│   ├── mcp-node/                          # MCP 协议节点 (8050)
│   ├── parallel-node/                     # 并行处理节点 (8071)
│   └── steam-node/                        # 流式处理节点 (8076)
├── spring-ai-alibaba-mcp/                 # MCP 协议模块
│   ├── mcp-nacos-register/                # MCP 服务注册 (8082)
│   └── mcp-nacos-discovery/               # MCP 服务发现 (8085)
├── spring-ai-alibaba-nacos-prompt/        # Nacos Prompt 模板服务 (10010)
├── spring-ai-alibaba-chat-memory/         # 聊天记忆示例 (8073)
├── spring-ai-alibaba-vectorstore/         # 向量存储示例
│   └── vectorstore-redis/                 # Redis 向量存储 (8052)
├── spring-ai-alibaba-workflow/            # 工作流示例 (8059)
├── spring-ai-alibaba-rag/                 # RAG 示例 (8035)
├── spring-ai-alibaba-hybrid-rag/          # 混合 RAG 示例
│   ├── dashscope-hybrid-rag/              # DashScope 混合 RAG (8021)
│   └── deepseek-hybrid-rag/               # DeepSeek 混合 RAG (8022)
├── spring-ai-alibaba-observability/       # 可观测性示例
│   └── zipkin-report/                     # Zipkin 链路追踪 (8055)
└── mutil-agent/                           # 多 Agent 协作示例 (8058)
```
### 核心组件

- **Common Module**: 统一配置管理，包含 Nacos 和 Agent 配置属性
- **Agent Module**: 实现 A2A (Agent-to-Agent) 协议的代理注册、发现和通信
- **Graph Module**: 实现基于图计算的 AI 处理流程，支持人机交互、MCP 集成、并行处理和流式输出
- **MCP Module**: 实现 Model Context Protocol 的服务注册和发现，支持工具调用和资源访问
- **Nacos Prompt Module**: 通过 Nacos 动态管理 Prompt 模板，运行时热更新
- **Chat Memory**: 支持 Redis/MySQL 后端的聊天记忆管理
- **VectorStore**: 基于 Redis/Elasticsearch 的向量存储示例
- **Workflow**: 工作流示例，包含条件节点和文本处理
- **RAG/Hybrid RAG**: 检索增强生成示例，支持基础 RAG 和混合 RAG（重排序）
- **Observability**: 链路追踪和可观测性示例，集成 Zipkin
- **Mutil-Agent**: 多 Agent 协作示例（Writer + Reviewer + Orchestrator）

#### 1. Common 模块 (spring-ai-alibaba-common)

Common 模块提供了项目的公共配置和工具类，确保各模块间的配置一致性。

- **配置管理**: 统一的 Nacos 连接配置和 Agent 属性配置
- **工具类**: 公共的工具方法和常量定义

#### 2. Agent 模块 (spring-ai-alibaba-agent)

Agent 模块实现了完整的 A2A (Agent-to-Agent) 通信协议，支持代理间的服务注册、发现和通信。

- **agent-nacos-register**: 标准 A2A 代理注册服务，提供基础的代理注册功能
- **agent-nacos-a2a-discovery**: 标准 A2A 代理发现服务，实现代理间的服务发现
- **agent-nacos-agentcard-register**: AgentCard 注册服务，提供增强的代理卡片注册功能
- **agent-nacos-agentcard-discovery**: AgentCard 发现服务，支持代理卡片的发现和管理
#### 3. Graph 模块 (spring-ai-alibaba-graph)

Graph 模块实现了基于 StateGraph 的 AI 处理流程，支持多种节点类型、并行处理和流式输出。

**3.1 human-node** (端口 8081): 人机交互节点
- **功能**: 支持用户反馈、对话管理和人工确认流程
- **核心节点类**:
  - `ExpanderNode`: 使用 AI 模型扩展输入文本
  - `TranslateNode`: 将文本翻译成目标语言
  - `HumanFeedbackNode`: 等待人工反馈并路由到下一个节点
- **示例接口**:
  - `GET /graph/human/expand?query=你好` - 启动扩展流程
  - `GET /graph/human/resume?thread_id=xxx` - 恢复等待人工反馈的流程

**3.2 mcp-node** (端口 8050): MCP 协议节点
- **功能**: 集成 MCP 客户端进行工具调用和资源访问
- **核心节点类**:
  - `McpNode`: 调用 MCP 工具并返回结果
- **示例接口**:
  - `GET /graph/mcp/call?query=当前时间` - 调用 MCP 工具 (如时间服务)

**3.3 parallel-node** (端口 8071): 并行处理节点
- **功能**: 支持多线程并行处理和结果收集
- **核心节点类**:
  - `DispatcherNode`: 分发任务到翻译器和扩展器
  - `ExpanderNode`: 使用 AI 模型扩展输入文本
  - `TranslateNode`: 将文本翻译成目标语言
  - `CollectorNode`: 收集并行处理结果并路由到下一个节点
- **示例接口**:
  - `GET /graph/stream/expand?query=你好` - 启动并行处理流程

**3.4 steam-node** (端口 8076): 流式处理节点
- **功能**: 支持流式输出和实时处理
- **示例接口**:
  - `GET /graph/stream/expand?query=你好` - 启动流式处理流程
#### 4. MCP 模块 (spring-ai-alibaba-mcp)

MCP (Model Context Protocol) 模块实现了模型上下文协议，提供了标准化的模型通信接口。

- **mcp-nacos-register**: MCP 服务注册中心，负责 MCP 服务的注册和管理
- **mcp-nacos-discovery**: MCP 服务发现，提供 MCP 服务的发现和负载均衡

#### 5. Nacos Prompt 模块 (spring-ai-alibaba-nacos-prompt)

该模块通过 Nacos 托管 Prompt 模板，实现模板的动态下发与监听，结合 DashScope 模型生成流式响应。

- **配置来源**: `spring.config.import: "optional:nacos:prompt-config.json"`
- **Nacos 连接**: 使用 `spring.cloud.nacos.config.*` 参数连接到 `${TENCENT_CLOUD_IP}:8848`
- **Prompt 监听**: 通过 `spring.ai.alibaba.nacos.prompt.template.enabled: true` 启用监听
- **示例接口**: `GET /prompt/instruduce?personName=周杰伦`

接口位置：`spring-ai-alibaba-nacos-prompt/src/main/java/com/bruce/ai/alibaba/nacos/prompt/controller/PromptController.java:45`

返回内容为模型的流式输出，可通过浏览器或 curl 查看。

#### 6. Chat Memory 模块 (spring-ai-alibaba-chat-memory)

支持多种存储后端的聊天记忆功能，实现对话历史的持久化管理。

- **Redis 存储**: 使用 `RedissonRedisChatMemoryRepository`
- **MySQL 存储**: 使用 `MysqlChatMemoryRepository`
- **示例接口**: `GET /advisor/memory/redis/call?query=你好&conversation_id=asurada`
- **示例接口**: `GET /advisor/memory/redis/messages?conversation_id=asurada`

#### 7. VectorStore 模块 (spring-ai-alibaba-vectorstore/vectorstore-redis)

基于 Redis 的向量存储示例，支持文档的向量化存储和相似度检索。

- **导入文档**: `GET /redis/import?messages=Spring AI rocks&owerName=bruce`
- **搜索文档**: `GET /redis/search?query=Spring AI`
- **删除文档**: `GET /redis/delete-filter?owerName=bruce`

#### 8. Workflow 模块 (spring-ai-alibaba-workflow)

工作流示例，包含条件节点和文本处理流程。

- **核心配置**: `WorkflowConfiguration`
- **示例接口**: `GET /workflow/expand?query=你好`

#### 9. RAG 模块 (spring-ai-alibaba-rag)

基础 RAG（检索增强生成）示例，使用 Redis 向量存储。

- **示例接口**: `GET /rag?query=Context7`
- **导入文档**: `GET /import`

#### 10. Hybrid RAG 模块 (spring-ai-alibaba-hybrid-rag)

**DashScope Hybrid RAG** (端口 8021):
- 使用 DashScope 重排序模型提升检索精度
- Elasticsearch 向量存储
- 示例接口：`GET /rag?query=Context7`

**DeepSeek Hybrid RAG** (端口 8022):
- 使用 DeepSeek 模型生成答案
- 支持 PDF 文档解析
- 示例接口：`GET /hybrid-rag/chat?query=你好`
- 示例接口：`GET /hybrid-rag/ingest?content=文本内容`
- 示例接口：`GET /hybrid-rag/ingest-pdfs` - 导入 PDF 文档

#### 11. Mutil-Agent 模块 (mutil-agent)

多 Agent 协作示例，包含 Writer、Reviewer 和 Orchestrator 三种角色。

- **核心配置**: `MutilAgentConfig`
- **示例接口**: `GET /api/agents/invoke?messages=请写一篇关于友谊的散文`

#### 12. Observability 模块 (spring-ai-alibaba-observability/zipkin-report)

链路追踪和可观测性示例，集成 Zipkin 和 Micrometer Tracing。

- 支持请求日志和追踪采样
- 端口：8055

## 项目逻辑

### A2A (Agent-to-Agent) 通信流程

1. **代理注册**: Agent 通过 Nacos 注册中心注册自身信息和能力
   - 端点：`GET /agentcard` - 返回 AgentCard 信息
2. **服务发现**: 其他 Agent 通过 Nacos 发现可用的代理服务
   - 支持 Nacos AI Service 和 REST API 两种方式
3. **直接通信**: Agent 之间建立直接的 HTTP 通信连接
   - 端点：`POST /a2a/call` - 符合 A2A 协议的标准调用
4. **能力调用**: 通过标准化的 A2A 协议进行能力调用和数据交换

### MCP (Model Context Protocol) 流程

1. **MCP 服务注册**: MCP 服务器在 Nacos 中注册工具和资源
   - 示例工具：`TimeService.getCityTimeMethod()` - 获取指定时区时间
2. **客户端发现**: MCP 客户端发现并连接到可用的 MCP 服务
3. **工具调用**: 通过 MCP 协议调用远程工具和访问资源
4. **AI 集成**: 与大语言模型集成，提供增强的 AI 能力

### Graph 工作流流程

1. **状态图定义**: 通过 StateGraph 定义处理流程
2. **节点配置**: 添加各种处理节点（expander、translate、human_feedback 等）
3. **边配置**: 配置节点间的连接关系（顺序边、条件边、并行边）
4. **执行流程**: 通过 StateMachine 执行工作流

### RAG 流程

1. **文档导入**: 将文档切分为 Document 对象并导入向量存储
2. **相似度检索**: 根据用户查询检索最相关的文档
3. **答案生成**: 将检索到的文档作为上下文，结合用户查询生成答案
4. **重排序** (Hybrid RAG): 使用重排序模型对检索结果进行精排序
### 关键特性

- **服务注册与发现**: 基于 Nacos 的分布式服务管理
- **负载均衡**: 支持多实例部署和负载均衡
- **熔断机制**: 内置熔断器模式，提高系统稳定性
- **重试机制**: 指数退避重试策略
- **多种认证**: 支持 JWT、OAuth2、API Key 等认证方式
- **异步通信**: 支持同步和异步调用模式
- **图计算工作流**: 支持状态图、条件分支、并行处理
- **记忆管理**: 支持 Redis/MySQL 后端的聊天记忆
- **向量检索**: 支持 Redis/Elasticsearch 向量存储
- **RAG 能力**: 支持基础 RAG 和混合 RAG（重排序）
- **多 Agent 协作**: 支持多 Agent 协同工作
- **可观测性**: 集成 Zipkin 链路追踪
- **节点类实现**: 提供完整的 NodeAction 实现类，支持 AI 扩展、翻译、人机交互、并行处理等能力

## 节点类说明

### human-node 模块节点类

**ExpanderNode**:
- **功能**: 使用 AI 模型扩展输入文本
- **输入**: `query` - 原始查询文本
- **输出**:
  - `expander_content`: 扩展后的内容
  - `expander_status`: 执行状态
  - `expander_number`: 扩展编号

**TranslateNode**:
- **功能**: 将文本翻译成目标语言
- **输入**:
  - `text`: 待翻译文本
  - `target_language`: 目标语言
- **输出**:
  - `translate_content`: 翻译后的内容
  - `translate_status`: 执行状态
  - `translate_language`: 目标语言

**HumanFeedbackNode**:
- **功能**: 等待人工反馈并路由到下一个节点
- **输入**: 等待用户输入反馈
- **输出**:
  - `feed_back`: 用户反馈内容
  - `human_next_node`: 下一个节点 (translate 或 END)

### parallel-node 模块节点类

**DispatcherNode**:
- **功能**: 分发任务到翻译器和扩展器
- **输入**: `query` - 原始查询文本
- **输出**:
  - `translate_language`: 翻译目标语言
  - `dispatch_status`: 分发状态

**CollectorNode**:
- **功能**: 收集并行处理结果并路由到下一个节点
- **输入**: 并行节点的执行结果
- **输出**:
  - `collector_result`: 收集的结果
  - `collector_next_node`: 下一个节点 (dispatcher 或 END)

### mcp-node 模块节点类

**McpNode**:
- **功能**: 调用 MCP 工具并返回结果
- **输入**: `query` - 查询文本
- **输出**:
  - `mcp_content`: MCP 工具返回的内容
  - `mcp_status`: 执行状态

## 环境要求

### 基础环境

- **Java**: JDK 21+
- **Maven**: 3.6+
- **Spring Boot**: 3.4.0
- **Spring AI**: 1.0.0
- **Spring AI Alibaba**: 1.1.0.0-M5

### 外部依赖

- **Nacos Server**: 2.3.0+ (服务注册与发现)
- **通义千问 API**: 阿里云大模型服务 (需要 API Key)
- **DeepSeek API**: DeepSeek 模型服务 (可选，用于 Hybrid RAG)
- **Redis**: 6.x+ (聊天记忆和向量存储)
- **MySQL**: 8.x+ (聊天记忆，可选)
- **Elasticsearch**: 8.x+ (向量存储，Hybrid RAG 可选)

### 环境变量配置

| 变量名 | 描述 | 示例值 |
|--------|------|--------|
| `TENCENT_CLOUD_IP` | Nacos/Redis/MySQL 服务器地址 | `127.0.0.1` |
| `NACOS_NAMESPACE` | Nacos 命名空间 | `dev` |
| `NACOS_USERNAME` | Nacos 用户名 | `nacos` |
| `NACOS_PASSWORD` | Nacos 密码 | `nacos` |
| `TONGYI_AI_KEY` | 通义千问 API Key | `sk-xxx` |
| `AGENT_NAME` | 代理名称 | `asurada-agent-test-9375` |
| `TARGET_AGENT_NAME` | 目标代理名称 | `asurada-agent-test-9375` |
| `DEEPSEEK_API_KEY` | DeepSeek API Key (可选) | `sk-xxx` |

## 快速开始

### 1. 环境准备

```bash
# 启动 Nacos Server (Docker)
docker run --name nacos -d \
  -p 8848:8848 \
  -p 9848:9848 \
  -e MODE=standalone \
  nacos/nacos-server:v2.3.0

# 设置环境变量
export TENCENT_CLOUD_IP=127.0.0.1
export NACOS_NAMESPACE=dev
export NACOS_USERNAME=nacos
export NACOS_PASSWORD=nacos
export TONGYI_AI_KEY=your-api-key
```

### 2. 编译项目

```bash
# 编译公共模块
cd spring-ai-alibaba-common
mvn clean install -DskipTests

# 编译整个项目
cd ..
mvn clean compile
```

### 3. 启动服务

```bash
# 启动 AgentCard 注册服务
cd spring-ai-alibaba-agent/agent-nacos-agentcard-register
AGENT_NAME=asurada-agent-test-9375 mvn spring-boot:run

# 启动 AgentCard 发现服务
cd ../agent-nacos-agentcard-discovery
TARGET_AGENT_NAME=asurada-agent-test-9375 mvn spring-boot:run

# 启动 MCP 注册服务
cd ../../spring-ai-alibaba-mcp/mcp-nacos-register
mvn spring-boot:run

# 启动 MCP 发现服务
cd ../mcp-nacos-discovery
mvn spring-boot:run

# 启动 Nacos Prompt 模板服务
cd ../../spring-ai-alibaba-nacos-prompt
mvn spring-boot:run

# 启动 Chat Memory 服务
cd ../spring-ai-alibaba-chat-memory
mvn spring-boot:run

# 启动 VectorStore 服务
cd ../spring-ai-alibaba-vectorstore/vectorstore-redis
mvn spring-boot:run

# 启动 Workflow 服务
cd ../spring-ai-alibaba-workflow
mvn spring-boot:run

# 启动 RAG 服务
cd ../spring-ai-alibaba-rag
mvn spring-boot:run

# 启动 Hybrid RAG 服务
cd ../spring-ai-alibaba-hybrid-rag/dashscope-hybrid-rag
mvn spring-boot:run

# 启动 Mutil-Agent 服务
cd ../../mutil-agent
mvn spring-boot:run

# 启动 Graph 模块服务
cd ../spring-ai-alibaba-graph/human-node
mvn spring-boot:run

# 启动 MCP Node 服务
cd ../mcp-node
mvn spring-boot:run

# 启动 Parallel Node 服务
cd ../parallel-node
mvn spring-boot:run

# 启动 Steam Node 服务
cd ../steam-node
mvn spring-boot:run
```

### 4. 验证服务

- **Nacos 控制台**: http://localhost:8848/nacos (nacos/nacos)
- **AgentCard 注册服务**: http://localhost:9093/health
- **AgentCard 发现服务**: http://localhost:9098
- **MCP 注册服务**: http://localhost:8081
- **MCP 发现服务**: http://localhost:8085
- **Nacos Prompt 服务**: http://localhost:10010
  - 示例接口：http://localhost:10010/prompt/instruduce?personName=周杰伦
- **Chat Memory 服务**: http://localhost:8073
  - 示例接口：http://localhost:8073/advisor/memory/redis/call?query=你好&conversation_id=test
- **VectorStore 服务**: http://localhost:8052
  - 示例接口：http://localhost:8052/redis/import?messages=Spring AI rocks&owerName=bruce
- **Workflow 服务**: http://localhost:8059
  - 示例接口：http://localhost:8059/workflow/expand?query=你好
- **RAG 服务**: http://localhost:8035
  - 示例接口：http://localhost:8035/rag?query=Context7
- **Hybrid RAG 服务**: http://localhost:8021
  - 示例接口：http://localhost:8021/rag?query=Context7
- **Mutil-Agent 服务**: http://localhost:8058
  - 示例接口：http://localhost:8058/api/agents/invoke?messages=请写一篇关于友谊的散文
- **Graph Human Node**: http://localhost:8081
  - 示例接口：http://localhost:8081/graph/human/expand?query=你好
- **Graph MCP Node**: http://localhost:8050
  - 示例接口：http://localhost:8050/graph/mcp/call?query=当前时间

## 服务端口

| 服务 | 端口 | 描述 |
|------|------|------|
| agent-nacos-register | 9999 | 标准 A2A 代理注册 |
| agent-nacos-a2a-discovery | - | 标准 A2A 代理发现 |
| agent-nacos-agentcard-register | 9093 | AgentCard 注册服务 |
| agent-nacos-agentcard-discovery | 9098 | AgentCard 发现服务 |
| mcp-nacos-register | 8082 | MCP 服务注册 (已修正端口冲突) |
| mcp-nacos-discovery | 8085 | MCP 服务发现 |
| nacos-prompt | 10010 | 动态 Prompt 模板服务 |
| human-node | 8081 | 人机交互节点服务 |
| mcp-node | 8050 | MCP 协议节点服务 |
| parallel-node | 8071 | 并行处理节点服务 |
| steam-node | 8076 | 流式处理节点服务 |
| chat-memory | 8073 | 聊天记忆服务 |
| vectorstore-redis | 8052 | Redis 向量存储服务 |
| workflow | 8059 | 工作流服务 |
| rag | 8035 | RAG 服务 |
| dashscope-hybrid-rag | 8021 | DashScope 混合 RAG |
| deepseek-hybrid-rag | 8022 | DeepSeek 混合 RAG |
| zipkin-report | 8055 | Zipkin 链路追踪 |
| mutil-agent | 8058 | 多 Agent 协作服务 |

## 配置说明（Nacos Prompt）

- 在 `spring-ai-alibaba-nacos-prompt/src/main/resources/application.yml` 中，`spring.config.import` 使用 Nacos 的 `prompt-config.json`：
  - 连接参数通过 `spring.cloud.nacos.config.server-addr=${TENCENT_CLOUD_IP}:8848` 与 `namespace=dev` 指定
  - 监听开关通过 `spring.ai.alibaba.nacos.prompt.template.enabled=true` 启用
- 在 Nacos 控制台 `dev` 命名空间下创建 `dataId=prompt-config.json`，示例：
  ```json
  {
    "templates": [
      {
        "name": "instruduce",
        "description": "人物简介",
        "template": "请简单介绍一下{{personName}}，100 字以内。"
      }
    ]
  }
  ```

## 配置说明（Chat Memory）

Chat Memory 模块支持 Redis 和 MySQL 两种存储后端，通过 `application.yml` 配置启用：

```yaml
memory:
  redis:
    enabled: true
    host: ${TENCENT_CLOUD_IP}
    port: 6379
  mysql:
    jdbc-url: jdbc:mysql://${TENCENT_CLOUD_IP}:3306/ai_chat_memory
    enabled: true
```

## 配置说明（VectorStore）

VectorStore 模块基于 Redis 实现向量存储，配置示例：

```yaml
spring:
  data:
    redis:
      host: ${TENCENT_CLOUD_IP}
      port: 6379
```

## 故障排除

- `config[dataId=prompt-config.json] is empty`：Nacos 中未创建或内容为空，按上文示例创建后重试
- `Port 10010 was already in use`：释放占用端口后重启
- BeanPostProcessor 警告：Spring Cloud Alibaba 在初始化阶段的提示，属正常现象，不影响功能
- Redis 连接失败：检查 Redis 服务是否启动，防火墙是否开放 6379 端口
- MySQL 连接失败：检查数据库是否存在，用户名密码是否正确

## 技术栈

- **框架**: Spring Boot 3.4.0, Spring AI 1.0.0, Spring AI Alibaba 1.1.0.0-M5
- **服务发现**: Nacos 2.3.0+
- **AI 模型**: 阿里云通义千问 (DashScope), DeepSeek
- **通信协议**: HTTP/HTTPS, A2A Protocol, MCP Protocol
- **序列化**: Jackson JSON, Fastjson
- **HTTP 客户端**: OkHttp 4.12.0, WebFlux
- **存储**: Redis 6.x, MySQL 8.x, Elasticsearch 8.x
- **向量存储**: Spring AI Redis VectorStore, Elasticsearch VectorStore
- **可观测性**: Zipkin, Micrometer Tracing
- **构建工具**: Maven 3.6+

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。