手把手搭建 Spring AI 开发环境：依赖引入、版本选择、项目初始化
专栏导读本专栏为Spring AI 科普实战系列从框架认知、环境搭建、基础对话、流式输出、会话记忆、函数调用到 RAG 知识库全方位讲解 Spring 生态 AI 集成方案零基础 Java 开发者也可轻松上手。上一篇我们从原理和痛点层面搞懂了为什么要用 Spring AI。理论落地必须依赖实战想要玩转 Spring AI 所有智能能力第一步就是搭建一套稳定、规范、无坑的基础开发环境。很多新手初学 Spring AI 最容易踩坑的地方版本不匹配、依赖缺失、自动配置失效。本篇文章专门解决环境问题手把手带你完成版本选型、项目创建、依赖引入、配置编写、项目启动、接口测试。读完本篇你将拥有一个可以贯穿整个系列的通用 Spring AI 基础工程。一、前置环境与版本适配重点必看Spring AI 对版本要求比较严格版本不对直接启动报错这里直接给出生产通用稳定组合无脑抄即可。1. 基础环境要求JDK17 及以上Spring Boot3 强制要求构建工具Maven 3.8 / Gradle 7.5开发工具IDEA / Eclipse / VS Code 均可2. 稳定版本组合推荐本文及后续所有实战统一使用这套稳定版本兼容性最好、BUG 最少Spring Boot3.3.xSpring AI1.1.x 稳定版避坑提示不要强行使用最新的 Spring Boot 4.0、Spring AI 2.0 预览版新特性多、兼容问题多学习和落地优先稳定版。二、两种项目创建方式这里提供两种最常用的创建方式任选其一即可最终效果完全一致。方式一Spring Initializr 在线初始化推荐官方在线脚手架一键生成干净工程无需手动配置版本。访问官网start.spring.io参数配置ProjectMavenLanguageJavaSpring Boot Version3.3.x稳定版Java Version17包名、项目名自定义初始化完成后下载压缩包导入 IDEA 等待依赖加载完毕。方式二IDEA 本地直接创建打开 IDEA - New Project - 选择 Spring Initializr参数同上直接本地生成工程即可。三、引入 Spring AI 核心依赖MavenSpring AI 采用 版本统一管理 机制需要先在 pom.xml 中声明 Spring AI 版本再按需引入对应 Starter。完整可直接运行的 pom 核心配置如下propertiesmaven.compiler.source17/maven.compiler.sourcemaven.compiler.target17/maven.compiler.targetspring-ai.version1.1.4/spring-ai.version/properties!-- 统一版本管理 --dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement!-- 核心依赖 --dependencies!-- Spring Web 必备用于写接口测试 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI 核心基础包 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-core/artifactId/dependency!-- 测试依赖 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependencies依赖说明spring-ai-bom统一管理所有 Spring AI 子依赖版本避免版本冲突spring-ai-starter-coreSpring AI 核心基础能力包含 Prompt、ChatClient、Advisor 等顶层抽象spring-boot-starter-web用于开发 Web 接口方便后续接口测试四、全局配置文件说明Spring AI 所有模型密钥、超时时间、模型参数全部统一在 application.yml / application.properties 中配置。本次环境搭建无需配置任何 AI 密钥仅保证项目结构正常即可后续对接模型会逐一补充配置。初始默认空配置即可干净无干扰。五、项目结构预览标准规范这里先统一整套系列的项目结构后续所有实战代码全部遵循该规范com.ai.demo ├── config // AI 配置类 ├── controller // 接口层 ├──service// 业务层 ├── entity // 实体类 └── AiDemoApplication.java // 启动类六、环境校验编写第一个 AI 测试接口为了验证我们的环境是否搭建成功我们注入 Spring AI 核心的 ChatClient编写一个最简单的测试接口。1. 编写测试 Controllerpackage com.ai.demo.controller;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RestController;RestController public class AiTestController{// 注入 Spring AI 核心客户端 private final ChatClient chatClient;public AiTestController(ChatClient.Builder chatClientBuilder){this.chatClientchatClientBuilder.build();}GetMapping(/ai/test)public Stringtest(){returnSpring AI 环境搭建成功等待接入大模型能力...;}}2. 启动项目验证运行启动类观察控制台无报错、项目正常启动 即为环境搭建成功。浏览器访问http://localhost:8080/ai/test页面输出Spring AI 环境搭建成功等待接入大模型能力…七、新手常见环境报错与解决1. JDK 版本不匹配报错关键词class file has wrong version解决方案项目、模块、编译器全部统一设置为 JDK17。2. 依赖无法导入、报红解决方案刷新 Maven、检查网络、确认 spring-ai-bom 版本书写正确。3. 启动提示自动配置失效解决方案必须使用 Spring Boot3.x不能使用 Spring Boot2.xSpring AI 不兼容低版本。八、本篇总结本篇我们完成了 Spring AI 全套基础环境搭建确定了统一版本规范、统一项目结构、导入了核心依赖并通过接口验证了工程可用性。目前我们的项目已经具备 Spring AI 完整运行基础后续所有的对话问答、流式输出、RAG、函数调用、记忆会话全部基于当前工程迭代开发。下一篇Spring AI 实战快速接入通义千问、OpenAI实现基础对话问答我们将正式接入大模型实现第一个真正的 AI 智能问答功能
)
