Spring AI 基础入门：环境搭建与模型接入实战

阿里云镜像（国内下载 Spring AI 依赖提速）：

<mirrors>
  <mirror>
    <id>aliyun</id>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
</mirrors>

本地仓库（避免占 C 盘）：

<localRepository>D:\maven-repo</localRepository>

1.3 Spring Boot3.x + Spring AI：项目初始化

Spring AI 目前还没进入 Spring 官方仓库，需要手动添加仓库地址。

步骤：

1. 用 Spring Initializr 生成项目：
   • 版本选 3.2.4（最新稳定版）
   • 依赖勾选：Spring Web、Lombok、Spring Reactive Web（流式响应需要）
2. 等待 Maven 下载依赖（第一次可能需要 5-10 分钟，耐心等，别断网）

解压后打开 pom.xml，添加 Spring AI 仓库和核心依赖：

<!-- Spring AI 仓库 -->
<repositories>
  <repository>
    <id>spring-snapshots</id>
    <name>Spring Snapshots</name>
    <url>https://repo.spring.io/snapshot</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

<!-- Spring AI 核心依赖 -->
<dependencies>
  <!-- 模型调用核心 -->
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
    <version>0.8.1-SNAPSHOT</version>
  </dependency>
  <!-- OpenAI 支持 -->
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
    <version>0.8.1-SNAPSHOT</version>
  </dependency>
  <!-- 通义千问支持 -->
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tongyi</artifactId>
    <version>0.8.1-SNAPSHOT</version>
  </dependency>
  <!-- Ollama 本地模型支持 -->
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
    <version>0.8.1-SNAPSHOT</version>
  </dependency>
</dependencies>

1.4 环境依赖关系图

2. 商业模型接入：从密钥到调用全流程

Spring AI 的核心优势就是标准化接口——不管是哪个厂商的模型，调用方式几乎一样。

2.1 OpenAI：最主流的商业模型

准备工作：

1. 注册 OpenAI 账号：OpenAI 平台（需要国外手机号验证）
2. 创建 API 密钥：右上角头像 → View API keys → Create new secret key（密钥只显示一次，赶紧存起来）
3. 充值：新账号有免费额度，用完后需要绑定信用卡充值（支持 Visa/MasterCard）

配置步骤：

在 application.yml 中添加：

spring:
  ai:
    openai:
      api-key: 你的 sk-xxx 密钥
      chat:
        model: gpt-3.5-turbo # 模型名称，也可以用 gpt-4

测试代码：

import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequiredArgsConstructor // Lombok 自动注入
public class OpenAIController {
    private final ChatClient chatClient; // Spring AI 自动配置的客户端

    @GetMapping("/openai/chat")
    public String chat(@RequestParam String message) {
        // 调用模型并返回结果
        return chatClient.call(message);
    }
}

2.2 Azure OpenAI：国内可用的 OpenAI 平替

如果访问 OpenAI 官网困难，Azure OpenAI 是个好选择（需要企业资质申请）。

配置差异：

spring:
  ai:
    azure:
      openai:
        api-key: 你的 Azure 密钥
        endpoint: 你的资源端点（如 https://xxx.openai.azure.com/）
        deployment-name: 部署的模型名称（在 Azure 控制台创建）

2.3 阿里云通义千问：国产模型优选

准备工作：

1. 注册阿里云账号：阿里云控制台
2. 创建 AccessKey：头像 → AccessKey 管理 → 生成密钥（注意保存 AccessKey ID 和 Secret）
3. 开通通义千问服务：在阿里云 AI 平台开通对应模型（有免费额度）

配置步骤：

spring:
  ai:
    tongyi:
      api-key: 你的 AccessKey ID
      secret-key: 你的 AccessKey Secret
      chat:
        model: qwen-turbo # 基础版，也可用 qwen-plus

调用代码：

和 OpenAI 完全一样！只需注入 ChatClient，因为 Spring AI 已经统一了接口：

@GetMapping("/tongyi/chat")
public String tongyiChat(@RequestParam String message) {
    return chatClient.call(message); // 和 OpenAI 调用代码完全相同
}

2.4 模型接入流程图

3. 本地私有化部署：Ollama+Llama3 搭建无网络依赖服务

如果对数据隐私敏感，或者需要离线运行，本地部署 Llama3 是最佳选择。

3.1 Ollama：最简单的本地模型运行工具

Ollama 是一个轻量级工具，能一键运行 Llama3、Mistral 等主流模型。

安装步骤：

1. 下载 Ollama：官网（支持 Windows/Mac/Linux，Windows 需要 WSL2）
2. 安装后启动：会自动在本地启动一个服务（默认端口 11434）

拉取 Llama3 模型：打开 cmd，输入：

ollama run llama3

首次运行会下载模型（约 4.7GB，耐心等），下载完成后会进入交互模式，输入 你好 测试是否可用。

3.2 Spring AI 接入本地 Llama3

配置 application.yml：

spring:
  ai:
    ollama:
      base-url: http://localhost:11434 # Ollama 默认地址
      chat:
        model: llama3 # 模型名称
        options:
          temperature: 0.7 # 随机性（0-1，越低越稳定）

调用代码：

还是熟悉的 ChatClient！Spring AI 的标准化接口在这里体现得淋漓尽致：

@GetMapping("/local/chat")
public String localChat(@RequestParam String message) {
    return chatClient.call(message); // 和调用 OpenAI、通义千问的代码完全一样
}

注意事项：

本地模型性能依赖硬件：Llama3-8B 至少需要 16GB 内存，GPU 加速需要 NVIDIA 显卡（支持 CUDA） 响应速度比商业模型慢：首次调用可能需要预热 3-5 秒

4. 代理配置与排坑指南：解决 90% 的网络问题

调用国外模型时，网络问题是最常见的拦路虎，这部分教你怎么排查和解决。

4.1 代理配置：让请求顺利出国

如果你的网络需要代理才能访问 OpenAI，在 application.yml 中添加：

spring:
  ai:
    openai:
      # 其他配置...
      client:
        proxy:
          host: 127.0.0.1 # 代理服务器地址
          port: 7890 # 代理端口（根据你的代理工具填写）

也可以通过 JVM 参数配置（适合开发环境）：在 IDEA 的启动配置中，添加 VM 选项：

-Dhttp.proxyHost=127.0.0.1
-Dhttp.proxyPort=7890
-Dhttps.proxyHost=127.0.0.1
-Dhttps.proxyPort=7890

4.2 常见网络异常与解决

异常 1：java.net.ConnectException: Connection timed out

原因：没开代理，或代理端口错误 解决：检查代理是否启动，端口是否和配置一致

异常 2：SSLHandshakeException: PKIX path building failed

原因：代理证书问题（比如使用了自签名证书） 解决：添加 JVM 参数忽略证书验证（仅开发环境用）：

-Djavax.net.ssl.trustStoreType=JKS
-Djavax.net.ssl.trustStore=路径/to/cacerts # JDK 安装目录下的 jre/lib/security/cacerts
-Djavax.net.ssl.trustStorePassword=changeit # 默认密码

异常 3：429 Too Many Requests

• 原因：API 调用频率超过限制
• 解决：在配置中添加限流参数：

spring:
  ai:
    openai:
      chat:
        options:
          rate-limit:
            enabled: true
            requests-per-second: 5 # 每秒最多 5 次请求

5. 实战：同步响应 vs 流式响应 对话接口开发

实际开发中，同步响应适合简单场景，流式响应（像 ChatGPT 那样逐字输出）更适合用户体验。

5.1 同步响应接口

就是前面写的简单调用，适合一次性获取结果：

@GetMapping("/sync/chat")
public String syncChat(@RequestParam String message) {
    return chatClient.call(message);
}

测试：访问 http://localhost:8080/sync/chat?message=介绍下 Spring AI，会等模型生成完整结果后一次性返回。

5.2 流式响应接口

需要用 WebFlux 的 Flux（响应式编程），实现逐字输出：

import org.springframework.ai.chat.ChatResponse;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
@RequiredArgsConstructor
public class StreamController {
    private final ChatClient chatClient; // 注意：MediaType 设为 TEXT_EVENT_STREAM_VALUE

    @GetMapping(value = "/stream/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestParam String message) {
        // 构建用户消息
        Prompt prompt = new Prompt(new UserMessage(message));
        // 调用流式接口，返回 Flux<ChatResponse>
        return chatClient.stream(prompt)
                // 提取每个响应中的内容
                .map(chatResponse -> chatResponse.getResult().getOutput().getContent());
    }
}

测试：用 Postman 访问 http://localhost:8080/stream/chat?message=介绍下 Spring AI，会看到内容逐段返回，和 ChatGPT 的体验一致。

5.3 两种响应方式对比

6. 总结与进阶方向

通过这篇教程，你已经掌握了 Spring AI 的核心环境搭建和模型接入方法：

基础环境：JDK17+Maven3.8+Spring Boot3.x 是必须的铁三角 模型接入：OpenAI / 通义千问 / Ollama 本地模型都能用 ChatClient 统一调用 网络问题：代理配置 + 异常日志解读能解决大部分坑 实战接口：同步和流式响应各有适用场景

进阶方向推荐：

1. 多模型切换：用 Spring AI 的 ModelSelector 实现根据场景自动选模型
2. Prompt 工程：结合 PromptTemplate 优化提示词，提升模型响应质量
3. 本地模型优化：给 Ollama 配置 GPU 加速，提升 Llama3 响应速度