从零搭建 Spring Boot 3 + 本地大模型 (Ollama) 的 AI 开发环境

[第一步：安装 AI 动力引擎 ------ Ollama](#第一步：安装 AI 动力引擎 —— Ollama)
[第二步：核心优化 ------ 将模型搬到 D 盘（避坑必看）](#第二步：核心优化 —— 将模型搬到 D 盘（避坑必看）)
第三步：运行你的第一个本地模型
[第四步：Java 后端集成（Spring Boot 3）](#第四步：Java 后端集成（Spring Boot 3）)
- [1. 引入 Maven 依赖](#1. 引入 Maven 依赖)
- [2. 配置 YAML 文件](#2. 配置 YAML 文件)
[第五步：编写测试 Controller](#第五步：编写测试 Controller)
第六步：联调测试
👌避坑指南

🚀 实验环境准备

操作系统： Windows 11

开发语言： Java 21+ (Spring Boot 3.x)

AI 引擎： Ollama

本地模型： Gemma3:4b (Google 开源轻量化模型)

集成框架： LangChain4j (Java 界的 LangChain)

第一步：安装 AI 动力引擎 ------ Ollama

下载：前往 Ollama 官网（https://ollama.com/）下载 Windows 安装包。
安装：运行 OllamaSetup.exe。
验证：安装完成后，在桌面右下角任务栏看到"小羊驼"图标，说明服务已启动。

第二步：核心优化 ------ 将模型搬到 D 盘（避坑必看）

为什么要改？默认路径在 C 盘，模型动辄几个 GB，很快会撑爆系统盘。

创建文件夹：在 D 盘创建你喜欢的路径，例如：D:\My_downloads\models。
设置环境变量：
右键"此电脑" -> 属性 -> 高级系统设置 -> 环境变量。
在用户变量中点击"新建"：
- 变量名：OLLAMA_MODELS
- 变量值：D:\My_downloads\models
彻底重启：
必须在右下角任务栏右键退出（Quit）Ollama。
重新打开 Ollama 软件。

第三步：运行你的第一个本地模型

打开终端：运行 CMD 或 PowerShell。

拉取并运行模型：

Shell 复制代码

# 这里以我已经下载好的 gemma3:4b 为例
ollama run gemma3:4b

常用命令速查：

ollama list：查看本地已有的模型。

ollama pull [模型名]：只下载不运行。

ollama rm [模型名]：删除模型。

第四步：Java 后端集成（Spring Boot 3）

这一步我们将 Java 程序与 Ollama 正式打通。

1. 引入 Maven 依赖

在项目的 pom.xml 中添加 LangChain4j 的官方 Starter：

xml 复制代码

<properties>
    <!-- 建议使用最新稳定版 -->
    <langchain4j.version>0.35.0</langchain4j.version>
</properties>

<dependencies>
    <!-- LangChain4j Spring Boot Starter 核心 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-spring-boot-starter</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>

    <!-- Ollama 适配器 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-ollama-spring-boot-starter</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
</dependencies>

2. 配置 YAML 文件

在 application.yml 中指定本地 Ollama 的地址和模型：

yml 复制代码

langchain4j:
  ollama:
    chat-model:
      # Ollama 默认监听 11434 端口
      base-url: http://localhost:11434
      # 必须与 ollama list 出来的名称完全一致
      model-name: gemma3:4b
      # 建议设置超时时间，因为 AI 推理较慢
      timeout: PT1M

第五步：编写测试 Controller

创建一个 Test 接口，验证链路是否通畅。

java 复制代码

@RestController
public class AiController {

    // Spring Boot 会根据配置文件自动注入这个 Bean
    private final ChatLanguageModel chatModel;

    public AiController(ChatLanguageModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/api/ai/simple-chat")
    public String chat(@RequestParam(value = "message", defaultValue = "你好") String message) {
        // 调用本地模型进行推理
        return chatModel.generate(message);
    }
}

第六步：联调测试

启动 Spring Boot 项目。
在浏览器或 Postman 访问：
http://localhost:8080/api/ai/simple-chat?message=帮我写一个Java冒泡排序
观察：浏览器可能需要转几秒钟（这是本地 CPU/GPU 在计算），随后你会看到模型生成的代码。

👌避坑指南

端口冲突：确保没有其他程序占用 11434 端口。
内存不足：如果运行 gemma3:4b 电脑风扇狂转、卡顿，可以尝试更轻量的 qwen2.5:1.5b。
版本兼容： Spring Boot 3 要求 Java 17 以上，建议直接上 Java 21，因为它对 AI 异步调用更友好。