基于 Spring AI Alibaba 的 AI 应用开发示例项目,包含 18 个渐进式学习模块,覆盖从 HelloWorld 入门到 Agent 工作流编排的完整技术栈。每个模块文档均位于各自 docs/ 目录下。
| 组件 | 版本 | 说明 |
|---|---|---|
| JDK | 17+ | 项目统一使用 Java 17 编译 |
| Maven | 3.6+ | 构建和模块管理 |
| Spring Boot | 3.5.14 | 由父 POM 统一管理 |
| Spring AI | 1.1.2 | 核心 Spring AI 框架 |
| Spring AI Alibaba | 1.1.2.0 | DashScope 等阿里云模型适配 |
| DashScope API Key | — | 阿里云百炼平台申请,设为环境变量 aliQwen-api |
| Redis | 7.x+(推荐 Stack 版) | SAA-10/11/12 模块依赖,提供向量检索和记忆持久化 |
| Ollama | 可选 | SAA-02 模块演示本地模型时需要,其余模块非必需 |
配置 API Key:
在系统环境变量或 IDE 启动配置中设置 aliQwen-api=你的DashScope API Key。各模块的 application.properties 通过 ${aliQwen-api} 读取。
springAIAlibaba-guigu/
│
├── pom.xml # 父 POM,统一版本管理(18 个子模块)
├── .gitignore # Git 忽略规则
├── README.md # 本文件
│
├── SAA-01HelloWorld/ # 入门:Spring AI Alibaba 最小示例
│ └── docs/01-HelloWorld.md
│
├── SAA-02Ollama/ # 本地模型:同时接入 DashScope + Ollama
│ └── docs/02-Ollama.md
│
├── SAA-03ChatModelChatClient/ # API 对比:ChatModel vs ChatClient
│ └── docs/03-ChatModelChatClient.md
│
├── SAA-04StreamingOutput/ # 流式输出 + 多模型并存
│ └── docs/04-StreamingOutput.md
│
├── SAA-05Prompt/ # Prompt 对象与消息体系
│ └── docs/05-Prompt.md
│
├── SAA-06PromptTemplate/ # Prompt 模板与外部文件化
│ └── docs/06-PromptTemplate.md
│
├── SAA-07StructuredOutput/ # 结构化输出:AI 返回 Java 对象
│ └── docs/07-StructuredOutput.md
│
├── SAA-08Advisor/ # 拦截器链:内置 + 自定义 Advisor
│ └── docs/08-Advisor.md
│
├── SAA-09ChatMemory/ # 对话记忆:内存存储版
│ └── docs/09-ChatMemory.md
│
├── SAA-10PersistentMemory/ # 对话记忆:Redis 持久化版
│ └── docs/10-PersistentMemory.md
│
├── SAA-11Embed2Vector/ # 文本向量化与向量检索
│ └── docs/11-Embed2Vector.md
│
├── SAA-12RAG4AiOps/ # RAG 检索增强生成(AIOps 场景)
│ └── docs/12-RAG4AiOps.md
│
├── SAA-13ToolCalling/ # Tool Calling(函数调用)
│ └── docs/13-ToolCalling.md
│
├── SAA-14LocalMcpServer/ # MCP Server(工具提供方)
│ └── docs/14-LocalMcpServer.md
│
├── SAA-15LocalMcpClient/ # MCP Client(工具消费方 + AI 模型)
│ └── docs/15-LocalMcpClient.md
│
├── SAA-16Text2Image/ # 文生图:通义万相
│ └── docs/16-Text2Image.md
│
└── SAA-17Text2Voice/ # 文生语音:CosyVoice TTS
└── docs/17-Text2Voice.md
│
└── SAA-18Graph/ # Agent 工作流:StateGraph 编排 AI 节点
└── docs/18-Graph.md
每个模块为独立的 Spring Boot 应用,可单独启动运行。子模块依赖均在父 POM 中统一管理。
学习顺序建议从 SAA-01 开始依次递进,每个模块在前一个基础上引入新的概念。详细内容请点击对应文档链接。
| 序号 | 模块 | 一句话介绍 | 文档 |
|---|---|---|---|
| 01 | HelloWorld | Spring AI Alibaba 最小示例,用最少的代码与大模型对话 | 01-HelloWorld.md |
| 02 | Ollama | 同一项目中同时接入云端 DashScope 和本地 Ollama 模型 | 02-Ollama.md |
| 03 | ChatModel vs ChatClient | 对比底层 ChatModel API 与高级 ChatClient Fluent API |
03-ChatModelChatClient.md |
| 04 | StreamingOutput | 流式输出的两种实现方式 + 多模型并存配置 | 04-StreamingOutput.md |
| 序号 | 模块 | 一句话介绍 | 文档 |
|---|---|---|---|
| 05 | Prompt | 从字符串升级到结构化 Prompt,让 AI 行为可控 | 05-Prompt.md |
| 06 | PromptTemplate | Prompt 模板化 + 外部文件加载,Prompt 与代码解耦 | 06-PromptTemplate.md |
| 07 | StructuredOutput | 让大模型直接返回强类型 Java 对象,对接业务系统 | 07-StructuredOutput.md |
| 序号 | 模块 | 一句话介绍 | 文档 |
|---|---|---|---|
| 08 | Advisor | 内置 + 自定义 Advisor,在请求前后插入拦截逻辑 | 08-Advisor.md |
| 09 | ChatMemory | 内存对话记忆,AI 不再每次「失忆」 | 09-ChatMemory.md |
| 10 | PersistentMemory | Redis 持久化记忆,服务重启后记忆依然存在 | 10-PersistentMemory.md |
| 序号 | 模块 | 一句话介绍 | 文档 |
|---|---|---|---|
| 11 | Embed2Vector | 文本向量化 + Redis 向量存储 + 语义相似度检索 | 11-Embed2Vector.md |
| 12 | RAG4AiOps | RAG 完整链路:加载知识库 → 向量化 → 检索 → 增强 Prompt → 回答 | 12-RAG4AiOps.md |
| 序号 | 模块 | 一句话介绍 | 文档 |
|---|---|---|---|
| 13 | ToolCalling | @Tool 注解让 AI 调用 Java 方法获取实时数据 |
13-ToolCalling.md |
| 14 | MCP Server | 构建 MCP Server,将工具以标准化协议暴露给远程 Client | 14-LocalMcpServer.md |
| 15 | MCP Client | MCP Client 连接 Server,AI 通过协议调用远程工具 | 15-LocalMcpClient.md |
| 序号 | 模块 | 一句话介绍 | 文档 |
|---|---|---|---|
| 16 | Text2Image | 通义万相(Wanx)文生图:文字描述 → AI 生成图片 | 16-Text2Image.md |
| 17 | Text2Voice | CosyVoice 文生语音:文字 → MP3 语音文件 | 17-Text2Voice.md |
| 序号 | 模块 | 一句话介绍 | 文档 |
|---|---|---|---|
| 18 | Graph | StateGraph 工作流编排:多个 AI 节点通过共享状态串行协作 | 18-Graph.md |
git clone <your-repo-url>
cd springAIAlibaba-guigu申请阿里云百炼 DashScope API Key,然后设置环境变量:
# Linux / macOS
export aliQwen-api=sk-xxxxxxxxxxxxxxxx
# Windows (CMD)
set aliQwen-api=sk-xxxxxxxxxxxxxxxx
# Windows (PowerShell)
$env:aliQwen-api="sk-xxxxxxxxxxxxxxxx"或在 IDE(IntelliJ IDEA)的 Run Configuration 中添加 Environment Variable。
# 安装 Ollama 并拉取模型
ollama pull deepseek-r1:14b不使用 SAA-02 可跳过此步骤。
推荐使用 Redis Stack(包含 RediSearch 模块):
docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest不使用向量/持久化记忆模块可跳过。各模块的 application.properties 中 Redis 连接地址默认为 192.168.101.42:6379,按需修改。
mvn clean compile# 以 SAA-01 为例
cd SAA-01HelloWorld
mvn spring-boot:run或直接运行各模块的主启动类:SAA-01HelloWorld/src/main/java/com/dec/study/Saa01HelloWorldApplication.java
# SAA-01:基础对话
curl "http://localhost:8001/ai/chat?msg=你好"
# SAA-03:ChatClient 流式调用
curl "http://localhost:8003/ai/chat_client?msg=hi"
# SAA-07:结构化输出
curl "http://localhost:8007/ai/v1/bean"
# SAA-09:多轮对话(带记忆)
curl "http://localhost:8009/ai/chat_memory?msg=我叫张三&convId=conv01"
curl "http://localhost:8009/ai/chat_memory?msg=我叫什么名字&convId=conv01"
# SAA-12:RAG 运维问答
curl "http://localhost:8012/rag4aiops?msg=B1111是什么意思"
# SAA-13:Tool Calling 获取时间
curl "http://localhost:8013/toolcall/chat2?msg=现在几点"
# SAA-16:文生图
curl "http://localhost:9001/t2i/image?prompt=一只刺猬"
# SAA-17:文生语音
curl "http://localhost:9002/t2v/voice"
# SAA-18:Agent 工作流
curl "http://localhost:8018/graph/simpleGraph?word=apple"各模块端口如下:
| 模块 | 端口 | 模块 | 端口 |
|---|---|---|---|
| SAA-01 | 8001 | SAA-10 | 8010 |
| SAA-02 | 8002 | SAA-11 | 8011 |
| SAA-03 | 8003 | SAA-12 | 8012 |
| SAA-04 | 8004 | SAA-13 | 8013 |
| SAA-05 | 8005 | SAA-14 | 8014 |
| SAA-06 | 8006 | SAA-15 | 8015 |
| SAA-07 | 8007 | SAA-16 | 9001 |
| SAA-08 | 8008 | SAA-17 | 9002 |
| SAA-09 | 8009 | SAA-18 | 8018 |
| 技术 | 用途 |
|---|---|
| Spring Boot 3.5.14 | 应用框架 |
| Spring AI 1.1.2 | AI 模型统一抽象(ChatModel / ImageModel / EmbeddingModel / TextToSpeechModel) |
| Spring AI Alibaba 1.1.2.0 | DashScope 百炼平台适配(通义千问 / 通义万相 / CosyVoice) |
| Spring AI MCP | Model Context Protocol 客户端与服务端 |
| Spring AI Alibaba Agent Framework | Agent 工作流编排(StateGraph / Node / CompiledGraph) |
| Redis Stack | 向量数据库(RediSearch)、对话记忆持久化 |
| Ollama | 本地大模型运行(可选) |
| Lombok | 代码简化 |
| Hutool | 工具库(SETNX 防重复) |
核心接口一览:
ChatModel— 文本对话ChatClient— Fluent 风格的 ChatModel 封装ImageModel— 文生图EmbeddingModel— 文本向量化TextToSpeechModel— 文生语音VectorStore— 向量数据库Advisor— 请求拦截器ChatMemory / ChatMemoryRepository— 对话记忆CompiledGraph— 编译后的可执行工作流图OverAllState— 工作流共享状态ToolCallback / ToolCallbackProvider— 工具注册
SAA-01 HelloWorld ──→ SAA-02 Ollama ──→ SAA-03 ChatModel/ChatClient ──→ SAA-04 Streaming
│
▼
SAA-05 Prompt ──→ SAA-06 PromptTemplate ──→ SAA-07 StructuredOutput
│
▼
SAA-08 Advisor ──→ SAA-09 ChatMemory ──→ SAA-10 PersistentMemory
│
▼
SAA-11 Embed2Vector ──→ SAA-12 RAG4AiOps
│
▼
SAA-13 ToolCalling ──→ SAA-14 MCP Server ──→ SAA-15 MCP Client
│
▼
SAA-16 Text2Image ──→ SAA-17 Text2Voice
│
▼
SAA-18 Graph (StateGraph Agent 工作流)
MIT License — 详见各模块源码。