/>

一、项目简介

本项目ai-agent是一个轻量级

对话服务，具备以下能力：

• Spring

  Boot

  3.5.10+Java

  21

• Spring

  AI对接Ollama，在本地运行大模型（如

  API

  Key

• Knife4j提供中文

  Swagger

  文档与在线调试

• Hutool工具库，便于后续扩展
• 提供健康检查与对话接口，方便集成与测试

阅读完本文，你将掌握：从零创建项目、配置

Ollama、编写对话接口、使用

必备环境

2.2

JDK

21

• Windows：从

  Oracle

  下载安装，并配置JAVA_HOME。

• macOS：brew

  install

  openjdk@21，并将JAVA_HOME指向该版本。

• Linux：使用发行版包管理器安装openjdk-21-jdk。

安装后执行：

java
Ollama
下载对应系统安装包。
安装完成后，在终端执行：
ollama
serve
保持该窗口运行（默认监听http://localhost:11434）。
start="3">
新开一个终端，拉取本项目使用的模型（例如
qwen3:4b）：
ollama
pull
qwen3:4b
等待下载完成。
如需其他模型，可执行ollama
list查看已安装，ollama
pull
创建（推荐）
打开
https://start.spring.io。
按下面配置选择：
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中手写，便于理解每一行含义。
点击Generate下载
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>
便于后续做
文档）
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>
注意：Spring
Boot
命名空间，需使用jakarta版
Spring
starter
<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-ollama-spring-boot-starter</artifactId><version>1.0.0-M6</version></dependency>
用于自动配置与
Ollama
与仓库（如使用快照/里程碑）
若
Spring
已生成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
配置
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
Knife4j
配置
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
默认即可，无需改代码：
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
context-path
为/api）。
用于运维或网关做健康探测。
+
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
Bean。
prompt().user(q).call().content()：把用户问题q发给
Ollama，并返回模型回复的文本。
接口路径：GET
/api/chat?q=你的问题。
Ollama
已运行
终端中ollama
serve保持运行。
已执行ollama
pull
qwen3:4b（或你配置的模型）。
9.2
Spring
Boot
IDEA：右键AiAgentApplication→Run
‘AiAgentApplication’。
命令行：在项目根目录执行：
./mvnw
spring-boot:run
Windows
“Started
测试健康检查
curlhttp://localhost:8123/api/health
应返回：ok。
/>
测试对话接口
http://localhost:8123/api/chat?q=你好，请用一句话介绍你自己
应返回模型的一段文字回复（可能稍等几秒）。
/>
调试
浏览器打开：http://localhost:8123/api/doc.html（Knife4j
404，可尝试：http://localhost:8123/api/swagger-ui.html。
在文档中找到「对话接口」或「chat」，输入参数q，点击「调试」即可在线发请求、查看响应。
/>
/>