Spring AI 与阿里云快速上手指南

引言/概述

随着大模型技术的飞速发展，越来越多的企业希望将 AI 能力无缝集成到现有的 Java 应用中。Spring AI 是 Spring 官方推出的 AI 集成框架，旨在简化开发者在 Spring 生态中调用大语言模型（LLM）的过程，提供统一、简洁、可扩展的编程模型。与此同时，阿里云作为国内领先的云服务商，提供了包括通义千问（Qwen）在内的强大大模型能力，并通过百炼平台开放 API 接口。

本文将指导你如何基于 Spring AI 快速接入阿里云的大模型服务（以通义千问为例），从环境准备、依赖配置到实际调用，助你快速构建具备 AI 能力的 Spring Boot 应用。无论你是初学者还是已有 Spring 开发经验的工程师，都能通过本指南快速上手。

核心内容

一、前置准备

在开始编码前，你需要完成以下准备工作：

1. 注册阿里云账号：访问 阿里云官网 并完成实名认证。
2. 开通通义千问服务：进入 阿里云百炼控制台，创建应用并获取 API Key。
3. 记录关键信息：
   • Access Key ID 和 Access Key Secret（用于鉴权）
   • 百炼平台分配的 App ID
   • API 端点（如 https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation）

注意：建议使用 RAM 用户的 AccessKey，并赋予最小必要权限，避免主账号泄露风险。

二、创建 Spring Boot 项目

使用 Spring Initializr 创建一个新项目，选择以下依赖：

• Spring Web
• Spring AI Alibaba（需添加 Spring AI 的 BOM）

由于 Spring AI 尚未完全发布到 Maven Central，你需要手动添加仓库和依赖。

添加 Spring AI BOM

在 pom.xml 中添加 Spring AI 的 BOM 管理依赖版本：

<properties>
    <spring-ai.version>0.8.1</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

添加 Alibaba 模型支持依赖

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-alibaba-dashscope-spring-boot-starter</artifactId>
    </dependency>
    <!-- 其他依赖如 spring-boot-starter-web -->
</dependencies>

注意：截至 2024 年中，spring-ai-alibaba-dashscope-spring-boot-starter 是官方提供的对接阿里云 DashScope（通义千问 API 平台）的 Starter。

三、配置阿里云凭证

在 application.yml 中配置阿里云的认证信息：

spring:
  ai:
    alibaba:
      dashscope:
        api-key: your_dashscope_api_key  # 在百炼控制台获取
        model: qwen-max                  # 可选：qwen-turbo, qwen-plus, qwen-max 等

提示：为安全起见，建议将 api-key 存入环境变量或使用 Spring Cloud Config / Vault 管理。

四、编写 AI 调用代码

Spring AI 提供了两种主要的调用方式：AiClient（简单问答）和 PromptTemplate（带模板的结构化输入）。

4.1 使用 AiClient 实现简单对话

创建一个 REST 控制器，注入 AiClient：

@RestController
@RequestMapping("/ai")
public class AiController {

    private final AiClient aiClient;

    public AiController(AiClient aiClient) {
        this.aiClient = aiClient;
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return aiClient.generate(message);
    }
}

启动应用后，访问 http://localhost:8080/ai/chat?message=你好，介绍一下你自己，即可看到通义千问的回复。

4.2 使用 PromptTemplate 构建结构化提示

对于更复杂的场景（如提取信息、格式化输出），推荐使用 PromptTemplate：

@Service
public class WeatherService {

    private final PromptTemplate promptTemplate;
    private final AiClient aiClient;

    public WeatherService(AiClient aiClient) {
        this.aiClient = aiClient;
        this.promptTemplate = new PromptTemplate(
            "请根据以下天气数据生成一段简短的天气预报：\n" +
            "城市：{city}\n" +
            "温度：{temperature}℃\n" +
            "天气：{condition}\n" +
            "请用中文友好地描述。"
        );
    }

    public String generateForecast(String city, int temperature, String condition) {
        Prompt prompt = promptTemplate.create(Map.of(
            "city", city,
            "temperature", temperature,
            "condition", condition
        ));
        return aiClient.generate(prompt).getResult().getOutput().getContent();
    }
}

在控制器中调用：

@GetMapping("/forecast")
public String forecast() {
    return weatherService.generateForecast("杭州", 25, "多云");
}

五、启用流式响应（可选）

对于长文本生成，启用流式输出可提升用户体验。Spring AI 支持 StreamingAiClient：

@RestController
public class StreamingController {

    private final StreamingAiClient streamingAiClient;

    public StreamingController(StreamingAiClient streamingAiClient) {
        this.streamingAiClient = streamingAiClient;
    }

    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestParam String message) {
        return streamingAiClient.stream(message)
                .map(chunk -> chunk.getResult().getOutput().getContent());
    }
}

前端可通过 EventSource 接收实时流式数据。

六、错误处理与日志

在生产环境中，务必添加异常处理：

@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleAiException(Exception ex) {
    log.error("AI 调用失败", ex);
    return ResponseEntity.status(500).body("AI 服务暂时不可用");
}

同时，可在 application.yml 中开启调试日志：

logging:
  level:
    org.springframework.ai: DEBUG

这有助于排查请求/响应细节。

总结

通过本文，我们完成了从零开始使用 Spring AI 对接阿里云通义千问的全过程。核心步骤包括：

1. 准备阿里云 API 凭证；
2. 引入 Spring AI Alibaba Starter；
3. 配置模型参数；
4. 使用 AiClient 或 PromptTemplate 实现智能问答；
5. 可选地启用流式响应与错误处理。

Spring AI 的设计哲学是“约定优于配置”，极大降低了 AI 集成的复杂度。而阿里云提供的稳定、高性能的大模型服务，则为国内开发者提供了合规、低延迟的选择。

未来，随着 Spring AI 功能的不断完善（如支持 Function Calling、RAG、Agent 等高级特性），结合阿里云百炼平台的丰富模型生态，Java 开发者将能更高效地构建下一代智能应用。

小贴士：建议定期关注 Spring AI 官方文档 和 阿里云百炼文档，获取最新功能与最佳实践。

现在，就动手试试吧！用几行代码，让你的 Spring Boot 应用拥有“思考”能力。