Spring Cloud Alibaba 接入通义千问大模型实战指南

备注： 如果添加依赖时出现报错 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 按钮重新导入依赖。

3.1.3 application.yml 配置

新建 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 进行敏感信息管理。

3.1.4 新建 SpringBoot 启动类

创建一个标准的 Spring Boot 启动类，无需额外注解，框架会自动扫描配置。

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

3.2 实现代码

3.2.1 新建包结构

建议按照 Controller、Service、Impl 的分层架构组织代码。

3.2.2 TongYiController

定义 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);
    }

}

3.2.3 TongYiService

定义业务接口。

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);
}

3.2.4 TongYiServiceImpl

实现具体的业务逻辑，注入 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);
    }

}

3.3 测试与验证

3.3.1 启动服务

运行 Spring Boot 启动类，确保控制台无报错，服务监听在 8080 端口。

3.3.2 基本对话测试

使用 Postman 或 curl 访问 /api/simple 接口，传入 message 参数，观察返回的文本内容是否符合预期。

3.3.3 文生图测试

访问 /api/image 接口，传入 imgPrompt 参数（例如'一只在草地上奔跑的猫'），检查返回的图片响应数据。

3.4 进阶实践与安全建议

3.4.1 异常处理

在实际生产中，网络请求可能会超时或鉴权失败。建议在 Service 层增加 Try-Catch 块，捕获 AiException 或 IOException，并返回友好的错误信息给前端。

try {
    return chatClient.call(prompt).getResult().getOutput().getContent();
} catch (Exception e) {
    log.error("AI 调用失败", e);
    throw new RuntimeException("AI 服务暂时不可用，请稍后再试");
}

3.4.2 提示词工程优化

为了获得更好的回答质量，可以在 UserMessage 之前添加 SystemMessage 来设定角色。例如：

Prompt prompt = new Prompt(
    new SystemMessage("你是一个专业的 Java 技术顾问"),
    new UserMessage(message)
);

3.4.3 成本与限流

通义千问 API 通常按 Token 计费。建议在网关层或 Service 层增加限流机制，防止恶意调用导致费用激增。同时，对于长文本输入，考虑进行截断或摘要处理。

3.5 常见问题排查

1. 依赖解析失败：确保已添加 Spring Milestones 和 Snapshots 仓库。
2. API Key 无效：检查 Key 是否过期，或是否在正确的区域开通。
3. 连接超时：检查服务器网络是否能访问阿里云 API 地址。
4. 空指针异常：确认 chatClient 等 Bean 是否正确注入。

四、总结

本文详细介绍了如何使用 Spring Cloud Alibaba AI 快速接入阿里云通义千问大模型。通过简单的 Maven 依赖引入和 YAML 配置，即可实现文本对话、流式输出及文生图功能。结合 Spring AI 提供的标准化接口，开发者可以专注于业务逻辑的实现，而无需关心底层模型的具体细节。未来，随着 Spring AI 生态的完善，Java 开发者在 AI 应用领域的开发效率将得到进一步提升。