Spring AI 实战：从0到1搭建第一个AI应用

当大语言模型的浪潮席卷全球我们 Java 开发者常常陷入一个尴尬的境地Python 似乎成了 AI 的“官方语言”而我们对 Spring 全家桶的深厚积累似乎暂时派不上用场。Spring AI 的出现彻底打破了这一困局。Spring AI 是 Spring 官方团队主导开发的开源项目它为 Java/Spring 生态系统提供了一个统一、模块化、企业级友好的 AI 应用开发框架。核心理念是AI 开发应遵循 Spring 哲学——POJO 编程、自动配置、可移植、可观测、可测试。1. 环境准备JDK 17Spring Boot 3.x 的硬性要求Maven 3.8AI 模型厂商百练阿里云百炼大模型平台国内访问友好Ollama本地运行环境适合离线场景Spring AI 支持 Spring Boot 3.4.x 和 3.5.x 版本2. 初始化 Spring Boot 工程访问 start.spring.io 使用 Spring Initializr 方式初始化 Spring Boot 工程。在新应用中选择您需要使用的 AI 模型等在这选用 Spring Boot 3.5.14 版本Spring AI 推荐使用 1.1.5 版本。完整 pom 如下projectxmlnshttp://maven.apache.org/POM/4.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsdmodelVersion4.0.0/modelVersion!-- 第一层Spring Boot 父 POM管理 Boot 生态 --parentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion3.5.14/versionrelativePath//parentartifactIdspring-ai-quickstart/artifactIdnamespring-ai-quickstart/namepropertiesproject.build.sourceEncodingUTF-8/project.build.sourceEncodingjava.version17/java.versionspring-ai.version1.1.5/spring-ai.version/properties!-- 第二层导入 Spring AI BOM管理 AI 生态 --dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement!-- 依赖 --dependencies!-- Spring Boot Web --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI Ollama 模型 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependency!-- Spring AI OpenAI协议 模型 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependency!-- Spring Boot Lombok --dependencygroupIdorg.projectlombok/groupIdartifactIdlombok/artifactIdoptionaltrue/optional/dependency!-- Spring Boot 测试 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependenciesbuildpluginsplugingroupIdorg.apache.maven.plugins/groupIdartifactIdmaven-compiler-plugin/artifactIdconfigurationannotationProcessorPathspathgroupIdorg.projectlombok/groupIdartifactIdlombok/artifactId/path/annotationProcessorPaths/configuration/pluginplugingroupIdorg.springframework.boot/groupIdartifactIdspring-boot-maven-plugin/artifactIdconfigurationexcludesexcludegroupIdorg.projectlombok/groupIdartifactIdlombok/artifactId/exclude/excludes/configuration/plugin/plugins/build/project2.1 构件仓库2.1.1 正式版 - 使用 Maven CentralSpring AI 1.0.0 及后续版本已在 Maven Central 仓库提供。构建文件只需启用 Maven Central 即可通常无需额外配置仓库:repositoriesrepositoryidcentral/idurlhttps://repo.maven.apache.org/maven2/url/repository/repositoriesMaven 构建默认包含 Maven Central不需要额外配置2.1.2 快照版 - 添加快照仓库如需使用开发版本如1.1.0-SNAPSHOT或1.0.0之前的里程碑版本需在构建文件中添加以下快照仓库:repositoriesrepositoryidspring-snapshots/idnameSpring Snapshots/nameurlhttps://repo.spring.io/snapshot/urlreleasesenabledfalse/enabled/releases/repositoryrepositorynameCentral Portal Snapshots/nameidcentral-portal-snapshots/idurlhttps://central.sonatype.com/repository/maven-snapshots//urlreleasesenabledfalse/enabled/releasessnapshotsenabledtrue/enabled/snapshots/repository/repositories需要注意的是使用 Maven 构建 Spring AI 快照时请检查镜像配置。若在 settings.xml 中配置了类似如下镜像mirroridmy-mirror/idmirrorOf*/mirrorOfurlhttps://my-company-repository.com/maven/url/mirror通配符*会将所有仓库请求重定向至该镜像导致无法访问 Spring 快照仓库。请修改 mirrorOf 配置排除 Spring 仓库mirroridmy-mirror/idmirrorOf*,!spring-snapshots,!central-portal-snapshots/mirrorOfurlhttps://my-company-repository.com/maven/url/mirror此配置允许 Maven 直接访问 Spring 快照仓库同时通过镜像获取其他依赖。2.2 Spring Boot 依赖管理Spring Boot 本身提供 BOMspring-boot-dependencies管理 Boot 生态通常由父 POM 管理parentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion3.5.14/versionrelativePath//parent2.3 Spring AI 依赖管理Spring AI 也提供 BOM 来管理 Spring AI 生态声明了 Spring AI 指定所有依赖的推荐版本dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion1.1.5/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement此 BOM 仅包含依赖管理不涉及插件声明或 Spring/Spring Boot 直接引用。可使用 Spring Boot 父 POM 或 Spring Boot BOM (spring-boot-dependencies) 管理 Spring Boot 版本。2.4 添加依赖添加 Spring Boot 和 Spring AI 等相关依赖dependencies!-- Spring Boot Web --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI Ollama 模型 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependency!-- Spring AI OpenAI协议 模型 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependency!-- Spring Boot Lombok --dependencygroupIdorg.projectlombok/groupIdartifactIdlombok/artifactIdoptionaltrue/optional/dependency!-- Spring Boot 测试 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependencies如果调用本地 Ollama 大模型则需要引入 spring-ai-starter-model-ollama 依赖如果调用 OpenAPI 兼容协议的大模型则需要引入 spring-ai-starter-model-openai 大模型。3. 配置文件在application.yml中配置阿里云百炼大模型配置或者本地 Ollama 配置server: port: 8888 spring: application: name: spring-ai-quickstart ai: openai: # 配置系统变量 api-key: ${DASHSCOPE_API_KEY} # url 后不要加 /v1 , spring ai 会自动添加 base-url: https://dashscope.aliyuncs.com/compatible-mode chat: options: model: qwen3.5-35b-a3b temperature: 0.7 ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5:7b temperature: 0.75 top-p: 0.9 max-tokens: 4096这里有三个值得注意的点防止端口冲突自定义新的端口8888。base-url 不要带/v1Spring AI 内部会自动拼接/v1/chat/completions。${DASHSCOPE_API_KEY}占位符Spring Boot 会自动从操作系统环境变量或 JVM 系统属性中解析这是管理密钥的最佳实践。安全提醒请勿将 API Key 硬编码在配置文件中推荐使用环境变量 DASHSCOPE_API_KEY 传入。4. 核心实现4.1 模型配置ChatClient 是 Spring AI 的核心抽象。无论底层是 OpenAI 协议还是 Ollama上层调用代码完全一致ConfigurationpublicclassChatConfig{// 本地 Ollama 大模型/*Bean public ChatClient localChatClient(OllamaChatModel chatModel) { return ChatClient.builder(chatModel) .build(); }*/// 远程 OpenAI 兼容协议大模型百练BeanpublicChatClientchatClient(OpenAiChatModelchatModel){returnChatClient.builder(chatModel).build();}}4.2 流式对话接口ChatController 流式对话接口Slf4jRestControllerRequestMapping(/api/v1/)publicclassChatController{AutowiredprivateChatClientchatClient;GetMapping(value/chat,producestext/plain;charsetUTF-8)publicFluxStringchatStream(RequestParam(valuemessage,defaultValue你是谁)Stringmessage){FluxStringresultchatClient.prompt().user(message).stream().content();log.info(chat: {},message);returnresult;}}代码非常简洁prompt()创建一个提示词构建器user(message)设置用户输入stream()要求模型以流式方式返回SSEcontent()从响应中提取纯文本流返回类型FluxString是 Reactor 的响应式流天然适合 SSE 场景。Spring Boot 会自动将其包装为 text/event-stream 格式输出到浏览器。5. 启动并测试5.1 设置百练模型api-key如果选用百练模型而非 Ollama 本地模型需要设置如下系统变量export DASHSCOPE_API_KEY你的api-key5.2 启动应用运行如下代码启动 Spring Boot 工程SpringBootApplicationpublicclassAIQuickstartApplication{publicstaticvoidmain(String[]args){SpringApplication.run(AIQuickstartApplication.class,args);}}或者使用如下命令启动应用mvn spring-boot:run5.3 测试浏览器直接访问http://localhost:8888/api/v1/chat?message请用三句话介绍Spring AI输出如下Spring AI 是一个专为 Java 开发者设计的开源框架旨在简化生成式人工智能与 Spring Boot 应用的集成。它通过提供统一的抽象层和 API屏蔽了不同大语言模型提供商的差异支持快速构建聊天机器人及检索增强生成RAG应用。依托 Spring 生态系统的成熟机制Spring AI 显著降低了开发门槛使企业能更高效地利用 AI 技术。源码spring-ai-quickstart