SpringBoot 整合 Ollama + 本地 DeepSeek 模型

小王不爱笑1322026-02-05 15:06

一、前置准备：Ollama+DeepSeek 模型本地部署（验证版）

严格按以下步骤操作，每一步都做验证，避免后续 SpringBoot 连接失败，以 Windows 为例（Linux/Mac 按你提供的命令执行即可）：

1. 安装 Ollama 并验证服务

  1. 官网下载：Ollama 官方下载，运行安装包完成安装（默认自动注册系统服务，开机自启）；

  2. 验证服务启动：打开命令提示符（CMD） ，执行 netstat -an | findstr :11434，若出现类似以下输出，说明端口监听成功（服务正常）：

    plaintext

    复制代码 
    TCP    0.0.0.0:11434          0.0.0.0:0              LISTENING
TCP    [::]:11434             [::]:0                 LISTENING

  3. 接口验证：执行 curl http://localhost:11434/api/tags（Windows 需提前安装 curl，或用 Postman 访问该地址），返回 JSON 格式的模型列表（初始为空，拉取模型后会有数据），说明 Ollama 接口正常。

2. 拉取 DeepSeek 模型并验证

  1. 拉取推荐模型（7B，平衡性能和资源）：CMD 执行 ollama pull deepseek-r1:7b，等待拉取完成（约 3.8GB，根据网络速度而定，请勿中断）；

  2. 验证模型：执行 ollama list，若输出以下内容，说明模型拉取成功并已部署：

    plaintext

    复制代码 
    NAME            ID              SIZE    MODIFIED
deepseek-r1:7b  8f9b79a4a9b5    3.8 GB  刚刚

  3. 本地测试模型（关键）：CMD 执行 ollama run deepseek-r1:7b，进入对话模式，输入你好，若能正常返回响应，说明模型 + Ollama 服务完全可用，可进入 SpringBoot 整合环节。

3. 硬件检查（避免响应过慢 / 启动失败）

  • deepseek-r1:1.5b：内存≥4GB，纯 CPU 可运行（速度一般）；
  • deepseek-r1:7b：内存≥8GB，有 2GB 以上独立 GPU 更佳（纯 CPU 会稍慢，可正常使用）；
  • deepseek-r1:33b：内存≥16GB，必须搭配 8GB 以上 GPU，否则无法启动。

二、SpringBoot 项目整合核心配置（完整版）

基于你之前的 LangChain4j+SpringBoot 项目，仅需替换依赖 + 修改配置 + 注入对应模型，无需大幅调整代码结构，完全兼容原有项目。

步骤 1：pom.xml 引入 Ollama Starter 依赖（指定版本，避免冲突）

移除原有 OpenAI 相关依赖（若不需要同时使用），引入 Ollama 的 SpringBoot Starter，指定与你项目匹配的版本（如 1.0.0-beta3，与之前 LangChain4j 版本一致）：

xml

复制代码 
<!-- 核心：Ollama SpringBoot Starter（自动配置，无需手动写配置类） -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-ollama-spring-boot-starter</artifactId>
    <version>1.0.0-beta3</version> <!-- 与项目中LangChain4j版本统一 -->
</dependency>

<!-- 保留SpringBoot测试依赖（必须，包含JUnit5） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

注意：若需同时使用 OpenAI 和 Ollama，可同时保留两个 Starter 依赖，配置文件分别配置即可，Spring 会自动创建不同的 Bean 实例。

步骤 2：application.properties 配置 Ollama（精准无换行）

删除原有 OpenAI 的配置，添加 Ollama 专属配置，注意配置项无换行、前缀正确 （LangChain4j 通过前缀识别 Ollama 配置），放在src/main/resources/application.properties中：

properties

复制代码 
# ========== Ollama 本地服务核心配置 ==========
# Ollama默认服务地址（固定，无需修改，除非手动改了Ollama端口）
langchain4j.ollama.chat-model.base-url=http://localhost:11434
# 本地部署的DeepSeek模型名称（与ollama list查询的NAME完全一致，大小写敏感）
langchain4j.ollama.chat-model.model-name=deepseek-r1:7b
# 启用请求/响应日志（调试用，正式环境可关闭）
langchain4j.ollama.chat-model.log-requests=true
langchain4j.ollama.chat-model.log-responses=true

# ========== 日志配置（可选，方便查看调用细节） ==========
logging.level.root=info
logging.level.dev.langchain4j=debug # 单独打印LangChain4j调用日志，精准排查问题

关键：model-name必须与ollama list的结果完全一致，多一个空格、大小写错误都会导致模型找不到。

步骤 3：编写测试类（注入 OllamaChatModel，符合 SpringBoot 测试规范）

在原有测试类com.qcby.LLMTest中添加 Ollama 测试方法，必须保留 @SpringBootTest 注解（核心，加载 Spring 容器才能实现依赖注入），代码如下（可直接替换原有测试类）：

java

运行

复制代码 
package com.qcby;

import dev.langchain4j.model.ollama.OllamaChatModel;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

/**
 * SpringBoot整合Ollama+本地DeepSeek模型测试类
 * 核心：@SpringBootTest 激活Spring测试容器，实现OllamaChatModel自动注入
 */
@SpringBootTest // 缺一不可，关联SpringBoot启动类，加载自动配置
public class LLMTest {

    // 自动注入Ollama Starter创建的Bean（无需手动new，Starter自动配置）
    @Autowired
    private OllamaChatModel ollamaChatModel;

    /**
     * 测试本地DeepSeek模型基础对话
     */
    @Test
    public void testLocalDeepSeek() {
        System.out.println("开始调用本地DeepSeek模型...");
        // 向本地模型提问
        String answer = ollamaChatModel.chat("你好，介绍一下你自己");
        // 输出响应结果
        System.out.println("===================== 模型响应 =====================");
        System.out.println(answer);
        System.out.println("====================================================");
    }

    /**
     * 测试多场景调用（推理+多轮对话，验证模型能力）
     */
    @Test
    public void testDeepSeekMultiScene() {
        // 1. 基础计算（推理能力）
        String answer1 = ollamaChatModel.chat("1+1等于多少？用中文回答");
        System.out.println("测试1-推理计算：" + answer1);

        // 2. 概念解释（知识能力）
        String answer2 = ollamaChatModel.chat("什么是人工智能？简单解释");
        System.out.println("测试2-概念解释：" + answer2);

        // 3. 多轮对话（上下文关联，Ollama默认支持简单上下文）
        String answer3 = ollamaChatModel.chat("它的核心技术有哪些？");
        System.out.println("测试3-多轮对话：" + answer3);
    }
}

三、关键前置条件（缺一不可，避坑核心）

整合前必须确保3 个核心条件满足 ，否则会出现注入失败、服务连接超时、模型找不到等问题，这是 90% 的整合失败原因：

1. SpringBoot 启动类存在且注解正确

项目中必须有@SpringBootApplication标注的启动类（如LangChain4jApplication），放在com.qcby包下，代码如下：

java

运行

复制代码 
package com.qcby;

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

// 激活自动配置，让Ollama Starter创建OllamaChatModel实例
@SpringBootApplication
public class LangChain4jApplication {
    public static void main(String[] args) {
        SpringApplication.run(LangChain4jApplication.class, args);
    }
}

缺失该类 / 注解 → Spring 容器无法创建 OllamaChatModel → 注入时报NoSuchBeanDefinitionException。

2. Ollama 服务始终运行（端口 11434 监听）

测试 / 运行 SpringBoot 项目时，Ollama 服务必须处于启动状态：

  • 若服务意外停止：Windows 可在「服务」中找到「Ollama Service」，右键「启动」；
  • 端口被占用：执行 netstat -an | findstr :11434 查看占用进程，关闭后重启 Ollama 服务。

3. 目录 + 包名规范（解决 ClassNotFoundException）

测试类LLMTest必须放在 src/test/java/com/qcby/ 下，与包名com.qcby完全对应，编译后target/test-classes/com/qcby/下能看到LLMTest.class文件。

四、运行测试类（正确操作步骤）

  1. 重建项目 ：IDEA 顶部菜单栏 Build → Rebuild Project，清理旧编译文件，确保所有配置和代码生效；
  2. 启动 Ollama 服务 ：确认 11434 端口监听正常（执行netstat -an | findstr :11434验证）；
  3. 运行测试方法 ：右键testLocalDeepSeek方法 → Run 'testLocalDeepSeek()'，或右键测试类运行所有方法；
  4. 查看结果 ：控制台会输出：
    • DEBUG 级别的请求 / 响应日志（LangChain4j 调用 Ollama 的细节）；
    • 本地 DeepSeek 模型的响应内容（如自我介绍、问题答案）。

运行成功的核心日志示例

plaintext

复制代码 
开始调用本地DeepSeek模型...
2026-02-04 20:00:00.000 DEBUG 1234 --- [main] dev.langchain4j.ollama.OllamaChatModel   : Sending request to Ollama: ...
2026-02-04 20:00:02.123 DEBUG 1234 --- [main] dev.langchain4j.ollama.OllamaChatModel   : Received response from Ollama: ...
===================== 模型响应 =====================
你好！我是由DeepSeek团队开发的大语言模型DeepSeek-R1，基于深度学习技术训练而成，能够为你提供信息咨询、问题解答、内容创作等多种服务...
====================================================
Process finished with exit code 0

五、常见问题解决方案（整合高频坑）

问题 1：注入失败 → NoSuchBeanDefinitionException: No qualifying bean of type 'OllamaChatModel'

  • 原因：① 缺少 Ollama Starter 依赖；② 无@SpringBootApplication启动类；③ 测试类无@SpringBootTest注解；
  • 解决：检查 pom.xml 依赖是否引入、启动类注解是否正确、测试类添加@SpringBootTest。

问题 2：连接失败 → ConnectException: Connection refused: connect

  • 原因：① Ollama 服务未启动；② 11434 端口被占用；③ 配置文件base-url写错（如多写端口、拼写错误）；
  • 解决：启动 Ollama 服务、释放 11434 端口、确认base-url=http://localhost:11434无错误。

问题 3：模型找不到 → OllamaApiException: model 'deepseek-r1:7B' not found

  • 原因：① 配置文件model-name与ollama list结果不一致（大小写、冒号、后缀错误）；② 未拉取模型；
  • 解决：执行ollama list确认模型名称，严格复制到配置文件（如deepseek-r1:7b，小写 b），未拉取则重新执行ollama pull deepseek-r1:7b。

问题 4：模型响应极慢（纯 CPU 运行）

  • 原因：硬件配置不足，7B 模型在纯 CPU 上运行会占用大量内存，计算速度慢；
  • 解决：① 切换更小的模型deepseek-r1:1.5b（执行ollama pull deepseek-r1:1.5b，修改配置文件model-name）；② 关闭其他占用内存的程序；③ 搭配 GPU（安装对应显卡驱动，Ollama 会自动调用 GPU）。

问题 5：测试类运行报错 → ClassNotFoundException: com.qcby.LLMTest

  • 原因：包名与目录结构不匹配，编译后无.class文件；
  • 解决：确保测试类放在src/test/java/com/qcby/下，包名是com.qcby，执行Rebuild Project重新编译。

六、核心优势与扩展使用

1. 本地部署核心优势（对比云端 API）

  • 🔒 数据隐私：所有对话数据在本地处理，无需上传至第三方服务器，适合企业内部、敏感数据场景；
  • 💰 零成本：无需 API 调用费用，一次性拉取模型，长期免费使用；
  • 📶 离线可用：无网络环境下，只要 Ollama 服务启动，模型即可正常调用；
  • ⚙️ 灵活定制：可通过 Ollama 命令调整模型参数（如温度、最大令牌数），适配业务需求。

2. 扩展：配置更多 Ollama 参数（优化模型调用）

在application.properties中添加以下配置，可优化模型响应速度、上下文能力等：

properties

复制代码 
# 设置请求超时时间（避免模型响应慢导致超时，单位：毫秒）
langchain4j.ollama.chat-model.timeout=30000
# 设置温度（0~2，值越高结果越随机，越低越精准，默认0.7）
langchain4j.ollama.chat-model.temperature=0.5
# 设置最大令牌数（控制响应内容长度，默认无限制）
langchain4j.ollama.chat-model.max-tokens=2048
# 开启流式响应（适合前端实时展示结果，如打字机效果）
langchain4j.ollama.chat-model.streaming=true

3. 扩展：业务代码中调用（非测试类）

在 SpringBoot 的 Service/Controller 中直接注入OllamaChatModel，即可在业务逻辑中调用本地模型，示例：

java

运行

复制代码 
package com.qcby.service;

import dev.langchain4j.model.ollama.OllamaChatModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class AIService {

    @Autowired
    private OllamaChatModel ollamaChatModel;

    /**
     * 业务方法：调用本地DeepSeek模型获取答案
     */
    public String getAIAnswer(String question) {
        // 调用模型
        return ollamaChatModel.chat(question);
    }
}

七、总结

SpringBoot 整合 Ollama + 本地 DeepSeek 模型的核心是 **「Ollama Starter 自动配置」+「本地服务正确部署」**，整体流程可概括为 3 步：

  1. 本地部署 Ollama+DeepSeek 模型，验证服务和模型可用；
  2. SpringBoot 项目引入 Ollama Starter 依赖，配置base-url和model-name；
  3. 注入OllamaChatModel，通过chat()方法实现本地模型调用。
相关推荐
毕设源码-钟学长2 小时前
【开题答辩全过程】以 高校宿舍分配系统设计与实现为例，包含答辩的问题和答案
java
何中应2 小时前
IDEA 中让 Git 忽略 .idea 目录
java·git·intellij-idea
無森~2 小时前
HBase优化面试题
java·面试·hbase
PPPPickup2 小时前
easymall---管理后端商品属性管理
java
人道领域2 小时前
SSM框架从入门到入土（SpringFrameWork）
java·spring boot·tomcat
源力祁老师2 小时前
深入解析 Odoo 中 default_get 方法的功能
java·服务器·前端
团子的二进制世界2 小时前
Sentinel-服务保护（限流、熔断降级）
java·开发语言·sentinel·异常处理
NWU_白杨2 小时前
多线程安全与通信问题
java
sheji34162 小时前
【开题答辩全过程】以 工业车辆维修APP设计与实现为例，包含答辩的问题和答案
java
热门推荐
01GitHub 镜像站点02Vue-skills的中文文档03一文了解国产算子编程语言 TileLang，TileLang 对国产开源生态的影响与启示04Claude Code Skills 实用使用手册05让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南06UV安装并设置国内源07Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services08在Trae中使用Pencil MCP09OpenClaw部署与配置教程：在Mac mini上接入国产大模型与飞书10OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)