03 · 环境搭建与第一个项目 学完能做什么从零建好一个 Spring Boot Spring AI 项目正确管理版本、配好模型密钥为下一章跑通对话做好准备。⏱️ 预计耗时40 分钟含动手 依赖前置第 01、02 章 难度一句话引spring-ai-bom统一版本 → 加一个模型 starter → 在application.yml填密钥环境就绪。1. 前提清单JDK17Spring Boot 3.x 硬性要求Maven 或 Gradle一个模型的 API Key本章以 OpenAI 为例没有海外 Key 可用「通义千问」或本地 Ollama见第 6 节2. 用 start.spring.io 建项目最快方式去 start.spring.io 选 Spring Boot 3.x JDK 17勾选OpenAIstarter。或手动加依赖见下。3. 关键一步用 BOM 统一版本⚠️ 这是新手最容易翻车的地方。务必用spring-ai-bom管理版本各 starter 就不用单独写版本号也避免版本打架。Mavenpom.xmlpropertiesjava.version17/java.versionspring-ai.version1.0.0/spring-ai.version/propertiesdependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependencies!-- 模型 starter注意 1.0 后的命名是 spring-ai-starter-model-xxx --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId!-- 不写 version由 BOM 统一管理 --/dependency/dependenciesGradlebuild.gradle等价写法dependencyManagement{imports{mavenBomorg.springframework.ai:spring-ai-bom:1.0.0}}dependencies{implementationorg.springframework.ai:spring-ai-starter-model-openai} 遇到「类找不到 / 包名对不上」的报错第一件事就是回来核对这里的spring-ai.version。详见附录414. 配置密钥与模型src/main/resources/application.ymlspring:ai:openai:api-key:${OPENAI_API_KEY}# 从环境变量读别硬编码进代码chat:options:model:gpt-4o-mini# 便宜好用练手够了temperature:0.7embedding:options:model:text-embedding-3-small 安全纪律API Key 绝不写进代码或提交到 Git。用环境变量 / 配置中心 / K8s Secret。生产实践见第 39 章。设置环境变量Windows PowerShell$env:OPENAI_API_KEY sk-你的key5. 自动配置带来了什么加了 starter 填了配置后Spring AI 的自动配置会帮你把ChatModel、ChatClient.Builder、EmbeddingModel等 Bean 准备好直接注入即可RestControllerclassPingController{privatefinalChatClientchatClient;// ChatClient.Builder 由自动配置提供构造时 build 出 ChatClientPingController(ChatClient.Builderbuilder){this.chatClientbuilder.build();}GetMapping(/ping-ai)Stringping(){returnchatClient.prompt().user(只回复两个字你好).call().content();}}启动后访问/ping-ai能返回模型回答环境就算通了完整讲解在下一章。6. 没有 OpenAI Key 怎么办方案 A国内模型通义千问——换 starter 与配置前缀即可dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-dashscope/artifactId/dependency方案 B本地跑Ollama免费、离线、适合学习dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependencyspring:ai:ollama:base-url:http://localhost:11434chat:options:model:qwen2.5# 先 ollama pull qwen2.5好消息因为都实现了同一套ChatModel/EmbeddingModel抽象换模型只改依赖和配置业务代码几乎不动第 23 章专讲多模型切换。7. 常见启动报错速排现象多半原因启动报ChatModelbean 找不到没加模型 starter或没配 api-key401 UnauthorizedKey 错 / 没设环境变量 / 没充值额度类/包名对不上版本不一致核对spring-ai-bom版本连接超时网络到不了模型服务海外模型需代理8. 一句话总结搭环境三步走BOM 锁版本 → 加模型 starter → yml 配密钥自动配置会把ChatClient等 Bean 备好注入即用换模型只改配置。➡️ 下一章04-第一个ChatClient对话.md真正跑通第一次大模型调用掌握 call 与 stream。