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 必备环境

环境	版本要求	说明
JDK	21+	项目使用 Java 21
Maven	3.6+	用于依赖管理与构建
Ollama	最新版	用于本地运行大模型

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: 8123
  servlet:
    context-path: /api

即应用名 ai-agent，服务端口 8123 ，统一前缀 /api （所有接口为 /api/xxx）。

5.2 Spring AI Ollama 配置

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen3:4b
          temperature: 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.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.leo.aiagent.controller

knife4j:
  enable: true
  setting:
    language: zh_cn

• 文档与接口扫描包为 com.leo.aiagent.controller，与下文 Controller 包名一致。
• Knife4j 启用且使用中文界面。

---

六、启动类与包结构

启动类保持 Spring Initializr 默认即可，无需改代码：

package com.leo.aiagent;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class AiAgentApplication {

    public static void main(String[] args) {
        SpringApplication.run(AiAgentApplication.class, args);
    }
}

确保所有 Controller 位于 com.leo.aiagent.controller 或其子包下，以便被扫描与 Knife4j 扫描到。

---

七、健康检查接口

在 src/main/java/com/leo/aiagent/controller/ 下新建 HealthController.java：

package com.leo.aiagent.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/health")
public class HealthController {

    @GetMapping
    public String healthCheck() {
        return "ok";
    }
}

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

---

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

在 controller 包下新建 ChatController.java：

package com.leo.aiagent.controller;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/chat")
public class ChatController {
  private final ChatClient chatClient;

  public ChatController(ChatClient.Builder builder) {
    this.chatClient = builder.build();
  }

  @GetMapping
  public String chat(@RequestParam String q) {
    return chatClient.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 测试健康检查

curl http://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，点击「调试」即可在线发请求、查看响应。