作者CSDN爱跑步的程序员本文手把手带你从零搭建一个基于 Spring Boot 3、Spring AI 与 Ollama 的本地 AI 对话服务包含环境准备、项目创建、依赖配置、接口开发与联调测试的完整步骤。一、项目简介本项目ai-agent是一个轻量级 AI 对话服务具备以下能力Spring Boot 3.5.10Java 21Spring AI对接Ollama在本地运行大模型如 qwen3:4b无需外网 API KeyKnife4j提供中文 Swagger 文档与在线调试Hutool工具库便于后续扩展提供健康检查与对话接口方便集成与测试阅读完本文你将掌握从零创建项目、配置 Ollama、编写对话接口、使用 Knife4j 调试的完整流程。二、环境准备2.1 必备环境环境版本要求说明JDK21项目使用 Java 21Maven3.6用于依赖管理与构建Ollama最新版用于本地运行大模型2.2 安装 JDK 21Windows从 Oracle JDK 或 Adoptium 下载安装并配置JAVA_HOME。macOSbrew install openjdk21并将JAVA_HOME指向该版本。Linux使用发行版包管理器安装openjdk-21-jdk。安装后执行java -version确认输出为 21.x。2.3 安装 Ollama打开 Ollama 官网 下载对应系统安装包。安装完成后在终端执行ollama serve保持该窗口运行默认监听http://localhost:11434。新开一个终端拉取本项目使用的模型例如 qwen3:4bollama pull qwen3:4b等待下载完成。如需其他模型可执行ollama list查看已安装ollama pull 模型名拉取新模型。三、创建 Spring Boot 项目3.1 使用 Spring Initializr 创建推荐打开 https://start.spring.io。按下面配置选择ProjectMavenLanguageJavaSpring Boot3.5.x或当前最新 3.xProject MetadataGroupcom.leoArtifactaiagentNameai-agentPackage namecom.leo.aiagentOptionsJava 21Dependencies先选Spring Web其余依赖稍后在pom.xml中手写便于理解每一行含义。点击Generate下载 zip解压到本地目录如ai-agent。3.2 使用 IDEA 创建File → New → Project选择Spring Initializr。SDK 选择21其他与上面一致Maven、Java、Group/Artifact/Name/Package。依赖先勾选Spring Web然后Create。在项目根目录得到与官网一致的 Maven 工程结构。四、添加依赖pom.xml在pom.xml的dependencies中保留spring-boot-starter-web并按下面顺序添加以下依赖。4.1 Lombok简化实体与日志dependencygroupIdorg.projectlombok/groupIdartifactIdlombok/artifactIdversion1.18.36/versionoptionaltrue/optional/dependency用于 getter/setter、构造等按需在实体或配置类上使用。4.2 Hutool 工具库dependencygroupIdcn.hutool/groupIdartifactIdhutool-all/artifactIdversion5.8.37/version/dependency便于后续做 HTTP、JSON、日期等工具封装。4.3 Knife4jSwagger 文档dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactIdversion4.4.0/version/dependency注意Spring Boot 3 使用 Jakarta 命名空间需使用jakarta版 Knife4j。4.4 Spring AI Ollama starterdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-ollama-spring-boot-starter/artifactIdversion1.0.0-M6/version/dependency用于自动配置与 Ollama 的 ChatClient无需手写 HTTP 调用。4.5 父 POM 与仓库如使用快照/里程碑若 Spring Initializr 已生成spring-boot-starter-parent只需在repositories中增加 Spring 里程碑仓库按需repositoriesrepositoryidspring-milestones/idnameSpring Milestones/nameurlhttps://repo.spring.io/milestone/urlsnapshotsenabledfalse/enabled/snapshots/repository/repositories如图所示。五、配置文件application.yml在src/main/resources/application.yml中做如下配置无则新建。5.1 应用名与服务端口spring:application:name:ai-agentserver:port:8123servlet:context-path:/api即应用名ai-agent服务端口8123统一前缀/api所有接口为/api/xxx。5.2 Spring AI Ollama 配置spring:ai:ollama:base-url:http://localhost:11434chat:options:model:qwen3:4btemperature:0.2base-url与本地ollama serve地址一致默认http://localhost:11434。model与ollama pull qwen3:4b的模型名一致可改为你本机已有模型。temperature控制随机性0.2 偏保守、稳定。5.3 Knife4j / SpringDoc 配置springdoc:swagger-ui:path:/swagger-ui.htmltags-sorter:alphaoperations-sorter:alphaapi-docs:path:/v3/api-docsgroup-configs:-group:defaultpaths-to-match:/**packages-to-scan:com.leo.aiagent.controllerknife4j:enable:truesetting:language:zh_cn文档与接口扫描包为com.leo.aiagent.controller与下文 Controller 包名一致。Knife4j 启用且使用中文界面。六、启动类与包结构启动类保持 Spring Initializr 默认即可无需改代码packagecom.leo.aiagent;importorg.springframework.boot.SpringApplication;importorg.springframework.boot.autoconfigure.SpringBootApplication;SpringBootApplicationpublicclassAiAgentApplication{publicstaticvoidmain(String[]args){SpringApplication.run(AiAgentApplication.class,args);}}确保所有 Controller 位于com.leo.aiagent.controller或其子包下以便被扫描与 Knife4j 扫描到。七、健康检查接口在src/main/java/com/leo/aiagent/controller/下新建HealthController.javapackagecom.leo.aiagent.controller;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;RestControllerRequestMapping(/health)publicclassHealthController{GetMappingpublicStringhealthCheck(){returnok;}}实际路径GET /api/health因 context-path 为/api。用于运维或网关做健康探测。八、对话接口Spring AI Ollama在controller包下新建ChatController.javapackagecom.leo.aiagent.controller;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;RestControllerRequestMapping(/chat)publicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.Builderbuilder){this.chatClientbuilder.build();}GetMappingpublicStringchat(RequestParamStringq){returnchatClient.prompt().user(q).call().content();}}要点ChatClient.Builder由 Spring AI Ollama 自动配置并注入无需手写 Bean。prompt().user(q).call().content()把用户问题q发给 Ollama并返回模型回复的文本。接口路径GET /api/chat?q你的问题。九、运行与验证9.1 确认 Ollama 已运行终端中ollama serve保持运行。已执行ollama pull qwen3:4b或你配置的模型。9.2 启动 Spring BootIDEA右键AiAgentApplication→Run ‘AiAgentApplication’。命令行在项目根目录执行./mvnw spring-boot:runWindows 使用mvnw.cmd。看到类似 “Started AiAgentApplication” 即启动成功。9.3 测试健康检查curlhttp://localhost:8123/api/health应返回ok。9.4 测试对话接口http://localhost:8123/api/chat?q你好请用一句话介绍你自己应返回模型的一段文字回复可能稍等几秒。9.5 使用 Knife4j 调试浏览器打开http://localhost:8123/api/doc.htmlKnife4j 增强文档页。若 404可尝试http://localhost:8123/api/swagger-ui.html。在文档中找到「对话接口」或「chat」输入参数q点击「调试」即可在线发请求、查看响应。