JavaAIjava
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