Spring AI + Ollama：零成本本地运行大模型实战

引言：从付费API到免费本地推理

Spring AI 为 Java 开发者打开了接入大语言模型的大门，但与 OpenAI 等云端服务集成时，API 调用费用是一个绑不开的话题。有没有一种方式，既能享受 Spring AI 的优雅抽象，又完全不花一分钱？答案就是 Ollama——一个可以在本地机器上运行 LLM 的轻量级工具。

本文基于一位海外开发者的实战演示，详细拆解如何将 Spring AI 与 Ollama 集成，在本地跑起 Llama、Mistral、Gemma 等开源大模型，并且几乎不需要修改任何业务代码。

什么是 Ollama？

Ollama 是一个轻量级的本地大模型运行工具，你可以把它理解为一个本地 AI 引擎。它的核心特点包括：

完全离线运行：模型下载到本地后，无需联网即可推理
支持主流开源模型：Llama、Mistral、Gemma 等热门模型均可一键拉取
暴露标准 HTTP API：模型启动后会在 localhost:11434 上提供 REST 接口，天然适合与 Spring AI 等框架对接
零成本：没有 token 计费，没有 API Key，想跑多少跑多少

Ollama 的出现是本地大模型推理工具链成熟的一个缩影。在此之前，开发者要在本地运行 LLM 通常需要手动配置 Python 环境、安装 llama.cpp 或 vLLM 等推理引擎、处理模型量化格式（如 GGUF、GPTQ）等繁琐步骤。Ollama 将这些底层复杂性封装起来，提供了类似 Docker 的使用体验——用 ollama pull 拉取模型，用 ollama run 启动推理，极大降低了门槛。其底层实际上基于 llama.cpp 构建，支持 CPU 和 GPU（CUDA/Metal）混合推理，并通过模型量化技术（通常为 4-bit 量化）将数十 GB 的原始模型压缩到几 GB，使得消费级硬件也能运行。

Ollama 模型列表页面

在 Ollama 官网（ollama.com）的左侧 Models 区域，可以浏览所有支持本地运行的模型。本次演示选用的是 gemma:2b，这是一个体积较小、推理速度较快的变体，非常适合入门体验。

Gemma 是 Google DeepMind 发布的开源大语言模型系列，2B 表示模型拥有约 20 亿个参数。在大模型领域，参数量是衡量模型能力的重要指标之一：GPT-3 有 1750 亿参数，Llama 3 的旗舰版本有 700 亿参数，而 2B 属于超轻量级。参数越少意味着推理速度越快、硬件要求越低，但在复杂推理、长文本理解和多步逻辑等任务上的表现会相应下降。2B 模型通常适合简单问答、文本摘要、代码补全等轻量任务，是本地开发调试的理想选择。Mistral 7B 和 Llama 3.2 等稍大的模型则在能力和资源消耗之间提供了更好的平衡。

本地环境搭建

安装与验证

安装 Ollama 后，可以通过以下命令验证：

# 查看版本
ollama --version

# 查看已下载的模型
ollama list

ollama list 会列出所有已下载到本地的模型，例如 gemma、llama3.2 等。

启动模型

运行模型只需一行命令：

ollama run gemma:2b

如果模型尚未下载，Ollama 会自动拉取；如果已经下载过，则直接启动。启动后即可在终端中与模型交互。

在终端中与 Gemma 模型交互

如上图所示，当被问到关于 Spring Boot 的问题时，Gemma 模型给出了关于开源免费、快速开发、模块化设计、内置安全特性等方面的详细回答。虽然是 2B 参数的小模型，但对于常见技术问题的回答质量已经相当不错。

Spring AI 与 Ollama 集成实战

第一步：修改 Maven 依赖

这是整个集成过程中最关键的一步。在 pom.xml 中，将原来的 OpenAI 依赖替换为 Ollama 依赖：

<!-- 移除 OpenAI 依赖，添加 Ollama 依赖 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

为什么需要这个依赖？因为你的 Spring Boot 应用并不知道如何直接与本地运行的 Ollama 通信。这个 starter 充当了一座桥梁：它负责处理所有底层的 API 调用，将你的请求转换为 Ollama 能理解的格式，并将响应解析回来。

深入来看，Spring Boot 的 Starter 机制是理解整个集成过程的关键。当你在 pom.xml 中引入 spring-ai-ollama-spring-boot-starter 时，Spring Boot 的自动配置（Auto-Configuration）机制会在启动时扫描 classpath，发现 Ollama 相关的类后自动创建并注册所需的 Bean——包括 OllamaChatModel、HTTP 客户端连接池等。这一机制基于 @ConditionalOnClass 和 @ConditionalOnProperty 等条件注解实现，开发者无需手动编写任何配置类。这也是为什么从 OpenAI 切换到 Ollama 只需要换依赖和配置：Spring Boot 会根据 classpath 中存在的 Starter 自动决定创建哪种 ChatModel 实现。

第二步：修改 application 配置

在 application.properties 或 application.yml 中，替换原来的 OpenAI 配置：

# 不再需要 API Key
# 指定使用的模型
spring.ai.ollama.chat.model=gemma:2b
# 指定 Ollama 服务地址（可选，Spring Boot 会自动识别）
spring.ai.ollama.base-url=http://localhost:11434

配置文件中的 Ollama 连接信息

Ollama 启动模型后，默认在 11434 端口暴露 HTTP API。Spring Boot 的自动配置机制会检测到 Ollama 依赖的存在，自动连接到这个端点。

第三步：注意 ChatModel 的类型变更

演示中遇到了一个典型的坑：配置中引用的 ChatModel 类型需要从 OpenAiChatModel 改为 OllamaChatModel。这是因为不同的 AI 提供商有各自的实现类。如果忘记修改，会出现类似"model mistral not found"的错误。

修正后重新启动应用，一切正常工作。

第四步：验证集成结果

应用启动在 8080 端口后，通过 curl 发送请求：

curl "http://localhost:8080/ai?message=what is multi-threading"

成功获取 Ollama 模型的响应

模型成功返回了关于多线程的详细解释，包括其概念、优势和应用场景。需要注意的是，本地推理的速度取决于你的硬件配置，2B 模型在普通机器上可能需要几秒到十几秒的响应时间。

核心亮点：代码零改动的抽象之美

整个集成过程中，最值得关注的一点是：Controller 层的业务代码完全没有改动。

// 同一份代码，既能对接 OpenAI，也能对接 Ollama
@GetMapping("/ai")
public String chat(@RequestParam String message) {
    // 调用 LLM，获取响应
    return chatModel.call(message);
}

从 OpenAI 切换到 Ollama，开发者只做了两件事：

换依赖：pom.xml 中替换 starter
换配置：application.properties 中修改模型名和地址

这正是 Spring AI 设计哲学的精髓——通过抽象层屏蔽底层差异。Spring AI 的接口抽象设计遵循了经典的策略模式（Strategy Pattern）和 Spring 框架一贯的面向接口编程理念。其核心接口 ChatModel（早期版本中为 ChatClient）定义了与 LLM 交互的标准方法签名，而 OpenAiChatModel、OllamaChatModel、AnthropicChatModel 等则是具体实现。这种设计与 Spring Data 中 JpaRepository 屏蔽不同数据库差异、Spring Cloud 中 DiscoveryClient 屏蔽不同注册中心差异的思路完全一致。开发者面向接口编程，具体实现由 Spring 的依赖注入容器在运行时决定，从而实现了 AI 后端的可插拔切换。

实际开发建议

适用场景

开发和调试阶段：本地运行模型可以节省大量 API 费用，快速迭代
隐私敏感场景：数据完全不出本机，适合处理敏感信息
离线环境：无网络条件下也能正常工作

硬件与性能注意事项

硬件要求：即使是 2B 的小模型也需要一定的内存和算力，7B 及以上模型建议至少 16GB 内存
模型能力差距：本地小模型与 GPT-4 等商业模型在推理能力上仍有明显差距，需根据实际需求选择
生产环境慎用：Ollama 更适合开发测试，生产环境需要考虑并发、稳定性等问题

本地推理的性能瓶颈主要来自两个方面：内存带宽和计算能力。LLM 推理是一个内存密集型任务——模型参数需要从内存加载到处理器，而生成每个 token 都需要遍历整个模型。以 7B 模型的 4-bit 量化版本为例，模型文件约 4GB，运行时实际内存占用可能达到 6-8GB（包括 KV Cache 等中间状态）。如果使用 GPU 推理，VRAM 大小是关键限制因素；如果使用 CPU 推理，内存带宽（而非 CPU 频率）往往是性能瓶颈。这也解释了为什么 Apple Silicon Mac 在本地推理场景中表现出色——其统一内存架构（Unified Memory Architecture）提供了极高的内存带宽，GPU 和 CPU 共享同一块内存池，避免了传统架构中 CPU 内存与 GPU 显存之间的数据搬运开销。

总结

Spring AI + Ollama 的组合为 Java 开发者提供了一条零成本、零门槛的 AI 应用开发路径。Ollama 负责在本地高效运行开源大模型，Spring AI 负责提供优雅的抽象和集成体验，两者配合让开发者可以专注于业务逻辑，而不必纠结于底层通信细节。

更重要的是，Spring AI 的抽象设计意味着你可以在开发阶段用 Ollama 免费调试，上线时无缝切换到 OpenAI 或其他商业服务——只需改改配置文件即可。这种灵活性，正是框架设计的最高境界。