【从0学习Spring AI Alibaba】2、Spring AI Alibaba版本选型及环境搭建

在进行Spring AI Alibaba的基础环境搭建与快速入门之前，我们先要捋一捋思路，进行Spring AI Alibaba合适版本的选择（为了便于描述，后面统一将Spring AI Alibaba简述为SAA），然后再进行环境搭建。

一、写在前面：为什么版本选型是"第一道防线"？

如果你正在读这篇文章，大概率是带着"用Spring AI Alibaba快速构建AI应用"的目标而来。你的脑海里或许正规划着智能客服、文档分析或创意文案生成等激动人心的功能蓝图------但请稍等片刻。

让我们先面对一个不那么"性感"，却绝对关键的现实：在Spring AI的世界里，错误的版本选择几乎是100%会导致项目"夭折"的开始。这并非危言耸听，无数开发者的第一行代码尚未编写，就已在启动日志中遭遇如下熟悉的"面孔"：

Caused by: java.lang.ClassNotFoundException: org.springframework.ai.model.Model
Caused by: java.lang.NoSuchMethodError: org.springframework.ai.chat.client.ChatClient$ChatClientRequestSpecBuilder.systemParam(Ljava/lang/String;Ljava/lang/Object;)

这些冰冷的错误信息，正是版本不兼容为你敲响的警钟。在Spring AI这个高速演进、生态繁茂的"热带雨林"中，版本选型就是你踏入这片未知领域必须携带的"地图"和"指南针"。

那么，Spring AI Alibaba究竟扮演什么角色？简单来说，它是阿里云官方基于Spring AI标准接口，为通义千问、灵积模型等阿里云AI服务提供的企业级实现。你可以把它理解为适配阿里云AI能力的一个"驱动程序"。这就决定了你的技术栈将是一个四层嵌套结构：

JDK版本 → Spring Boot版本 → Spring AI核心版本 → Spring AI Alibaba版本

这四个组件环环相扣，任何一个环节的版本错位，都可能导致整个大厦的倾覆。因此，版本选型并非简单的"用最新版"，而是精准锁定一组经过充分验证的、彼此兼容的技术组合。这不仅是为了能跑起来，更是为了在未来的开发、调试、依赖升级和维护中，能拥有一份确定性和从容。

本指南的目标读者，正是那些希望稳扎稳打、从零搭建AI应用的Java/Spring开发者，或是正为如何从旧有技术栈平滑迁移而头疼的团队。我们的目标，就是为你提供这张清晰、可靠的"地图"，让你跨越版本冲突的鸿沟，将宝贵的精力聚焦于业务逻辑与AI能力的创新结合上，而非浪费在与构建工具的"搏斗"中。

准备好你的开发环境，让我们从这"第一道防线"开始，开启一段顺畅的Spring AI Alibaba之旅。

二、核心版本矩阵：锁定你的"黄金组合"

在 Spring AI Alibaba（SAA）的生态里，"兼容"比"最新"更重要。这一节直接给出经过验证的"黄金组合"，帮你跳过踩坑阶段。

2.1.2026年主流推荐组合（新项目首选）

对于新建项目，直接复制这套配置，能最大程度保证稳定性并享受新特性（如 Agent 能力）。

避坑提示：虽然 JDK 21 也是 LTS 且性能更优，但在 2026 年初的 Spring Boot 3.5 生态下，JDK 17 依然是第三方库兼容性最好的"万金油"选择。若团队技术栈激进，可评估升级至 21，但需注意部分监控或链路追踪工具可能存在兼容性滞后。

2.2.官方兼容性对照表（存档参考）

SAA 的版本号前三位必须与上游 Spring AI 严格锁死。以下是官方确认的兼容矩阵，供你排查历史项目时参考：

2.3.关于Spring Boot 4.0的特别说明

截至2026年3月，Spring Boot 4.0.x​已发布。虽然它支持JDK 21+和Spring Framework 7，但Spring AI Alibaba 1.1.x主要针对Boot 3.5测试。如果你在4.0上强行引入SAA，极大概率会遇到ClassNotFoundException。对于生产项目，建议暂时停留在Boot 3.5+SAA 1.1.2​这一黄金组合，等待官方明确宣布支持4.0后再进行迁移。

2.4.快速决策指南

全新项目（2026年启动）： 无脑选JDK 17+Spring Boot 3.5.x+SAA 1.1.2.0。
存量项目（正在用Boot 3.3/3.4）： 先尝试升级Boot至 3.5，再引入SAA 1.1.2.0。如果无法升级Boot，则只能降级使用 SAA 1.0.x系列。
还在用Spring Boot 2.x： 请先完成基础架构升级（升到JDK 17+Boot 3.x），再考虑引入AI能力。SAA完全不支持​Spring Boot 2.x 。

锁定这个矩阵后，下一节我们将深入解析SAA独特的"四段式"版本号规则，让你彻底看懂每个数字背后的含义。

三、版本号解码：SAA 的"四段式"命名规则

当你看到 1.1.2.0这样的版本号时，可能会疑惑它比常见的 1.1.2多了一位。这并非手误，而是Spring AI Alibaba (SAA) 为了严格对齐上游生态而设计的"四段式"命名规则。理解这套规则，是避免依赖地狱的关键。

3.1 解剖版本号：<Spring AI>.<SAA Patch>

SAA的版本号本质上是"寄生"在Spring AI之上的。它的前三位严格锁死上游，第四位才是自己的发挥空间。

官方定义：SAA 使用四位版本号，前三位与 Spring AI 主版本对应，社区在此基础上持续迭代第四位版本号。

3.2 实战解码：以 1.1.2.0为例

当你引入spring-ai-alibaba-starter-dashscope:1.1.2.0时，实际上引入的是这样一组依赖：

spring-ai版本：必须为1.1.2。如果你的项目中混用了1.0.0或1.1.0，将直接导致ClassNotFoundException。
SAA特性： 基于Spring AI 1.1.2的第 0次补丁发布（通常是最新稳定版）。
记忆口诀： "前三位看齐，第四位自理"。选型时，先确定你要的Spring AI版本（如 1.1.2），再选择对应的SAA版本（如 1.1.2.0）。

3.3为什么这套规则如此严格？

Spring AI在 1.0.x到 1.1.x的演进中，核心接口（如 ChatClient、Agent）发生了不兼容的变更。
错误示范： 如果你强行组合Spring AI 1.1.2+SAA 1.0.0.2，由于SAA 1.0.x系列编译时依赖的是Spring AI 1.0.x的旧接口，运行时会出现方法签名不匹配或类找不到的致命错误。
**正确逻辑：**SAA 1.1.x.x系列只能与 Spring AI 1.1.x绑定；SAA 1.0.x.x系列只能与 Spring AI 1.0.x绑定。

3.4 最佳实践：让BOM替你管理

手动管理这四位数字极易出错。强烈建议使用Bill of Materials (BOM)​ 来统一版本，这是官方推荐的"防呆"机制。

<dependencyManagement>
    <dependencies>
        <!-- 引入 SAA BOM，它会自动锁定 Spring AI 的正确版本 -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>1.1.2.0</version> <!-- 只需改这里，所有子依赖自动对齐 -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

通过BOM引入后，你无需再显式指定spring-ai的版本，所有兼容性问题由BOM文件内部定义解决。

小结：SAA的版本号不是独立的数字游戏，而是与Spring AI的"联名款"。锁定 1.1.2.0，就意味着你已承诺使用Spring AI 1.1.2的生态。

四、实战：3分钟配置 Checklist

理论讲得再多，不如一次顺畅的实操。这一节将完全针对IntelliJ IDEA（建议2023.3及以上版本）的操作界面，手把手带你完成从创建到成功运行的全过程。

4.1 第一步：创建项目（Spring Initializr）

目标：搭建一个JDK 17+Spring Boot 3.5的纯净底座。
（1）打开IDEA：点击 File→ New→ Project。

（2）选择模板：在左侧选择 Spring Initializr。

（3）关键配置（请严格对照下表填写）：

（4）选择依赖：在Dependencies界面，暂时只勾选Spring Web。Spring AI Alibaba的依赖我们稍后手动添加（因为Initializr的版本可能滞后）。

（5）生成：点击Create，IDEA会自动下载并打开项目。

4.2 第二步：配置 Maven (pom.xml)

（1）目标： 将之前提到的"黄金组合"配置写入项目。
（2）打开文件： 在项目根目录找到 pom.xml，双击打开。
**（3）替换配置：**将以下代码完整复制，替换掉文件内原有的 <parent>和 <dependencies>部分。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 1. 锁定 Spring Boot 3.5.x 父版本 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.5</version> <!-- 确保是 3.5.x 系列 -->
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>spring-ai-alibaba-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-ai-alibaba-demo</name>
    <description>Demo project for Spring AI Alibaba</description>

    <properties>
        <java.version>17</java.version>
        <!-- 2. 定义 SAA 版本变量 -->
        <spring-ai-alibaba.version>1.1.2.0</spring-ai-alibaba.version>
    </properties>

    <!-- 3. 【关键】引入 BOM 统一版本管理 -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-bom</artifactId>
                <version>${spring-ai-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Spring Boot 基础依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- 4. 核心：Spring AI Alibaba 通义千问 Starter -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
            <version>${spring-ai-alibaba.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

**（3）刷新依赖：**保存文件后，IDEA右上角通常会弹出提示，点击Reload project（或者去右侧Maven面板点击刷新按钮 🔄）。等待控制台下载依赖完成，确保没有报错。

4.3 第三步：配置 API Key（环境变量）

目标：安全地设置 DASHSCOPE_API_KEY，这是调用通义千问的通行证。
（1）获取 Key： 登录 阿里云灵积(DashScope)控制台，创建一个 API Key 并复制（该部分的详细操作步骤，见我的博文《3、阿里云百炼平台API Key 申请指南》中）。
（2）IDEA 配置：

●点击顶部菜单 Run→ Edit Configurations...。

●在左侧选中你的Spring Boot主类（通常是 DemoApplication）。

●在右侧Environment variables一栏，点击输入框，添加：

DASHSCOPE_API_KEY=你的-api-key-here

●点击应用以及OK保存。

●然后将DASHSCOPE_API_KEY作为动态参数配置到application.yml或application.properties中：

spring.ai.dashscope.api-key=${DASHSCOPE_API_KEY}

最佳实践：强烈建议使用环境变量，而不是写在application.yml中，避免代码泄露密钥。

4.4 第四步：验证与运行

（1）检查SDK： 点击 File→ Project Structure→ Project，确认SDK和Language level都是 17：

（2）启动： 找到 src/main/java下的 XxxApplication，右键点击Run（绿色三角）：

（3）看日志： 观察控制台。成功的标志是看到 Started ... in X.XXX seconds，且没有​ ClassNotFoundException或 NoSuchMethodError等版本冲突错误：

4.5 IDEA 快速排错 Checklist

如果启动失败，请按此清单逐项核对：
●JDK 版本： File→ Project Structure→ Project中，SDK 是否为 17？
●Maven 刷新： 修改 pom.xml后，是否点击了 Reload project？
●BOM 生效： pom.xml中是否引入了 spring-ai-alibaba-bom，且Starter依赖没有写 <version>标签？
●环境变量： Run Configurations中是否正确设置了 DASHSCOPE_API_KEY？（注意不要有空格）

完成以上步骤，你的 Spring AI Alibaba 开发环境在 IDEA 中就已 100% 就绪。接下来可以开始编写你的第一个 ChatClient代码了。

下一章节我们讲解如何使用Spring AI Alibaba整合Ollama接入本地大模型。
转载请注明出处：https://blog.csdn.net/u013517797/article/details/159618324