当前位置： 首页 > news >正文

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

news 2025/10/24 8:19:11

 

前言：为什么要学 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 核心配置
  2. 商业模型接入：OpenAI/Azure OpenAI / 通义千问 密钥配置与调用
  3. 本地私有化部署：Ollama+Llama3 搭建专属 AI 服务
  4. 代理配置与排坑指南：从网络异常到日志解读
  5. 实战：同步响应 vs 流式响应 对话接口开发
  6. 总结与进阶方向

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. 下载地址：推荐Eclipse Temurin 17（OpenJDK 的稳定发行版，免费无限制）
  2. 安装注意：路径绝对不能有空格或中文（比如D:\jdk17，别放Program Files）
  3. 配置环境变量：
    • 新建JAVA_HOME：值为安装路径（如D:\jdk17）
    • 编辑Path：添加%JAVA_HOME%\bin（建议移到最上面，避免和其他 JDK 冲突）
  4. 验证：cmd 输入java -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 Maven3.8：依赖管理的加速器

为什么选 3.8？
  • 对 JDK17 兼容性更好，老版本（如 3.6）可能出现依赖下载失败
  • 支持 HTTPS 仓库（Spring AI 的仓库是 HTTPS，老版本可能报协议错误）
安装与配置：
  1. 下载：Apache Maven 3.8.8（3.8.x 最新稳定版）
  2. 解压到无空格路径（如D:\maven3.8）
  3. 环境变量：
    • 新建MAVEN_HOME：D:\maven3.8
    • Path添加%MAVEN_HOME%\bin
  4. 验证：mvn -v能看到版本信息即可
  5. 关键配置（conf/settings.xml）：
    • 本地仓库（避免占 C 盘）： 
      <localRepository>D:\maven-repo</localRepository>
    • 阿里云镜像（国内下载 Spring AI 依赖提速 10 倍）： 
      <mirrors><mirror><id>aliyun</id><name>阿里云公共仓库</name><url>https://maven.aliyun.com/repository/public</url><mirrorOf>central</mirrorOf></mirror>
</mirrors>

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 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>
  3. 等待 Maven 下载依赖（第一次可能需要 5-10 分钟，耐心等，别断网）

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 IDsecret-key: 你的AccessKey Secretchat: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、通义千问的代码完全一样
}
注意事项：
  • 本地模型性能依赖硬件：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: truerequests-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 响应速度

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

http://www.dtcms.com/a/519950.html

相关文章：

  • 容器适配器：Stack与Queue的底层奥秘
  • 2025年10月23日Github流行趋势
  • 上海外贸网站建设公司价格做兼职设计去哪个网站
  • 免费效果图网站wordpress分类目录导航
  • 【完整源码+数据集+部署教程】【运动的＆足球】足球比赛分析系统源码＆数据集全套：改进yolo11-RFAConv
  • YARN简介
  • PSO-Transformer-BiLSTM分类预测/故障诊断，优化参数为注意力机制头数、学习率、正则化系数、隐藏层单元，图很多，包括分类效果图，混淆矩阵图
  • AJAX 知识
  • 做淘宝推广开网站合适全球最大的设计网站
  • Java-157 MongoDB 存储引擎 WiredTiger vs InMemory：何时用、怎么配、如何验证 mongod.conf
  • 详细-vue3项目初始化配置流程
  • 电子科技网站太原seo排名
  • 销售记账-成本中心/成本会计分配
  • TensorFlow深度学习实战——链路预测
  • 广州网站建设公司品牌太和县建设局网站
  • 帝国网站的互动专栏怎么做做ppt兼职网站
  • SpringBoot-数据访问之JDBC
  • Linux操作系统-父进程的等待：一个关于回收与终结的故事
  • Adobe After Effects 2025(AE2025解锁版) 电影级特效
  • 云栖实录 | DataWorks 发布下一代 Data+AI 一体化平台，开启企业智能数据新时代
  • uv add openai 和 uv pip install openai 的区别
  • 安装了conda和uv如何创建一个项目？
  • 策略模式解决的核心问题是什么？
  • Jenkins远程命令执行漏洞复现：原理详解+环境搭建+渗透实践（CVE-2018-1000861 3种方法)
  • SQLite 数据类型
  • 一般建设网站大概需要多少钱一流的聊城做网站费用
  • 福永网站设计二级建造师最好的网站
  • 2025第二届中国物流枢纽发展大会影响力如何，给行业带来哪些新方向？
  • 高端制作网站公司seo优化在哪里学
  • 预警！流感季可能将提前！盈电智控物联网技术如何构筑智慧防疫新防线