三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Spring AI Alibaba + Ollama：让大模型在你的电脑上跑起来

发布时间：2026/8/5 10:19:18 三亩地 编程学习日记
Spring AI Alibaba + Ollama：让大模型在你的电脑上跑起来

前言

Spring AI Alibaba 是阿里巴巴官方推出的 AI 框架，它在 Spring AI 生态基础上深度集成了通义系列模型，并完全兼容 Spring AI 的抽象接口。这使得我们在享受阿里云 AI 便利的同时，也能无缝接入Ollama这类本地大模型。本文将展示如何在一个 Spring AI Alibaba 项目中，快速集成 Ollama 本地模型，实现对话补全与流式输出。

读完本文你将掌握：

  • 本地安装 Ollama 并拉取 Llama 3 模型
  • 在 Spring AI Alibaba 项目中引入必要依赖
  • 通过application.yml同时配置 Alibaba 和 Ollama
  • 注入顶层接口ChatModel或具体实现OllamaChatModel
  • 实现同步调用与 SSE 流式调用

一、环境准备：本地安装 Ollama

Ollama 是一个跨平台的本地大模型运行工具，提供类似 Docker 的模型管理体验。

1.1 安装并启动

# macOS (Homebrew)
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

启动服务（默认监听http://localhost:11434）：

ollama serve

1.2 拉取 Llama 3 模型

ollama pull llama3

测试模型：

ollama run llama3

对话正常即表示环境就绪。

二、创建 Spring Boot 项目并引入依赖

2.1 项目基础

基于 Spring Boot 3.x 创建项目，添加 Spring Web 依赖。

2.2 添加仓库

需要 Spring Milestone 仓库来获取 Spring AI 相关里程碑版本：

<repositories>
<repository>
<id>spring-milestones</id>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>

2.3 引入 Spring AI Alibaba 与 Ollama Starter

<dependencies>
<!-- Spring AI Alibaba 基础 Starter（提供通义千问等能力） -->
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter</artifactId>
<version>1.0.0-M3</version>
</dependency>

<!-- Ollama 官方 Starter（提供本地模型能力） -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-ollama-starter</artifactId>
<version>1.0.0-M4</version>
</dependency>
</dependencies>

注意：版本号请根据官方最新发布调整。Spring AI Alibaba 在底层完全兼容 Spring AI，因此可以混用不同模型的 Starter。

三、配置 application.yml

只需一份配置，即可同时启用多个模型。因为我们主要使用 Ollama，所以重点配置 Ollama 的连接信息：

spring:
ai:
# 阿里云灵积配置（若暂不使用可省略，或者仅占位）
dashscope:
api-key: your-dashscope-key # 此处不展开

# Ollama 本地模型配置
ollama:
base-url: http://localhost:11434
chat:
enabled: true
options:
model: llama3 # 与 ollama list 显示的模型名一致
temperature: 0.7
num-predict: 512
embedding:
enabled: false
  • base-url：指向本地 Ollama 服务地址。
  • model：必须与已拉取的模型名称严格一致。

四、注入并使用 ChatModel（重点：注入方式的选择）

Spring AI（及 Spring AI Alibaba）统一了顶层接口ChatModel，无论是阿里云的通义千问还是本地的 Ollama，业务代码完全相同。

但开发者在注入时有两种选择，各有优劣。

方式一：注入顶层接口ChatModel（推荐，可插拔）

@RestController
@RequestMapping("/ai")
public class ChatController {

@Autowired
private ChatModel chatModel; // 实际注入的是 OllamaChatModel（由配置决定）
}
  • 优点：完全解耦，后续若要换成阿里云灵积或其他模型，仅需修改配置，代码无需改动。
  • 缺点：无法调用OllamaChatModel特有的非标准方法（极少使用，绝大多数场景用接口方法足够）。

方式二：注入具体实现类OllamaChatModel（类型明确）

@Autowired
private OllamaChatModel ollamaChatModel;
  • 优点：代码表意清晰，一眼就知道用的是本地 Ollama 模型；可调用其特有 API。
  • 缺点：与实现类绑定，切换 AI 提供商时需要修改代码，不够灵活。

实际表现

当同时引入spring-ai-alibaba-starter和spring-ai-ollama-starter，且只启用ollama.chat.enabled: true时，Spring 容器中会存在一个OllamaChatModelBean，它同时也实现了ChatModel接口。此时用接口注入和用实现类注入，拿到的是同一个对象。

建议：如果你的项目确定长期只用 Ollama，且希望代码更明确，可以使用方式二；若考虑未来灵活扩展，推荐方式一。两种方式均不影响同步和流式调用的代码逻辑。

五、同步与流式调用

以下示例以接口注入ChatModel为例，如果使用OllamaChatModel，代码写法完全一致（接口方法签名相同）。

5.1 同步调用

@GetMapping("/chat")
public String chat(@RequestParam String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return chatModel.call(prompt).getResult().getOutput().getContent();
}

5.2 流式调用（SSE）

@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> chatStream(@RequestParam String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return chatModel.stream(prompt)
.map(response -> response.getResults().get(0).getOutput().getContent());
}

前端可使用EventSource接收流式数据，实现打字机效果。

六、切换模型：一行配置的事

如果你后续想从本地 Ollama 切换到阿里云通义千问，只需：

  1. 在application.yml中配置dashscope.api-key。
  2. 将ollama.chat.enabled设为false（或移除配置）。
  3. 添加dashscope.chat.options.model: qwen-turbo等。

Controller 代码完全无需修改。这正是 Spring AI Alibaba 拥抱 Spring AI 生态带来的插拔式体验。

七、常见问题

1. 启动报错找不到 OllamaChatModel

  • 确认已引入spring-ai-ollama-starter。
  • 检查 Spring AI 版本与 Spring Boot 版本兼容性（通常 1.0.0-M4 配合 Spring Boot 3.3.x）。

2. 连接被拒绝

  • 确保 Ollama 服务已启动（ollama serve），且base-url端口正确。

3. 模型名无效

  • 执行ollama list查看已安装模型名，注意区分大小写。

4. 如何同时使用多个模型？

  • 可以同时配置ollama和dashscope，然后通过@Qualifier或根据ChatModel的 bean 名称来注入特定实现（如ollamaChatModel、dashScopeChatModel）。默认情况下，只有一个聊天模型会被标注为 primary。

八、总结

本文展示了如何在 Spring AI Alibaba 项目中快速接入 Ollama 本地大模型，并重点讨论了注入ChatModel接口与注入OllamaChatModel具体实现的区别。Spring AI Alibaba 在保持阿里云模型深度集成的同时，完全兼容 Spring AI 生态，让我们能够自由组合本地与云端模型。代码层面只需面向ChatModel接口编程，即可轻松实现同步与流式调用，真正做到了一处开发，处处可用。

本地模型带来的数据隐私和低延迟优势，结合 Spring AI Alibaba 的企业级集成能力，非常适合构建安全、可控的智能应用。赶快动手试试吧！

参考资料

  • Ollama 官方文档
  • Spring AI Alibaba GitHub
  • Spring AI 参考手册
编程学习 学习日记 实战经验
← 返回列表