（第二篇）Spring AI 基础入门：从环境搭建到模型接入全攻略（覆盖国内外模型 + 本地部署）

前言：为什么要学 Spring AI？

        最近在做 AI 应用开发时，发现很多朋友卡在了工具链整合这一步：用原生 SDK 调用 OpenAI 要处理一堆 HTTP 请求，切换到通义千问又得改大量代码，本地部署 Llama3 更是不知道怎么和 Spring 项目结合…

        直到接触了 Spring AI 才发现，这个框架简直是为 Java 开发者量身定做的 AI 开发工具 —— 它把不同模型的调用逻辑标准化了，不管是 OpenAI、通义千问还是本地 Llama3，都能用几乎一样的 API 调用。

        这篇教程从基础环境讲到实战接口，全程手把手操作，哪怕是 AI 开发新手，跟着走也能跑通第一个 Spring AI 应用。

目录

1. 基础环境搭建：JDK17+Maven3.8+Spring Boot3.x 核心配置

        Spring AI 依赖 Spring Boot3.x，而 Spring Boot3.x 强制要求 JDK17 及以上 —— 这一步要是版本错了，后面全白搭。

1.1 JDK17：必须选对的底层引擎

为什么是 JDK17？

• Spring Boot3.x 基于 Java 17 的模块化系统，用 JDK8 会直接报java.lang.UnsupportedClassVersionError
• Spring AI 的很多特性（比如 Record 类型接收模型响应）依赖 JDK17 语法
• 主流 AI 厂商的 Java SDK（如通义千问）默认支持 JDK17

安装步骤（以 Windows 为例）：

1.2 Maven3.8：依赖管理的加速器

为什么选 3.8？

• 对 JDK17 兼容性更好，老版本（如 3.6）可能出现依赖下载失败
• 支持 HTTPS 仓库（Spring AI 的仓库是 HTTPS，老版本可能报协议错误）

安装与配置：

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

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

步骤：

1.4 环境依赖关系图

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

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

2.1 OpenAI：最主流的商业模型

准备工作：

配置步骤：

在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 阿里云通义千问：国产模型优选

准备工作：

配置步骤：

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 等主流模型。

安装步骤：

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统一调用
• 网络问题：代理配置 + 异常日志解读能解决大部分坑
• 实战接口：同步和流式响应各有适用场景

进阶方向推荐：

如果觉得有用，欢迎点赞收藏，有问题可以在评论区交流 —— 后续会更新 Spring AI 的高级用法，关注不迷路！