SpringBoot集成SpringAI与Ollama本地大模型

作者：CSDN爱跑步的程序员
本文手把手带你从零搭建一个基于 Spring Boot 3、Spring AI 与 Ollama 的本地 AI 对话服务，包含环境准备、项目创建、依赖配置、接口开发与联调测试的完整步骤。

一、项目简介

本项目ai-agent是一个轻量级 AI 对话服务，具备以下能力：

• Spring Boot 3.5.10+Java 21
• Spring AI对接Ollama，在本地运行大模型（如 qwen3:4b），无需外网 API Key
• Knife4j提供中文 Swagger 文档与在线调试
• Hutool工具库，便于后续扩展
• 提供健康检查与对话接口，方便集成与测试

阅读完本文，你将掌握：从零创建项目、配置 Ollama、编写对话接口、使用 Knife4j 调试的完整流程。

二、环境准备

2.1 必备环境

2.2 安装 JDK 21

• Windows：从 Oracle JDK 或 Adoptium 下载安装，并配置JAVA_HOME。
• macOS：brew install openjdk@21，并将JAVA_HOME指向该版本。
• Linux：使用发行版包管理器安装openjdk-21-jdk。

安装后执行：

java -version

确认输出为 21.x。

2.3 安装 Ollama

1. 打开 Ollama 官网 下载对应系统安装包。
2. 安装完成后，在终端执行：

ollama serve

保持该窗口运行（默认监听http://localhost:11434）。

3. 新开一个终端，拉取本项目使用的模型（例如 qwen3:4b）：

ollama pull qwen3:4b

等待下载完成。如需其他模型，可执行ollama list查看已安装，ollama pull <模型名>拉取新模型。

三、创建 Spring Boot 项目

3.1 使用 Spring Initializr 创建（推荐）

1. 打开 https://start.spring.io。
2. 按下面配置选择：
   • Project：Maven
   • Language：Java
   • Spring Boot：3.5.x（或当前最新 3.x）
   • Project Metadata：
     • Group：com.leo
     • Artifact：aiagent
     • Name：ai-agent
     • Package name：com.leo.aiagent
   • Options：Java 21
   • Dependencies：先选Spring Web，其余依赖稍后在pom.xml中手写，便于理解每一行含义。
3. 点击Generate下载 zip，解压到本地目录（如ai-agent）。

3.2 使用 IDEA 创建

1. File → New → Project，选择Spring Initializr。
2. SDK 选择21，其他与上面一致（Maven、Java、Group/Artifact/Name/Package）。
3. 依赖先勾选Spring Web，然后Create。
4. 在项目根目录得到与官网一致的 Maven 工程结构。

四、添加依赖（pom.xml）

在pom.xml的<dependencies>中保留spring-boot-starter-web，并按下面顺序添加以下依赖。

4.1 Lombok（简化实体与日志）

<dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.36</version><optional>true</optional></dependency>

用于 getter/setter、构造等，按需在实体或配置类上使用。

4.2 Hutool 工具库

<dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>5.8.37</version></dependency>

便于后续做 HTTP、JSON、日期等工具封装。

4.3 Knife4j（Swagger 文档）

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

注意：Spring Boot 3 使用 Jakarta 命名空间，需使用jakarta版 Knife4j。

4.4 Spring AI Ollama starter

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-ollama-spring-boot-starter</artifactId><version>1.0.0-M6</version></dependency>

用于自动配置与 Ollama 的 ChatClient，无需手写 HTTP 调用。

4.5 父 POM 与仓库（如使用快照/里程碑）

若 Spring Initializr 已生成spring-boot-starter-parent，只需在<repositories>中增加 Spring 里程碑仓库（按需）：

<repositories><repository><id>spring-milestones</id><name>Spring Milestones</name><url>https://repo.spring.io/milestone</url><snapshots><enabled>false</enabled></snapshots></repository></repositories>

如图所示。

五、配置文件（application.yml）

在src/main/resources/application.yml中做如下配置（无则新建）。

5.1 应用名与服务端口

spring:application:name:ai-agent

server: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.2

• base-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:'default'paths-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.java：

packagecom.leo.aiagent.controller;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RestController;@RestController@RequestMapping("/health")publicclassHealthController{@GetMappingpublicStringhealthCheck(){return"ok";}}

• 实际路径：GET /api/health（因 context-path 为/api）。
• 用于运维或网关做健康探测。

八、对话接口（Spring AI + Ollama）

在controller包下新建ChatController.java：

packagecom.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;@RestController@RequestMapping("/chat")publicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.Builderbuilder){this.chatClient=builder.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 Boot

• IDEA：右键AiAgentApplication→Run ‘AiAgentApplication’。
• 命令行：在项目根目录执行：

./mvnw spring-boot:run

Windows 使用mvnw.cmd。看到类似 “Started AiAgentApplication” 即启动成功。

9.3 测试健康检查

curlhttp://localhost:8123/api/health

应返回：ok。

9.4 测试对话接口

http://localhost:8123/api/chat?q=你好，请用一句话介绍你自己

应返回模型的一段文字回复（可能稍等几秒）。

9.5 使用 Knife4j 调试

1. 浏览器打开：http://localhost:8123/api/doc.html（Knife4j 增强文档页）。
2. 若 404，可尝试：http://localhost:8123/api/swagger-ui.html。
3. 在文档中找到「对话接口」或「chat」，输入参数q，点击「调试」即可在线发请求、查看响应。