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。

安装后执行：

bash 复制代码

java -version

确认输出为 21.x。

2.3 安装 Ollama

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

bash 复制代码

ollama serve

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

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

bash 复制代码

ollama pull qwen3:4b

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

三、创建 Spring Boot 项目

3.1 使用 Spring Initializr 创建（推荐）

打开 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 下载 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（简化实体与日志）

xml 复制代码

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

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

4.2 Hutool 工具库

xml 复制代码

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

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

4.3 Knife4j（Swagger 文档）

xml 复制代码

<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

xml 复制代码

<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 里程碑仓库（按需）：

xml 复制代码

<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 应用名与服务端口

yaml 复制代码

spring:
  application:
    name: ai-agent

yaml 复制代码

server:
  port: 8123
  servlet:
    context-path: /api

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

5.2 Spring AI Ollama 配置

yaml 复制代码

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 配置

yaml 复制代码

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 默认即可，无需改代码：

java 复制代码

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：

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：

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'。
命令行：在项目根目录执行：

bash 复制代码

./mvnw spring-boot:run

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

9.3 测试健康检查

bash 复制代码

curl http://localhost:8123/api/health

应返回：ok。

9.4 测试对话接口

bash 复制代码

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

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

9.5 使用 Knife4j 调试

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