【Spring AI】第一弹：在 A‏I 应用平台上创建‏智能体应用、工作流‏应用和使用 SDK 、HTTP、Spring AI 、LangChain4j 四种方式接入阿里云百炼灵积大模型

一、如何对比和选择大模型？

在选择大模‏型时，可以关注以下‏几个维度，这里提供‏给大家一个对比表格‏，无需记忆，要用到‌的时候参考一下即可。

其中，对大多数开发者来说，更关注的是 准确度 + 功能支持 + 性能 + 成本。

作为开发者，‏我们经常要通过开发框架来‏让程序对接大模型，因此可‏以通过一些开发框架的官方‏文档来快速了解和对比不同‌的大模型的功能支持，比如：

• LangChain4j 支持的大模型对比：Comparison Table of all supported Language Models | LangChain4j
• Spring AI 大模型对比文档：Chat Models Comparison :: Spring AI Reference

二、接入 AI 大模型

1、AI 应用平台接入

通过云服务商提供的 AI 应用平台来使用 AI 大模型。

以 阿里云百炼 为例，这是一站式的大模型开发及应用构建平台，它提供了从模型调用到应用构建的全流程支持。

不论是开发者还‏是业务人员，都可以通过简单的‏界面操作，在 5 分钟内开发‏出一款大模型应用，或在几小时‏内训练出一个专属模型，从而将‌更多精力专注于应用创新。

此外，还提‏供了知识库管理、应‏用评测、应用观测等‏功能，能够帮企业快‏速构建智能客服等应‌用。

大家在使用阿里云百炼产品时，可能会看到另外一个产品 —— 模型服务灵积（DashScope），很容易把这两个产品混淆。

百炼是一个可视化平台，同时服务于技术和非技术同学，使用更简单，更上层；

而灵积旨在通过灵活、易用的 模型 API 接口，让开发者能够快速调用丰富的大模型能力，面向技术开发同学，更底层。

后续我们通过编程来调用 AI 大模型，更多的是和灵积打交道。

利用阿里云‏百炼平台，我们可以‏轻松体验 AI 大‏模型和构建 AI‏ 应用。

1）快速体验 AI 大模型：

2）创建自己的 AI 应用，支持智能体、工作流和智能体编排应用。

智能体应用：

工作流应用，可以自主编排多个工作节点，完成复杂任务。

适用于需要结合大模型执行 高确定性 的业务逻辑的流程型应用，如可执行不同任务的智能助理工作流、自动化分析会议记录工作流等。

智能体编排应用支持用户通过画布的自定义智能体执行逻辑，编排主体为智能体，如智能体节点、智能体组及节点等，可快速实现复杂多智能体协同的逻辑设计和业务效果验证。

适用于需要处理大量数据、进行复杂计算或执行多任务处理的场景。

创建好了应用（智能体、工作流或智能体编排）后，可以参考 应用调用文档，通过 DashScope SDK 或 HTTP 的方式在自己的项目中集成应用。

2、AI 软件客户端接入

Cursor：以 AI 为核心的编程开发工具，可以快速生成项目代码、理解整个代码库并提供智能建议。

在本项目中，也会使用 Cursor 来生成前端项目代码。

3、程序接入

可以通过编‏程的方式在自己的项‏目中调用 AI 大‏模型，又可以分为 ‏2 种方式：

对于第 1 种方式，可以使用特定平台提供的 SDK 或 API，参考平台的文档来接入；也可以使用 AI 开发框架，比如 Spring AI、Spring AI Alibaba、LangChain4j 等自主选择大模型进行调用，可以灵活切换使用的大模型而几乎不用修改代码。

对于第 2 种方式，一般只能使用特定平台提供的 SDK 或 API，参考 平台的文档 来接入，每个大模型服务平台的代码都不一样。

如果是个人小项目，第 ‏2 种方式可能会更方便，因为把大多数应用构建‏的操作都放到了云端可视化平台而不是通过编程来‏实现；

但如果是企业级项目，考虑到扩展性，更推‏荐第 1 种方式，直接用 Spring AI‌ 等开发框架调用 AI 大模型。

三、后端项目初始化

(1) 环境准备

安装的 JDK 版本必须是 17 或 21，不能选择其他版本！因为项目使用最新版本的 Spring Boot 3 和 Spring AI 开发框架。

推荐使用 21 版本，因为支持虚拟线程这个王炸功能。

可参考视频安装 JDK：https://www.bilibili.com/video/BV14SUNYREv8

(2) 新建项目

在 IDEA 中新建项目，选择 Spring Initializr 模板，注意需要确保 Server URL 为 https://start.spring.io/。

配置如图，Java 版本选择 21：

选择 Spr‏ing Boot 3.‏4.4 版本，可以根据‏自己的需要添加一些依赖‏，比如 Spring ‌Web 和 Lombok：

当然，后续通过修改 Maven 配置添加依赖也是可以的。

点击创建，‏就得到了一个 Sp‏ring Boot‏ 项目，需要等待 ‏Maven 为我们‌安装依赖。

接下来，我们需要先让项目跑一跑：

做好上述修改后，重新跑项目：

💡 小提示，如果 Lombok 依赖报错的话，可以手动指定 Lombok 的版本，pom.xml 代码如下：

<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.36</version>
<optional>true</optional>
</dependency>

上面的两处 lombok 加上版本号后，刷新依赖；

重新启动项目，项目运行成功后，我们需要测试项目是否可以打包：

(3) 整合依赖

可以根据自‏己的需要，整合一些开‏发项目常用的依赖。此‏处我们整合 Huto‏ol 工具库和 Kn‌ife4j 接口文档即可。

1、Hutool 工具库

(1) Hutool 介绍

Hutool 是主流的 Java 工具类库，集合了丰富的工具类，涵盖字符串处理、日期操作、文件处理、加解密、反射、正则匹配等常见功能。

它的轻量化和无侵入性让开发者能够专注于业务逻辑而不必编写重复的工具代码。例如，DateUtil.formatDate(new Date()) 可以快速将当前日期格式化为字符串。

(2) 引入 Hutool 依赖

参考官方文档引入：[简介 | Hutool](https://doc.hutool.cn/pages/index/#🍊maven)

在 Maven 的 pom.xml 中添加依赖：

<dependency>
<groupId>cn.hutool</groupId>
<artifactId>hutool-all</artifactId>
<version>5.8.37</version>
</dependency>

2、Knife4j 接口文档

(1) Knife4j 介绍

Knife4j 是基于 S‏wagger 接口文档的增强工具，提供了更加友好的‏ API 文档界面和功能扩展，例如动态参数调试、分组文‏档等。

它适合用于 Spring Boot 项目‏中，能够通过简单的配置自动生成接口文档，让开发者和‌前端快速了解和调试接口，提高写作效率。

参考官方文档 | Knife4j引入，注意我们使用的是 Spring Boot 3.x，不要引入错版本了：

(2) 引入 Knife4j 依赖

在 Maven 的 pom.xml 中添加依赖：

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>

(3) 编写测试接口

新建 ‏controlle‏r 包用于存放 A‏PI 接口，编写一‏个健康检查接口用于‌测试接口文档是否正常引入：

@RestController
@RequestMapping("/health")
public class HealthController {

@GetMapping
public String healthCheck() {
return "ok";
}
}

(4) 追加接口文档配置

在 application.yml 中追加接口文档配置，扫描 controller 包。

这段配置可以从官方文档中复制过来，然后微调即可：

spring:
application:
name: lei–ai–agent
server:
port: 8123
servlet:
context-path: /api
# springdoc-openapi
springdoc:
swagger-ui:
path: /swagger–ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api–docs
group-configs:
– group: 'default'
paths-to-match: '/**'
packages-to-scan: com.lei.leiaiagent.controller
# knife4j
knife4j:
enable: true
setting:
language: zh_cn

(5) 测试接口文档

启动项目，访问 http://localhost:8123/api/doc.html 能够看到接口文档，可以测试调用接口：

3、编写通用基础代码

如果是要开发完整项目，除了引入依赖之外，还要编写一些通用基础代码，比如自定义异常、响应包装类、全局异常处理器、请求包装类、全局跨域配置等。

后端项目启动和初始化-CSDN博客

四、程序调用 AI 大模型

在实际开发中，有‏多种方式可以在应用程序中调用 ‏AI 大模型。下面详细介绍 4‏ 种主流的接入方式，并通过实例‏代码展示如何在 Java 项目‌中实现与 AI 大模型的交互。

下面所有的示例代码均放置在项目的 demo.invoke 包下，方便统一管理和查阅。

1、SDK 接入

SDK（软‏件开发工具包）是官‏方提供的最直接的集‏成方式，通常提供了‏完善的类型支持和错误‌处理机制。

(1) 安装 SDK

首先需要按照官方文档安装 SDK：安装 SDK 官方指南

在选择 SDK 版本时，建议在 Maven 仓库查看最新的版本号：Maven中央仓库版本信息

在 pom.xml 中引入依赖：

<!– https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java –>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>dashscope-sdk-java</artifactId>
<version>2.19.1</version>
</dependency>

(2) 申请 API Key

先在大模型服务平台百炼控制台申请一个 API Key，注意不要泄露：

(3) 创建接口类‏来存储密钥信息

项目中新建 demo.invoke 包，集中存放调用 AI 大模型的示例代码。

为了安全管‏理 API 密钥，‏我们创建一个接口类‏来存储密钥信息（在‏实际生产环境中，应‌使用配置文件或环境变量）：

public interface TestApiKey {

String API_KEY = "你的 API Key";
}

具体的代码示例可参考官方文档 通过 API 调用通义千问，如图：

找到关于 DashScope 的调用：

找到调用示例的代码，直接复制到我们的项目中：

使用 SD‏K 调用模型的完整‏示例代码：    ‏         ‏         ‌

// 建议dashscope SDK的版本 >= 2.12.0
import java.util.Arrays;
import java.lang.System;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

public class Main {
public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
Generation gen = new Generation();
Message systemMsg = Message.builder()
.role(Role.SYSTEM.getValue())
.content("You are a helpful assistant.")
.build();
Message userMsg = Message.builder()
.role(Role.USER.getValue())
.content("你是谁？")
.build();
GenerationParam param = GenerationParam.builder()
// 若没有配置环境变量，请用百炼API Key将下行替换为：.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// 此处以qwen-plus为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models
.model("qwen-plus")
.messages(Arrays.asList(systemMsg, userMsg))
.resultFormat(GenerationParam.ResultFormat.MESSAGE)
.build();
return gen.call(param);
}
public static void main(String[] args) {
try {
GenerationResult result = callWithMessage();
System.out.println(JsonUtils.toJson(result));
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
// 使用日志框架记录异常信息
System.err.println("An error occurred while calling the generation service: " + e.getMessage());
}
System.exit(0);
}
}

复制代码到 Invoke 中，修改类名：

修改输入给大模型的内容和 API key：

(4) 启动程序

运行项目，成功看到 AI 的回复：

2、HTTP 接入

对于 SD‏K 不支持的编程语言‏或需要更灵活控制的场‏景，可以直接使用 H‏TTP 请求调用 A‌I 大模型的 API。

💡 使用建‏议：一般来说，如果有官‏方 SDK 支持，优先‏使用 SDK；只有在不‏支持 SDK 的情况下‌，再考虑直接 HTTP调用。

(1) 查找模型请求体的 CURL 形式

HTTP 调用的详细说明可参考官方文档：通过 API 调用通义千问

(2) 转换 CURL 为代码

可以利用 ‏AI 将上述 CUR‏L 代码转换为 Ja‏va 的 Hutoo‏l 工具类网络请求代‌码，示例 Prompt：

将上述请求转换为 hutool 工具类的请求代码

AI 生成的代码如下，可以自己略作修改：

public class HttpAiInvoke {
public static void main(String[] args) {
// 替换为你的实际 API 密钥
String url = "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation";

// 设置请求头
Map<String, String> headers = new HashMap<>();
headers.put("Authorization", "Bearer " + TestApiKey.API_KEY);
headers.put("Content-Type", "application/json");

// 设置请求体
JSONObject requestBody = new JSONObject();
requestBody.put("model", "qwen-plus");

JSONObject input = new JSONObject();
JSONObject[] messages = new JSONObject[2];

JSONObject systemMessage = new JSONObject();
systemMessage.put("role", "system");
systemMessage.put("content", "You are a helpful assistant.");
messages[0] = systemMessage;

JSONObject userMessage = new JSONObject();
userMessage.put("role", "user");
userMessage.put("content", "你是谁？");
messages[1] = userMessage;

input.put("messages", messages);
requestBody.put("input", input);

JSONObject parameters = new JSONObject();
parameters.put("result_format", "message");
requestBody.put("parameters", parameters);

// 发送请求
HttpResponse response = HttpRequest.post(url)
.addHeaders(headers)
.body(requestBody.toString())
.execute();

// 处理响应
if (response.isOk()) {
System.out.println("请求成功，响应内容：");
System.out.println(response.body());
} else {
System.out.println("请求失败，状态码：" + response.getStatus());
System.out.println("响应内容：" + response.body());
}
}
}

(3) 运行程序

测试 HTTP 是否可以成功调用大模型：

3、Spring AI 接入

(1) Spring AI 介绍

Spring AI 是 Spring 生态系统的新成员，旨在简化 AI 功能与 Spring 应用的集成。

Spring AI 通过提供统一接口、支持集成多种 AI 服务提供商和模型类型、各种 AI 开发常用的特性（比如 RAG 知识库、Tools 工具调用和 MCP 模型上下文协议），简化了 AI 应用开发代码，使开发者能够专注于业务逻辑，提高了开发效率。

(2) Spring AI 核心特性

Spring AI 的核心特性如下，参考官方文档：

1. 跨 AI 供应商的可移植 API 支持：

• 适用于聊天、文本转图像和嵌入模型；
• 同时支持同步和流式 API 选项，并可访问特定于模型的功能。

2. 支持所有主流 AI 模型供应商：

• 如 Anthropic、OpenAI、微软、亚马逊、谷歌和 Ollama；
• 支持的模型类型包括：聊天补全、嵌入、文本转图像、音频转录、文本转语音

3. 结构化输出：

将 AI 模型输出映射到 POJO（普通 Java 对象）。

4. 支持所有主流向量数据库：

如 Apache Cassandra、Azure Cosmos DB、Azure Vector Search、Chroma、Elasticsearch、GemFire、MariaDB、Milvus、MongoDB Atlas、Neo4j、OpenSearch、Oracle、PostgreSQL/PGVector、PineCone、Qdrant、Redis、SAP Hana、Typesense 和 Weaviate。

5. 跨向量存储供应商的可移植 API：

包括新颖的类 SQL 元数据过滤 API。

6. 工具/函数调用：

允许模型请求执行客户端工具和函数，从而根据需要访问必要的实时信息并采取行动。

7. 可观测性：

提供与 AI 相关操作的监控信息。

8. 文档 ETL 框架：

适用于数据工程场景。

9. AI 模型评估工具：

帮助评估生成内容并防范幻觉响应。

10. Spring Boot 自动配置和启动器：

适用于 AI 模型和向量存储。

11. ChatClient API：

与 AI 聊天模型通信的流式 API，用法类似于 WebClient 和 RestClient API。

12. Advisors API：

封装常见的生成式 AI 模式，转换发送至语言模型（LLM）和从语言模型返回的数据，并提供跨各种模型和用例的可移植性。

13. 支持聊天对话记忆和检索增强生成（RAG）。

(3) Spring AI 调用大模型

Spring AI 默认没有支持所有的大模型（尤其是国产的），更多的是支持兼容 OpenAI API 的大模型的集成，参考 官方的模型对比。

因此，我们如果想要调用阿里系大模型（比如通义千问），推荐直接使用阿里自主封装的 Spring AI Alibaba 框架，它不仅能直接继承阿里系大模型，用起来更方便，而且与标准的 Spring AI 保持兼容。

可以参考下列官方文档，来跑通调用大模型的流程：

• 灵积模型接入指南
• 通义千问接入指南

1. 引入依赖

<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter</artifactId>
<version>1.0.0-M6.1</version>
</dependency>

官方提醒：由于 spring-ai 相关依赖包还没有发布到中央仓库，如出现 spring-ai-core 等相关依赖解析问题，请在项目的 pom.xml 依赖中加入如下仓库配置。

<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>

(2) 编写配置

在提交代码时，为了避免暴露 api-key 等敏感信息，我们创建一个 application-local.yml，将敏感的配置信息放在该配置文件；

并在 gitignore 中忽略对设置 git 对 application-local.yml的提交；

### CUSTOM ###
application-local.yml

以上就是 spring ai 对接灵积大模型的配置；

此外，我们还需要在配置文件中，再写一些关于特定大模型的参数，来指定调用的大模型：

spring:
application:
name: spring–ai–alibaba–qwq–chat–client–example
ai:
dashscope:
api-key: ${AI_DASHSCOPE_API_KEY}
chat:
options:
model: qwen–plus

(3) 编写示例代码

注意要注入 dashscopeChatModel;

代码实现了 C‏ommandLineRunner 接‏口，我们启动 Spring Boot‏ 项目时，会自动注入大模型 Chat‏Model 依赖，并且单次执行该类的‌ run 方法，达到测试的效果：

// 取消注释即可在 SpringBoot 项目启动时执行
@Component
public class SpringAiAiInvoke implements CommandLineRunner {

@Resource
private ChatModel dashscopeChatModel;
// 引入 springframework 的对话模型 bean
// 注意, @Resource 注入优先考虑 bean 的名称、再其次是类型
// 所以这个 bean 的名称一定要是 dashscopeChatModel, 表示引入的 bean 为灵积大模型

@Override
public void run(String... args) throws Exception {
AssistantMessage output = dashscopeChatModel.call(new Prompt("你好，我是小雷，正在学习如何通过 spring ai 调用大模型!"))
.getResult()
.getOutput();
System.out.println(output.getText());
}
}

应用启动 → Bean 扫描 → 依赖注入 → 应用启动完成 → CommandLineRunner 执行
↓ ↓ ↓ ↓ ↓
main()方法 → @Component → @Resource → 容器就绪 → run()方法执行

(4) 运行项目

💡 上述代码中我们是通‏过 ChatModel 对象调用大模型，适合简单‏的对话场景。除了这种方式外，Spring AI ‏还提供了 ChatClient 调用方式，提供更‏多高级功能（比如会话记忆），适合复杂场景，在后续‌ AI 应用开发章节中会详细介绍。

4、LangChain4j 接入

(1) LangChain4j 介绍

和 Spring AI ‏作用一样，LangChain4j 是一个专注于‏构建基于大语言模型（LLM）应用的 Java ‏框架，作为知名 AI 框架 LangChain‏ 的 Java 版本，它提供了丰富的工具和抽象‌层，简化了与 LLM 的交互和应用开发。

LangChain 官方是没有支持阿里系大模型的，只能用 社区版本的整合大模型包。可以在官方文档中查询支持的模型列表：LangChain4j模型集成

(2) LangChain4j 调用大模型

1. 引入依赖

要接入阿里云灵积模型，可以参考官方文档：DashScope模型集成，提供了依赖和示例代码。

<!– https://mvnrepository.com/artifact/dev.langchain4j/langchain4j-community-dashscope –>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-community-dashscope</artifactId>
<version>1.0.0-beta2</version>
</dependency>

2. 找到依赖的版本号

值得一提的是，LangChain4j 也提供了 Spring Boot Starter，方便在 Spring 项目中使用，最新版本号可以在 Maven中央仓库 查询。

我们这里由于只是编写 Demo，而且已经引入了 Spring AI 的 Starter，就不再引入 LangChain 的 Starter 了，担心会有冲突。

Starter 可以理解为集成：

• Spring AI 的 Starter 就是 Spring AI 集成 SpringBoot
• LangChain 的 Starter 就是 LangChain 集成 SpringBoot

集成需要引入对应的依赖，如：

引入了 Spring AI 的 Starter，就不再引入 LangChain 的 Starter 了，因为同时引入两个会发生冲突；

3. 编写对话代码

参考 官方文档 来编写示例对话代码，创建了一个 ChatModel 并调用，是不是和 Spring AI 很像？

public class LangChainAiInvoke {
public static void main(String[] args) {
ChatLanguageModel qwenModel = QwenChatModel.builder()
.apiKey(TestApiKey.API_KEY)
.modelName("qwen-max")
.build();
String answer = qwenModel.chat("你好，我是小雷，正在学习如何通过 langchain4j 调用千问大模型!");
System.out.println(answer);
}
}

4. 运行程序

最后直接运行 main 方法进行测试即可。

5、接入方式对比

以下是 4 种 AI 大模型接入方式的优缺点对比：

个人更推荐选择 Spring‏ AI，一方面是它属于 Spring 生态，更主流；

另‏一方面是它简单易用、资源更多，更利于学习，也能满足我们‏绝大多数 AI 项目的开发需求。因此本项目的后续教程，‏也会以 Spring AI 为主。

学会一个 AI 开发‌框架后，其他框架学起来都是如鱼得水。

💡 无论‏选择哪种接入方式，‏都建议先使用简单的‏测试案例验证接入是‏否成功，然后再进行‌更复杂的功能开发。

五、扩展思‏路

1）完善后端项目的初始化，补充通用基础代码

2）使用其他 AI 大模型平台，比如 火山引擎，并且通过 SDK 接入大模型

六、重点实现

1）在 A‏I 应用平台上创建‏智能体应用、工作流‏应用、智能体编排应‏用

2）使用至少一个 AI 软件客户端，推荐 Cursor

3）完成后端项目初始化

4）实践 4 种程序调用 AI 大模型的方式