第1天-Spring-AI-Alibaba简介与环境搭建

三十

Spring AI Alibaba 简介与环境搭建

系列文章第1篇 | 预计阅读时间：20分钟 | 难度：⭐
本文带你从零开始，全面了解 Spring AI Alibaba 是什么、为什么选它、以及如何搭建第一个可运行的 AI 应用开发环境。

目录

  1. 什么是 Spring AI Alibaba？
  2. 为什么选择 Spring AI Alibaba？
  3. 技术架构全景图
  4. 环境准备
  5. 创建 Spring Boot 项目
  6. 集成 Spring AI Alibaba 依赖
  7. 配置大模型连接（通义千问）
  8. 编写第一个 AI 对话应用
  9. 项目结构最佳实践
  10. 常见问题排查
  11. 总结与下一步

1. 什么是 Spring AI Alibaba？

Spring AI Alibaba 是阿里巴巴开源的、基于 Spring AI 生态的 AI 应用开发框架。它将大语言模型（LLM）的能力无缝集成到 Spring Boot 生态中，让 Java 开发者能够用熟悉的 Spring 编程模型来构建 AI 驱动的应用。

1.1 背景与定位

Spring AI 是 Spring 官方推出的 AI 应用开发框架，提供了统一的 AI 模型接口抽象。而 Spring AI Alibaba 在此基础上，深度集成了阿里云通义千问（Qwen）系列模型以及阿里巴巴在 AI 工程化方面的最佳实践。

简单来说：

  • Spring AI = 统一的 AI 编程模型（类似 Spring Data 对数据库的抽象）
  • Spring AI Alibaba = Spring AI + 通义千问模型 + 阿里工程实践

1.2 核心能力

Spring AI Alibaba 提供以下核心能力：

能力模块说明
ChatModel对话模型接口，支持同步/流式对话
EmbeddingModel向量嵌入模型，用于语义搜索
Function Calling工具调用，让 AI 可以调用外部 API
RAG 支持检索增强生成，构建知识库问答
Agent 框架智能体编排，多步推理与决策
Model Adapter多模型适配，支持通义千问、OpenAI 等

1.3 版本兼容性

截至本文撰写时（2026年4月），Spring AI Alibaba 主要版本如下：

  • Spring AI Alibaba 1.0.0-M4+：支持 Spring Boot 3.2.x / 3.3.x
  • Spring Boot 3.x 是必须的（基于 Java 17+）
  • 通义千问 DashScope SDK 2.x

2. 为什么选择 Spring AI Alibaba？

2.1 对比其他方案

维度Spring AI AlibabaLangChain4jOpenAI SDK
生态融合原生 Spring 生态Java 独立库REST API 封装
依赖注入天然支持 @Autowired手动管理手动管理
配置管理application.yml 统一配置代码配置为主环境变量
企业集成Spring Cloud/Security 无缝集成需要额外适配需要额外适配
国产模型通义千问原生支持需自行适配不支持
学习成本Spring 开发者零门槛需学习新范式需学习新范式

2.2 核心优势

① 熟悉的 Spring 编程模型

// 像注入 DataSource 一样注入 AI 模型
@Autowired
private ChatModel chatModel;

// 像调用 Service 一样调用 AI
String response = chatModel.call("你好，请介绍一下自己");

② 开箱即用的企业级特性

  • Spring Boot AutoConfiguration 自动装配
  • 配置中心（Nacos）动态切换模型
  • Spring Security 集成 AI 权限控制
  • Spring Cloud 微服务部署

③ 通义千问深度优化

  • 原生支持 Qwen-Max / Qwen-Plus / Qwen-Turbo 等全系列模型
  • 针对通义千问的 Function Calling 协议深度适配
  • 阿里云 DashScope API 性能优化

3. 技术架构全景图

┌─────────────────────────────────────────────────────────────┐
│                    你的 Spring Boot 应用                      │
├─────────────────────────────────────────────────────────────┤
│  Controller 层  →  @RestController + AI 接口暴露              │
│  Service 层     →  @Service + 业务逻辑 + AI 编排              │
├─────────────────────────────────────────────────────────────┤
│              Spring AI Alibaba 核心层                         │
│  ┌────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│  │ ChatModel  │ │ EmbeddingModel│ │ FunctionCallback       │ │
│  │ (对话模型)  │ │ (向量嵌入)    │ │ (工具回调/函数调用)      │ │
│  └────────────┘ └──────────────┘ └────────────────────────┘ │
│  ┌────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│  │ Prompt     │ │ OutputParser │ │ VectorStore            │ │
│  │ (提示词模板) │ │ (输出解析)    │ │ (向量存储)              │ │
│  └────────────┘ └──────────────┘ └────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│              Spring AI 抽象层 (spring-ai-core)               │
│  Model / ChatClient / Advisor / ToolCallingManager          │
├─────────────────────────────────────────────────────────────┤
│              模型适配器层                                     │
│  ┌────────────────┐  ┌──────────────┐  ┌─────────────────┐ │
│  │ DashScope      │  │ OpenAI       │  │ Ollama / 其他    │ │
│  │ (通义千问)      │  │ (兼容接口)    │  │ (本地模型)       │ │
│  └────────────────┘  └──────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│              底层通信层                                      │
│  HTTP Client / WebSocket / SSE (Server-Sent Events)         │
└─────────────────────────────────────────────────────────────┘

3.1 关键抽象类说明

抽象类/接口作用典型实现
ChatModel对话模型统一接口DashScopeChatModel
EmbeddingModel向量嵌入接口DashScopeEmbeddingModel
ImageModel图像生成接口DashScopeImageModel
AudioTranscriptionModel语音转文本DashScopeAudioTranscriptionModel
VectorStore向量存储接口MilvusVectorStore
ChatClient高级对话客户端DefaultChatClient

4. 环境准备

4.1 JDK 安装

Spring AI Alibaba 要求 Java 17 或更高版本。推荐使用 JDK 21（LTS）。

# 检查 Java 版本
java -version

# 如果未安装，可以使用 SDKMAN 安装
# curl -s "https://get.sdkman.io" | bash
# sdk install java 21.0.2-tem

确认输出包含 version "17" 或更高：

openjdk version "21.0.2" 2024-01-16 LTS
OpenJDK Runtime Environment Temurin-21.0.2+13 (build 21.0.2+13-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.2+13 (build 21.0.2+13-LTS, mixed mode)

4.2 Maven 安装

推荐使用 Maven 3.9+：

mvn -version

4.3 获取通义千问 API Key

  1. 访问 阿里云 DashScope 控制台
  2. 登录阿里云账号
  3. 在「API-KEY管理」页面创建新的 API Key
  4. 复制保存 Key（格式类似：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）

注意：通义千问为新用户提供了一定的免费额度，足够用于学习和开发。

4.4 IDE 推荐

  • IntelliJ IDEA（推荐，对 Spring Boot 支持最好）
  • VS Code + Java Extension Pack
  • Eclipse（需要额外配置）

5. 创建 Spring Boot 项目

5.1 方式一：使用 Spring Initializr（推荐）

访问 https://start.spring.io，配置如下：

Project: Maven
Language: Java
Spring Boot: 3.3.x
Group: com.example
Artifact: spring-ai-alibaba-demo
Packaging: Jar
Java: 17（或 21）
Dependencies: Spring Web, Spring Boot DevTools

点击下载生成项目，解压后导入 IDE。

5.2 方式二：使用命令行

curl https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.3.5 \
  -d baseDir=spring-ai-alibaba-demo \
  -d groupId=com.example \
  -d artifactId=spring-ai-alibaba-demo \
  -d javaVersion=21 \
  -d dependencies=web,devtools \
  -o spring-ai-alibaba-demo.zip

unzip spring-ai-alibaba-demo.zip
cd spring-ai-alibaba-demo

5.3 方式三：手动创建 pom.xml

如果你需要从零开始创建项目，以下是一个完整的 pom.xml 模板：

<?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>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.5</version>
        <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>Spring AI Alibaba 入门示例</description>

    <properties>
        <java.version>21</java.version>
        <spring-ai-alibaba.version>1.0.0-M4.1</spring-ai-alibaba.version>
        <spring-ai.version>1.0.0-M4</spring-ai.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring AI Alibaba - 通义千问 -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter</artifactId>
            <version>${spring-ai-alibaba.version}</version>
        </dependency>

        <!-- Spring Boot DevTools -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>

        <!-- Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <repositories>
        <!-- Spring AI Alibaba Maven 仓库 -->
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>sonatype-snapshots</id>
            <name>Sonatype Snapshots</name>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>

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

关键点说明：

  • spring-ai-alibaba-starter 是核心依赖，包含了通义千问模型适配器和所有必要的 AutoConfiguration
  • 版本号需要与 Spring AI 核心版本匹配（1.0.0-M4.1 对应 spring-ai 1.0.0-M4）
  • 必须添加 spring-milestones 仓库，因为 Milestone 版本不在 Maven Central

6. 集成 Spring AI Alibaba 依赖

6.1 核心依赖详解

spring-ai-alibaba-starter 这个 Starter 内部包含了以下关键模块：

spring-ai-alibaba-starter
├── spring-ai-alibaba-autoconfigure    # 自动配置
├── spring-ai-dashscope                # DashScope SDK 集成
│   ├── DashScopeChatModel            # 聊天模型
│   ├── DashScopeEmbeddingModel       # 嵌入模型
│   ├── DashScopeImageModel           # 图像模型
│   └── DashScopeAudioTranscriptionModel  # 语音模型
└── spring-ai-alibaba-core             # 核心工具类

6.2 可选依赖

根据项目需求，你可能还需要以下依赖：

<!-- 向量存储 - Milvus -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-milvus-store-spring-boot-starter</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

<!-- 向量存储 - Redis -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-redis-store-spring-boot-starter</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

<!-- 向量存储 - PostgreSQL (pgvector) -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

<!-- 文档解析 - PDF -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pdf-document-reader</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

7. 配置大模型连接（通义千问）

7.1 application.yml 基本配置

在 src/main/resources/application.yml 中添加以下配置：

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY:sk-your-api-key-here}
      chat:
        options:
          model: qwen-plus          # 模型选择
          temperature: 0.7          # 创造性控制 (0.0-1.0)
          top-p: 0.8               # 核采样参数
          top-k: 50                # 候选词数量
          max-tokens: 2048         # 最大输出长度
          enable-search: false     # 是否开启联网搜索
      embedding:
        options:
          model: text-embedding-v3  # 向量嵌入模型
          dimensions: 1024          # 向量维度

7.2 环境变量方式（推荐生产环境）

# 在环境变量中设置 API Key
export DASHSCOPE_API_KEY=sk-your-actual-api-key

# 或者写入 .env 文件（需要 dotenv 支持）
# .env
# DASHSCOPE_API_KEY=sk-your-actual-api-key

7.3 模型选择指南

通义千问提供多种模型，各有适用场景：

模型特点适用场景参考成本
qwen-turbo速度快、成本低简单对话、文本分类低
qwen-plus平衡性能与成本通用任务、大多数场景中
qwen-max最强推理能力复杂推理、代码生成高
qwen-max-latest最新优化版本需要最新能力的场景高

建议：开发阶段使用 qwen-plus，生产环境根据实际需求和成本选择。

7.4 多模型配置

如果你需要在不同场景使用不同模型，可以通过 ChatClient 动态指定：

@Bean
public ChatClient qwenTurboClient(ChatModel chatModel) {
    return ChatClient.builder(chatModel)
            .defaultOptions(OpenAiChatOptions.builder()
                    .withModel("qwen-turbo")
                    .build())
            .build();
}

@Bean
public ChatClient qwenMaxClient(ChatModel chatModel) {
    return ChatClient.builder(chatModel)
            .defaultOptions(OpenAiChatOptions.builder()
                    .withModel("qwen-max")
                    .build())
            .build();
}

7.5 测试连接

配置完成后，编写一个简单的连接测试：

package com.example.demo;

import org.springframework.ai.chat.model.ChatModel;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class SpringAiAlibabaDemoApplication {

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

    /**
     * 启动时测试 AI 连接是否正常
     */
    @Bean
    CommandLineRunner testAiConnection(ChatModel chatModel) {
        return args -> {
            System.out.println("=== 测试 AI 连接 ===");
            String response = chatModel.call("你好，请用一句话介绍你自己");
            System.out.println("AI 回复: " + response);
            System.out.println("=== 连接测试完成 ===");
        };
    }
}

运行 mvn spring-boot:run，如果看到 AI 的正常回复，说明环境配置成功。

8. 编写第一个 AI 对话应用

8.1 项目目录结构

spring-ai-alibaba-demo/
├── src/
│   ├── main/
│   │   ├── java/com/example/demo/
│   │   │   ├── SpringAiAlibabaDemoApplication.java
│   │   │   ├── controller/
│   │   │   │   └── ChatController.java          # REST API 控制器
│   │   │   ├── service/
│   │   │   │   ├── ChatService.java              # 业务逻辑层
│   │   │   │   └── impl/
│   │   │   │       └── ChatServiceImpl.java
│   │   │   ├── config/
│   │   │   │   └── AiConfig.java                 # AI 配置类
│   │   │   └── dto/
│   │   │       ├── ChatRequest.java              # 请求 DTO
│   │   │       └── ChatResponse.java             # 响应 DTO
│   │   └── resources/
│   │       ├── application.yml
│   │       └── application-dev.yml
│   └── test/
│       └── java/com/example/demo/
│           └── ChatServiceTest.java
└── pom.xml

8.2 DTO 定义

// ChatRequest.java
package com.example.demo.dto;

import jakarta.validation.constraints.NotBlank;

public class ChatRequest {
    
    @NotBlank(message = "消息内容不能为空")
    private String message;
    
    private String systemPrompt;  // 可选的系统提示词
    private Double temperature;   // 可选的温度参数
    
    // Getters & Setters
    public String getMessage() { return message; }
    public void setMessage(String message) { this.message = message; }
    public String getSystemPrompt() { return systemPrompt; }
    public void setSystemPrompt(String systemPrompt) { this.systemPrompt = systemPrompt; }
    public Double getTemperature() { return temperature; }
    public void setTemperature(Double temperature) { this.temperature = temperature; }
}

// ChatResponse.java
package com.example.demo.dto;

public class ChatResponse {
    private String content;
    private String model;
    private long responseTimeMs;
    
    // Getters & Setters
    public String getContent() { return content; }
    public void setContent(String content) { this.content = content; }
    public String getModel() { return model; }
    public void setModel(String model) { this.model = model; }
    public long getResponseTimeMs() { return responseTimeMs; }
    public void setResponseTimeMs(long responseTimeMs) { this.responseTimeMs = responseTimeMs; }
}

8.3 Service 层实现

// ChatService.java
package com.example.demo.service;

import com.example.demo.dto.ChatRequest;
import com.example.demo.dto.ChatResponse;

public interface ChatService {
    ChatResponse chat(ChatRequest request);
    String simpleChat(String message);
}

// ChatServiceImpl.java
package com.example.demo.service.impl;

import com.example.demo.dto.ChatRequest;
import com.example.demo.dto.ChatResponse;
import com.example.demo.service.ChatService;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.SystemPromptTemplate;
import org.springframework.ai.chat.prompt.UserMessage;
import org.springframework.ai.dashscope.api.DashScopeApi;
import org.springframework.stereotype.Service;

import java.util.Map;

@Service
public class ChatServiceImpl implements ChatService {

    private final ChatModel chatModel;

    public ChatServiceImpl(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @Override
    public String simpleChat(String message) {
        // 最简调用方式：直接传入字符串
        return chatModel.call(message);
    }

    @Override
    public ChatResponse chat(ChatRequest request) {
        long startTime = System.currentTimeMillis();
        
        // 构建 Prompt
        var prompt = buildPrompt(request);
        
        // 调用模型
        ChatResponse response = chatModel.call(prompt);
        
        long responseTime = System.currentTimeMillis() - startTime;
        
        // 封装响应
        ChatResponse result = new ChatResponse();
        result.setContent(response.getResult().getOutput().getContent());
        result.setModel("qwen-plus");
        result.setResponseTimeMs(responseTime);
        
        return result;
    }
    
    /**
     * 构建 Prompt 对象
     */
    private Prompt buildPrompt(ChatRequest request) {
        // 如果有自定义系统提示词，使用系统提示词
        if (request.getSystemPrompt() != null && !request.getSystemPrompt().isBlank()) {
            return new Prompt(
                    new org.springframework.ai.chat.messages.SystemMessage(request.getSystemPrompt()),
                    new UserMessage(request.getMessage())
            );
        }
        
        // 默认只使用用户消息
        return new Prompt(new UserMessage(request.getMessage()));
    }
}

8.4 Controller 层

// ChatController.java
package com.example.demo.controller;

import com.example.demo.dto.ChatRequest;
import com.example.demo.dto.ChatResponse;
import com.example.demo.service.ChatService;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/chat")
public class ChatController {

    private final ChatService chatService;

    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }

    /**
     * 简单对话接口
     * GET /api/chat/simple?message=你好
     */
    @GetMapping("/simple")
    public ResponseEntity<String> simpleChat(@RequestParam String message) {
        return ResponseEntity.ok(chatService.simpleChat(message));
    }

    /**
     * 完整对话接口
     * POST /api/chat
     * Body: { "message": "你好", "systemPrompt": "你是一个专业的Java程序员" }
     */
    @PostMapping
    public ResponseEntity<ChatResponse> chat(@Valid @RequestBody ChatRequest request) {
        return ResponseEntity.ok(chatService.chat(request));
    }

    /**
     * 健康检查
     */
    @GetMapping("/health")
    public ResponseEntity<String> health() {
        try {
            String test = chatService.simpleChat("你好");
            return ResponseEntity.ok("AI 服务正常: " + test);
        } catch (Exception e) {
            return ResponseEntity.internalServerError()
                    .body("AI 服务异常: " + e.getMessage());
        }
    }
}

8.5 运行与测试

启动应用后，可以通过以下方式测试：

# 测试简单对话
curl "http://localhost:8080/api/chat/simple?message=Java和Python哪个更适合做AI开发？"

# 测试完整对话
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "请解释Spring Boot的自动配置原理",
    "systemPrompt": "你是一个资深的Java技术专家，善于用通俗易懂的语言解释技术概念"
  }'

# 健康检查
curl http://localhost:8080/api/chat/health

9. 项目结构最佳实践

9.1 分层架构建议

controller/     → 处理 HTTP 请求，参数校验，响应封装
  ↓
service/        → 业务逻辑，AI 调用编排，异常处理
  ↓
ai/             → AI 专用层（可选，项目较大时推荐）
  ├── prompt/   → Prompt 模板定义
  ├── tool/     → Function Calling 工具定义
  └── advisor/  → ChatClient Advisor 配置
  ↓
model/ (AI)     → Spring AI 自动注入的 ChatModel 等

9.2 Prompt 模板管理

对于复杂项目，建议将 Prompt 模板独立管理：

// prompt/PromptTemplates.java
package com.example.demo.ai.prompt;

public final class PromptTemplates {
    
    private PromptTemplates() {}
    
    /** 代码审查系统提示词 */
    public static final String CODE_REVIEW_SYSTEM = """
        你是一位资深的 Java 代码审查专家。
        请从以下维度审查代码：
        1. 代码规范性
        2. 潜在 Bug
        3. 性能问题
        4. 安全漏洞
        5. 可维护性建议
        请用中文回复，格式清晰。
        """;
    
    /** 翻译系统提示词 */
    public static final String TRANSLATION_SYSTEM = """
        你是一位专业的技术文档翻译专家。
        请将以下内容翻译成{targetLanguage}。
        要求：
        - 保持技术术语的准确性
        - 语言流畅自然
        - 保留代码片段不做翻译
        """;
}

9.3 配置文件分层

# application.yml (通用配置)
spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}

# application-dev.yml (开发环境)
spring:
  ai:
    dashscope:
      chat:
        options:
          model: qwen-turbo    # 开发用便宜的模型
          temperature: 0.9     # 更有创造性

# application-prod.yml (生产环境)
spring:
  ai:
    dashscope:
      chat:
        options:
          model: qwen-max      # 生产用最强模型
          temperature: 0.3     # 更稳定可预测
          max-tokens: 4096

10. 常见问题排查

10.1 API Key 问题

错误现象：

org.springframework.ai.retry.NonTransientAiException: 
DashScope API error: InvalidApiKey

解决方案：

  1. 检查 API Key 格式是否正确（应以 sk- 开头）
  2. 确认环境变量 DASHSCOPE_API_KEY 已正确设置
  3. 登录 DashScope 控制台确认 API Key 状态为「启用」

10.2 依赖版本冲突

错误现象：

ClassNotFoundException: org.springframework.ai.chat.model.ChatModel

解决方案：

  1. 检查 spring-ai-alibaba-starter 和 spring-ai 版本是否匹配
  2. 运行 mvn dependency:tree 查看依赖树
  3. 确保添加了 spring-milestones 仓库

10.3 模型超时

错误现象：

java.net.SocketTimeoutException: Read timed out

解决方案：

spring:
  ai:
    dashscope:
      timeout: 60000  # 设置超时时间为 60 秒
      chat:
        options:
          max-tokens: 1024  # 适当减少输出长度

10.4 自动装配失败

错误现象：

Parameter 0 of constructor in ChatServiceImpl required a bean of type 
'org.springframework.ai.chat.model.ChatModel' that could not be found.

解决方案：

  1. 确认已正确配置 spring.ai.dashscope.api-key
  2. 检查 spring-ai-alibaba-starter 依赖是否正确引入
  3. 查看启动日志中是否有 DashScopeChatAutoConfiguration 的加载信息

10.5 调试技巧

在 application.yml 中开启详细日志：

logging:
  level:
    com.alibaba.cloud.ai: DEBUG
    org.springframework.ai: DEBUG

这样可以看到模型请求和响应的完整内容，有助于排查问题。

11. 总结与下一步

11.1 本文要点回顾

要点内容
什么是Spring AI Alibaba 是 Spring AI + 通义千问的企业级 AI 开发框架
为什么选原生 Spring 生态、通义千问深度优化、企业级特性开箱即用
环境要求Java 17+、Maven 3.9+、通义千问 API Key
核心依赖spring-ai-alibaba-starter
核心配置spring.ai.dashscope.api-key + 模型选项
最简单调用chatModel.call("你的问题")

11.2 快速上手 Checklist

  • 安装 JDK 17+
  • 获取通义千问 API Key
  • 创建 Spring Boot 3.3 项目
  • 添加 spring-ai-alibaba-starter 依赖
  • 配置 API Key 到环境变量
  • 编写第一个 ChatModel 调用
  • 成功运行并收到 AI 回复 ✅

11.3 下一步

在下一篇中，我们将深入探讨 Spring AI Alibaba 的核心概念：AI Model 体系，包括：

  • ChatModel、EmbeddingModel、ImageModel 的完整体系
  • 各模型的适用场景与选型指南
  • 底层架构与源码解析
  • 多模型切换的实现方式

敬请期待！