菜鸟AI
菜鸟AI AI提示词 · 教程 · 资讯
首页>进阶教程

Spring AI实战指南：从环境搭建到模型接入一站式教程

2026-06-13阅读 0热度 0
ai

前言：为什么要学 Spring AI？

最近在捣鼓 AI 应用开发，发现不少朋友卡在了工具链整合这一环。用原生 SDK 调 OpenAI，得处理一堆 HTTP 请求；切换到通义千问，又得改大量代码；本地部署个 Llama3 更是不知道怎么跟 Spring 项目揉在一起。

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

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

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

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

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

为什么是 JDK17？ 简单来说，JDK17 是长期支持版本，性能稳定，而且 Spring Boot3.x 和 Spring AI 都基于它构建。用旧版本会直接报编译错误，没得商量。

安装步骤（以 Windows 为例）：

  1. 下载地址：推荐 Eclipse Temurin 17（OpenJDK 的稳定发行版，免费且无限制使用）。
  2. 安装注意：路径绝对不能有空格或中文。比如放在 D:\jdk17，别放 Program Files 这类带空格的目录。
  3. 配置环境变量：
    • 新建 JA VA_HOME，值为安装路径（如 D:\jdk17）。
    • 编辑 Path，添加 %JA VA_HOME%\bin，建议把它移到最上面，避免和其他 JDK 版本冲突。
  4. 验证：在 cmd 中输入 ja va -version，如果能看到类似以下信息，说明配置成功：
    openjdk version "17.0.10" 2024-01-16
    OpenJDK Runtime Environment Temurin-17.0.10+7 (build 17.0.10+7)
    OpenJDK 64-Bit Server VM Temurin-17.0.10+7 (build 17.0.10+7, mixed mode, sharing)

1.2 Ma ven3.8：依赖管理的翻跟斗

为什么选 3.8？ 3.8.x 系列是经过广泛验证的稳定版本，兼容性好，而且配置简单。

安装与配置：

  1. 下载：Apache Ma ven 3.8.8（3.8.x 最新稳定版）。
  2. 解压到无空格路径，比如 D:\ma ven3.8。
  3. 环境变量：
    • 新建 MA VEN_HOME，值为 D:\ma ven3.8。
    • Path 添加 %MA VEN_HOME%\bin。
  4. 验证：运行 mvn -v，能看到版本信息即可。
  5. 关键配置（在 conf/settings.xml 中）：
    • 本地仓库路径（避免占用 C 盘空间）：
      D:\ma ven-repo
    • 阿里云镜像（国内下载 Spring AI 依赖能提速 10 倍）：


      aliyun
      阿里云公共仓库
      https://ma ven.aliyun.com/repository/public
      central

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

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

步骤：

  1. 用 Spring Initializr 生成项目：
    • 版本选 3.2.4（最新稳定版）。
    • 依赖勾选：Spring Web、Lombok、Spring Reactive Web（流式响应需要用到）。
  2. 解压后打开 pom.xml，添加 Spring AI 仓库和核心依赖：



    spring-snapshots
    Spring Snapshots
    https://repo.spring.io/snapshot

    true








    org.springframework.ai
    spring-ai-core
    0.8.1-SNAPSHOT



    org.springframework.ai
    spring-ai-openai
    0.8.1-SNAPSHOT



    org.springframework.ai
    spring-ai-tongyi
    0.8.1-SNAPSHOT



    org.springframework.ai
    spring-ai-ollama
    0.8.1-SNAPSHOT

  3. 等待 Ma ven 下载依赖。第一次可能需要 5-10 分钟，保持网络畅通，耐心等待就好。

1.4 环境依赖关系图

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

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

2.1 OpenAI：最主流的商业模型

准备工作：

  1. 注册 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）。
  3. 拉取 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、通义千问的代码完全一样
}

注意事项： 本地模型响应速度受硬件性能影响，建议至少配备 8GB 显存的显卡。如果使用 CPU 模式，响应时间会明显变长。

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：ja va.net.ConnectException: Connection timed out
原因：网络不通，可能是袋里配置错误或目标服务器不可达。检查袋里地址和端口，确保袋里工具处于运行状态。

异常 2：SSLHandshakeException: PKIX path building failed
原因：SSL 证书验证失败，常见于使用自签名证书或某些袋里工具。可以尝试在 JVM 参数中添加 -Dcom.sun.net.ssl.checkRevocation=false 或直接导入证书。

异常 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 streamChat(@RequestParam String message) {
// 构建用户消息
Prompt prompt = new Prompt(new UserMessage(message));
// 调用流式接口，返回Flux
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 的核心环境搭建和模型接入方法。

进阶方向推荐：

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

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

上一篇二零二六年五月人工智能大模型周报权威榜单：推理多模态智能体加速发展 下一篇DeepSeek V4推理成本优化监控体系搭建：降本65%实战指南
免责声明

本网站新闻资讯均来自公开渠道，力求准确但不保证绝对无误，内容观点仅代表作者本人，与本站无关。若涉及侵权，请联系我们处理。本站保留对声明的修改权，最终解释权归本站所有。

相关阅读

更多

最新教程

Stable Diffusion WebUI整合包下载与模型放置全指南HunyuanVideo安装失败排查指南：依赖、显存与工作流问题解决Runway官网入口与使用指南：下载注册及常见问题全解析Notion AI新手入门指南：从下载到模板设置的完整教程GitHub Copilot安装指南：JetBrains插件市场一键配置与激活全流程2026年ComfyUI安装与配置终极指南：从零部署到高效出图全流程解析CogVideoX安装包获取与部署指南：从下载到剪辑机配置的完整教程2024图像识别实战精选：基于EasyDL的完整案例解析与测评

最新资讯

Harness vs Loop Engineering：2025 DevOps工具深度对比EMR Spark Relational Cache跨集群同步精选指南Hermes技能测评：一条命令省10分钟，效率提升300%瑞幸Skill实测：点一杯咖啡需要消耗多少Token云HIS前后端分离源码实践：SpringBoot+Bootstrap+jQueryAI智能体开发技术方案深度对比与推荐阿里云ESSD-AutoPL云盘性能测评与计费对比AI开发微信小程序教程：5分钟快速入门指南
欢迎回来 登录或注册后，可保存提示词和历史记录
登录后可同步收藏、历史记录和常用模板
注册即表示同意服务条款与隐私政策