Spring AI Alibaba 快速入门指南（适合初学者）

如果你是刚接触 AI 开发或 Spring 框架的初学者，不用担心，本指南会用简单易懂的语言带你一步步了解并使用 Spring AI Alibaba。

一、什么是 Spring AI Alibaba（小白也能懂）

简单来说，Spring AI Alibaba 就是一个 “工具包”，它把阿里巴巴的 AI 技术（比如通义千问大模型、向量数据库等）和大家常用的 Spring 框架 “打包” 到了一起。

**打个比方：**就像你想做蛋糕（开发 AI 应用），Spring AI Alibaba 已经帮你准备好了烤箱（AI 技术）、面粉（Spring 框架工具），你不用自己研究烤箱怎么造，直接跟着步骤做就能做出蛋糕。

它的核心作用就是：让你不用深入学习复杂的 AI 底层技术，就能快速开发出带 AI 功能的应用（比如智能聊天机器人、自动写文案的工具等）。

二、核心特性（用例子告诉你它能做什么）

1. 大模型集成：直接调用 “通义千问” 这样的 AI 大模型。

   ✅ 例子：你想做一个 “自动写周报” 的工具，不用自己训练 AI，通过它就能让通义千问帮你生成文本。

2. 向量数据库适配：方便存储和查找 “语义数据”。

   ✅ 例子：做一个 “智能客服” 时，能快速找到和用户问题意思相近的历史答案。

3. 和 Spring 框架无缝衔接：如果你学过 Spring Boot，会觉得特别熟悉。

   ✅ 好处：不用重新学新框架，用你熟悉的@Autowired、@Service这些注解就能开发。

4. 场景化组件：提供现成的 “工具” 应对常见需求。

   ✅ 比如：内置了 “智能问答” 组件，你不用自己写逻辑，直接用它就能实现用户问问题、AI 回答的功能。

5. Graph 多智能体架构：用画图的方式设计 AI 流程。

   ✅ 例子：想做一个 “自动审批流程”，可以像画流程图一样拖拖拽拽，就能让 AI 按步骤处理。

6. 多种开发方式：

• 零代码：纯鼠标操作，适合完全不会编程的人；

• 低代码：写少量代码，适合初学者；

• 高代码：自己写完整逻辑，适合复杂需求。

三、环境搭建（ step by step 手把手教学）

准备工作：你需要先安装这些工具

• JDK 17+：Java 的运行环境（建议用 17 版本，官网能下载）。

• Maven 3.6+：管理项目依赖的工具（安装后记得配置环境变量）。

• IDE：推荐用 IntelliJ IDEA（社区版免费，足够初学者使用）。

• 通义千问 API 密钥：相当于调用 AI 的 “钥匙”，需要去阿里云官网申请（后面会说简单步骤）。

第一步：创建一个 Spring Boot 项目

1. 打开 IDEA，点击 New Project → 选择 Spring Initializr → 点击 Next。

2. 填写项目信息（不用死记，按下图填即可）：

• Group：随便写，比如 com.example

• Artifact：项目名，比如 spring-ai-demo

• Java Version：选 17

3. 点击 Next → 暂时不选依赖（后面手动加）→ 点击 Finish。

第二步：添加依赖（复制粘贴就行）

打开项目里的 pom.xml 文件（在项目根目录），在 <dependencies> 标签里添加下面的代码：

<dependency><groupId>com.alibaba.spring.ai</groupId><artifactId>spring-ai-alibaba-boot-starter</artifactId><version>1.0.0</version> <!-- 最新稳定版 -->
</dependency>
<!-- 下面是web依赖，让我们能通过浏览器访问项目 -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency>

📌 初学者注意：添加后记得点击 IDEA 右上角的 Load Maven Changes（像刷新的图标），让它自动下载需要的文件。

第三步：配置 API 密钥（获取 “调用 AI 的钥匙”）

1. 获取 API 密钥：

• 打开阿里云官网（https://www.aliyun.com/），注册并登录；

• 搜索 “通义千问 API”，按提示申请开通（个人开发者有免费额度）；

• 申请后在 “控制台” 找到 API密钥（一串字母数字组合），复制保存好。

2. 配置到项目中：

• 在 src/main/resources 目录下找到 application.properties 文件；

• 打开后粘贴下面的内容（把 你的密钥 换成你刚复制的内容）：

# 配置通义千问的密钥
spring.ai.alibaba.api-key=你的通义千问API密钥
# 选择要使用的模型（qwen-turbo是免费额度内可用的模型）
spring.ai.alibaba.model=qwen-turbo
# 项目启动的端口（默认8080，不用改）
server.port=8080

四、快速入门示例：让 AI 帮你写文本（完整代码 + 解释）

我们来做一个简单的功能：通过浏览器输入一句话，让通义千问帮我们扩展成一段文字。

第一步：创建服务类（让 AI 干活的 “工人”）

在 src/main/java/com/example/springaidemo 目录下，新建一个 AiService.java 文件：

// 告诉Spring这是一个“服务类”（用来写业务逻辑）
@Service
public class AiService {// 自动引入调用AI的“工具”（不用自己创建，Spring会帮你准备好）@Autowiredprivate AlibabaAiClient aiClient;// 定义一个方法：接收用户的提示词，返回AI生成的文本public String generateText(String prompt) {// 1. 准备“任务单”：告诉AI要做什么AlibabaChatRequest request = AlibabaChatRequest.builder().prompt(prompt) // 用户输入的提示词（比如“写一段关于春天的句子”）.temperature(0.7) // 控制AI生成的随机性（0-1之间，0表示更固定，1表示更多样）.build();// 2. 让AI执行任务，并获取结果AlibabaChatResponse response = aiClient.generate(request);// 3. 返回AI生成的内容return response.getContent();}
}

💡 初学者小贴士：

• @Service：标记这个类是 “干活的”，Spring 会自动管理它。

• @Autowired：相当于 “自动送货上门”，不用自己创建 AlibabaAiClient 对象。

第二步：创建控制器（接收用户请求的 “前台”）

再新建一个 AiController.java 文件：

// 告诉Spring这是一个“控制器”（用来接收浏览器的请求）
@RestController
public class AiController {// 引入上面写的服务类（让“前台”调用“工人”干活）@Autowiredprivate AiService aiService;// 定义一个接口：通过浏览器访问 /generate 时触发@GetMapping("/generate")public String generate(@RequestParam String prompt) {// 调用服务类的方法，把用户输入的prompt传给AI，返回结果return aiService.generateText(prompt);}
}

💡 初学者小贴士：

• @RestController：标记这个类是 “前台接待员”，负责和用户交互。

• @GetMapping("/generate")：用户访问 http://localhost:8080/generate 时，会执行这个方法。

• @RequestParam String prompt：获取浏览器地址里的 prompt 参数（比如 prompt=写一段关于春天的句子）。

第三步：启动项目并测试

1. 找到 SpringAidemoApplication.java（项目创建时自动生成的），点击旁边的运行按钮（▶️）。

2. 等待控制台出现 Started SpringAidemoApplication in xx seconds（表示启动成功）。

3. 打开浏览器，输入地址：

   http://localhost:8080/generate?prompt=``写一段关于春天的句子

   （注意：prompt= 后面可以换成任何你想让 AI 生成的内容）

✅ 成功的话，浏览器会显示 AI 生成的文本（比如 “春天像个害羞的小姑娘，悄悄带来了嫩绿的小草和芬芳的花朵…”）。

五、常见问题（初学者必看）

1. 启动时报错 “找不到 API 密钥”：

   → 检查 application.properties 里的 spring.ai``.alibaba.api-key 是否填对，有没有多空格。

2. 浏览器访问后显示 “500 错误”：

   → 看控制台日志，可能是 API 密钥过期了，或者网络不好（AI 调用需要联网）。

3. AI 生成的内容是空的：

   → 试试换一个简单的 prompt（比如 “你好”），可能是你的提示词太复杂，AI 没理解。

4. Maven 依赖下载失败：

   → 点击 IDEA 里的 File → Invalidate Caches...，清除缓存后重新下载。

六、进阶小练习（巩固所学）

1. 改一改 temperature 的值（比如 0.1 或 0.9），看看 AI 生成的内容有什么变化。

2. 新增一个方法，让 AI 生成 “3 个关于学习的成语”（提示词可以写成 “生成 3 个关于学习的成语，用逗号分隔”）。

3. 尝试用浏览器访问 http://localhost:8080/generate?prompt=``帮我写一个请假条，看看 AI 的表现。

通过上面的步骤，你已经成功用 Spring AI Alibaba 调用了 AI 大模型！是不是比想象中简单？后续可以慢慢探索 “多轮对话”“向量检索” 等功能，一步步成为 AI 开发高手～

如果有哪里不懂，可以再回头看步骤，或者留言问我哦！