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

A꯭ғ꯭ᴛ꯭ᴇ꯭ʀ꯭ᴀʟʟ126

429人浏览 · 2026-08-04 15:55:49

A꯭ғ꯭ᴛ꯭ᴇ꯭ʀ꯭ᴀʟʟ126 · 2026-08-04 15:55:49 发布

前言

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 容器中会存在一个 OllamaChatModel Bean，它同时也实现了 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 切换到阿里云通义千问，只需：

在 application.yml 中配置 dashscope.api-key。
将 ollama.chat.enabled 设为 false（或移除配置）。
添加 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 的企业级集成能力，非常适合构建安全、可控的智能应用。赶快动手试试吧！