Skip to content

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

spring-ai-alibaba-examples

基于 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

Prompt 工程篇:让 AI 行为可控

序号 模块 一句话介绍 文档
05 Prompt 从字符串升级到结构化 Prompt,让 AI 行为可控 05-Prompt.md
06 PromptTemplate Prompt 模板化 + 外部文件加载,Prompt 与代码解耦 06-PromptTemplate.md
07 StructuredOutput 让大模型直接返回强类型 Java 对象,对接业务系统 07-StructuredOutput.md

架构篇:Advisor 拦截器链

序号 模块 一句话介绍 文档
08 Advisor 内置 + 自定义 Advisor,在请求前后插入拦截逻辑 08-Advisor.md
09 ChatMemory 内存对话记忆,AI 不再每次「失忆」 09-ChatMemory.md
10 PersistentMemory Redis 持久化记忆,服务重启后记忆依然存在 10-PersistentMemory.md

知识库与 RAG 篇:让 AI 能「查资料」

序号 模块 一句话介绍 文档
11 Embed2Vector 文本向量化 + Redis 向量存储 + 语义相似度检索 11-Embed2Vector.md
12 RAG4AiOps RAG 完整链路:加载知识库 → 向量化 → 检索 → 增强 Prompt → 回答 12-RAG4AiOps.md

工具调用篇:让 AI 能「做事」

序号 模块 一句话介绍 文档
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

多模态篇:文字之外的 AI 能力

序号 模块 一句话介绍 文档
16 Text2Image 通义万相(Wanx)文生图:文字描述 → AI 生成图片 16-Text2Image.md
17 Text2Voice CosyVoice 文生语音:文字 → MP3 语音文件 17-Text2Voice.md

Agent 编排篇:多步骤 AI 工作流

序号 模块 一句话介绍 文档
18 Graph StateGraph 工作流编排:多个 AI 节点通过共享状态串行协作 18-Graph.md

快速开始

1. 克隆项目

git clone <your-repo-url>
cd springAIAlibaba-guigu

2. 配置 API Key

申请阿里云百炼 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。

3. 配置 Ollama(SAA-02 需要)

# 安装 Ollama 并拉取模型
ollama pull deepseek-r1:14b

不使用 SAA-02 可跳过此步骤。

4. 配置 Redis(SAA-10/11/12 需要)

推荐使用 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,按需修改。

5. 编译项目

mvn clean compile

6. 运行单个模块

# 以 SAA-01 为例
cd SAA-01HelloWorld
mvn spring-boot:run

或直接运行各模块的主启动类:SAA-01HelloWorld/src/main/java/com/dec/study/Saa01HelloWorldApplication.java

7. 调用接口

# 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 工作流)

License

MIT License — 详见各模块源码。

About

一个完整的 Spring AI Alibaba 示例项目,涵盖 Chat、Prompt、RAG、MCP、Tool Calling、多模态 AI 等。持续更新中

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages