Spring Cloud Alibaba 接入通义千问大模型实战指南
基于 Spring Cloud Alibaba AI 接入阿里云通义千问大模型的完整流程。内容包括环境准备、Maven 依赖配置、application.yml 设置、Controller 与服务层代码实现,以及基本的对话、流式输出和文生图功能测试。文章还补充了安全性建议、异常处理、提示词优化及常见问题排查方案,帮助开发者快速构建 Java AI 应用。

基于 Spring Cloud Alibaba AI 接入阿里云通义千问大模型的完整流程。内容包括环境准备、Maven 依赖配置、application.yml 设置、Controller 与服务层代码实现,以及基本的对话、流式输出和文生图功能测试。文章还补充了安全性建议、异常处理、提示词优化及常见问题排查方案,帮助开发者快速构建 Java AI 应用。

近几年,AI 大模型的发展迅速,成为全球科技竞争的新高地,具有极大的发展潜力和广泛的应用前景。中国在 AI 大模型领域的发展尤为显著,不仅在算力规模上与美国差距不大,而且在中文语料和文化理解方面具有天然优势。中国企业在大模型开发方面起步较晚,但发展迅速,涌现出如百度的 ERNIE、阿里巴巴的 M6 等代表性的大模型产品。
AI 大模型的应用场景广泛,包括但不限于自然语言处理、图像识别、语音识别、推荐系统、自动驾驶、游戏、科学研究等。随着技术的进步,AI 大模型正在不断推动人工智能技术的边界,为各行各业带来革命性的变化。
Spring AI 是 Spring 官方社区项目,旨在简化 Java AI 应用程序开发,让 Java 开发者像使用 Spring 开发普通应用一样开发 AI 应用。
Spring AI 项目从最初专注于处理语言输入和生成语言输出的模型开始,逐渐发展成为一个提供多种 AI 功能集成的框架。它提供了跨 AI 提供商的可移植 API 支持,包括聊天、文本到图像、嵌入模型等,并支持同步和流式 API 选项。
主要功能特点:
java.util.Function 实现,以供 OpenAI 模型在其提示响应中使用。Spring Cloud Alibaba AI 以 Spring AI 为基础,并在此基础上提供阿里云通义系列大模型全面适配,让用户能快速开发基于通义大模型的 Java AI 应用。
Spring Cloud Alibaba AI 目前基于 Spring AI 0.8.1 版本 API 完成通义系列大模型的接入。通义接入是基于阿里云灵积模型服务,灵积模型服务建立在'模型即服务'(Model-as-a-Service,MaaS)的理念基础之上,围绕 AI 各领域模型,通过标准化的 API 提供包括模型推理、模型微调训练在内的多种模型服务。
在当前最新版本中,Spring Cloud Alibaba AI 主要完成了几种常见生成式模型的适配,包括对话、文生图、文生语音等,开发者可以使用 Spring Cloud Alibaba AI 开发基于通义的聊天、图片或语音生成 AI 应用,框架还提供 OutParser、Prompt Template、Stuff 等实用能力。
为了确保项目的顺利运行,需要准备好以下开发环境和资源:
在 IntelliJ IDEA 中选择 File -> New -> Project -> Maven,设置 GroupId 和 ArtifactId,完成初始化。
在 pom.xml 文件中引入 Spring Cloud Alibaba AI 的依赖管理。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-alibaba-dependencies</artifactId>
<version>2023.0.1.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-ai</artifactId>
</dependency>
</dependencies>
备注:
如果添加依赖时出现报错 Cannot resolve org.springframework.ai:spring-ai-core:0.8.1,说明本地仓库缺少 Spring 的里程碑或快照仓库。需要在 pom.xml 中添加如下仓库配置段落,这会指引 Maven 去查找 Spring 的里程碑和快照仓库。
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>https://repo.spring.io/snapshot</url>
<releases>
<enabled>false</enabled>
</releases>
</repository>
</repositories>
添加后,点击 IDE 中的 Reload 按钮重新导入依赖。
新建 application.yml 文件,配置服务端口、应用名称以及通义 API Key。
server:
port: 8080
spring:
application:
name: alibaba-spring-ai-demo
cloud:
ai:
tongyi:
api-key: ${TONGYI_API_KEY}
安全建议:
生产环境中,不建议将 API Key 硬编码在配置文件中。建议使用环境变量 ${TONGYI_API_KEY} 或者 Spring Cloud Config 进行敏感信息管理。
创建一个标准的 Spring Boot 启动类,无需额外注解,框架会自动扫描配置。
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
建议按照 Controller、Service、Impl 的分层架构组织代码。
定义 RESTful 接口,暴露对话、流式对话和图片生成能力。
@RestController
@RequestMapping("/api")
public class TongYiController {
@Resource
private TongYiService tongYiService;
/**
* 简单问答接口
*/
@GetMapping("/simple")
public String completion(@RequestParam(value = "message", defaultValue = "AI 时代下 Java 开发者该何去何从?") String message) {
return tongYiService.completion(message);
}
/**
* 流式对话接口
*/
@GetMapping("/stream_completion")
public Map<String, String> streamCompletion(@RequestParam(value = "message", defaultValue = "AI 时代下 Java 开发者该何去何从?") String message) {
return tongYiService.streamCompletion(message);
}
/**
* 文生图接口
*/
@GetMapping("/image")
public ImageResponse getImage(@RequestParam(value = "imgPrompt", defaultValue = "画一只狗") String imgPrompt) {
return tongYiService.getImage(imgPrompt);
}
}
定义业务接口。
public interface TongYiService {
/**
* 基本问答
*
* @param message 用户输入的消息
* @return 模型返回的文本内容
*/
String completion(String message);
/**
* Stream 流式调用
*
* @param message 用户输入的消息
* @return 包含消息和完整内容的 Map
*/
Map<String, String> streamCompletion(String message);
/**
* 文生图
*
* @param imgPrompt 图片描述提示词
* @return 图片响应对象
*/
ImageResponse getImage(String imgPrompt);
}
实现具体的业务逻辑,注入 ChatClient 和 ImageClient。
@Service
@Slf4j
public class TongYiServiceImpl implements TongYiService {
@Resource
private ChatClient chatClient;
@Resource
private ImageClient imageClient;
@Resource
private StreamingChatClient streamingChatClient;
@Override
public String completion(String message) {
// 构建 Prompt,包含用户消息
Prompt prompt = new Prompt(new UserMessage(message));
// 调用模型并获取结果
return chatClient.call(prompt).getResult().getOutput().getContent();
}
@Override
public Map<String, String> streamCompletion(String message) {
StringBuilder fullContent = new StringBuilder();
// 使用流式客户端接收响应
streamingChatClient.stream(new Prompt(message))
.flatMap(chatResponse -> Flux.fromIterable(chatResponse.getResults()))
.map(content -> content.getOutput().getContent())
.doOnNext(fullContent::append)
.last()
.map(lastContent -> Map.of(message, fullContent.toString()))
.block();
log.info("fullContent:{}", fullContent);
return Map.of(message, fullContent.toString());
}
@Override
public ImageResponse getImage(String imgPrompt) {
// 构建图片生成 Prompt
ImagePrompt imagePrompt = new ImagePrompt(imgPrompt);
// 调用图片生成服务
return imageClient.call(imagePrompt);
}
}
运行 Spring Boot 启动类,确保控制台无报错,服务监听在 8080 端口。
使用 Postman 或 curl 访问 /api/simple 接口,传入 message 参数,观察返回的文本内容是否符合预期。
访问 /api/image 接口,传入 imgPrompt 参数(例如'一只在草地上奔跑的猫'),检查返回的图片响应数据。
在实际生产中,网络请求可能会超时或鉴权失败。建议在 Service 层增加 Try-Catch 块,捕获 AiException 或 IOException,并返回友好的错误信息给前端。
try {
return chatClient.call(prompt).getResult().getOutput().getContent();
} catch (Exception e) {
log.error("AI 调用失败", e);
throw new RuntimeException("AI 服务暂时不可用,请稍后再试");
}
为了获得更好的回答质量,可以在 UserMessage 之前添加 SystemMessage 来设定角色。例如:
Prompt prompt = new Prompt(
new SystemMessage("你是一个专业的 Java 技术顾问"),
new UserMessage(message)
);
通义千问 API 通常按 Token 计费。建议在网关层或 Service 层增加限流机制,防止恶意调用导致费用激增。同时,对于长文本输入,考虑进行截断或摘要处理。
chatClient 等 Bean 是否正确注入。本文详细介绍了如何使用 Spring Cloud Alibaba AI 快速接入阿里云通义千问大模型。通过简单的 Maven 依赖引入和 YAML 配置,即可实现文本对话、流式输出及文生图功能。结合 Spring AI 提供的标准化接口,开发者可以专注于业务逻辑的实现,而无需关心底层模型的具体细节。未来,随着 Spring AI 生态的完善,Java 开发者在 AI 应用领域的开发效率将得到进一步提升。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online