前几篇我们都在和云端的模型打交道，虽然方便，但每次调用都要走网络、数据要出网、还要按量付费。今天我们来搞点不一样的——把大模型搬到你自己的电脑上跑，全程离线，数据不出本机，而且完全免费。

实现这个目标，我们需要一个工具：Ollama。它的定位是“本地大模型运行器”，安装简单、命令行操作、支持几十种开源模型。更关键的是，Spring AI 对它提供了原生支持，接入方式和前面学的 OpenAI 几乎一模一样。今天我们就从安装 Ollama 开始，拉取模型，最后用 Spring AI 接上本地服务，完成第一次本地 AI 对话。

一、痛点场景：为什么要把模型搬到本地？

场景一：隐私和合规

你做的智能客服要处理用户的工单、合同、报表。这些数据一旦通过 API 发送到云端，哪怕承诺“不用于训练”，合规部门也很难点头。本地模型的核心优势在于：原始数据不需要离开你的机器，你自己掌控网络边界、日志和存储。

场景二：成本控制

云 API 按 Token 计费。如果你做的不是偶尔玩玩的 demo，而是一个稳定的内部问答系统，每天几千次调用，月底的账单会让你肉疼。本地模型更像一次投入、长期使用——硬件成本固定，运行成本可预期。

场景三：实验自由

学习阶段你想折腾各种模型、各种参数，云端受限于平台提供的模型列表。本地你可以自由拉取 Qwen、Llama、DeepSeek、Phi 等几十种开源模型，随便切换、随便测。

场景四：网络受限环境

有些企业内网根本连不上外网，或者网络延迟很高。本地推理不需要联网，只要局域网通就行，延迟可控。

如果你被以上任意一条戳中，那今天的内容就是为你准备的。

二、核心概念快览

2.1 什么是 Ollama？

Ollama 是一个用于在本地运行大语言模型的工具。它的特点是安装简单（Windows/Mac/Linux 都支持），一条命令就能拉取和运行模型，自动检测并利用 GPU，通过本地 API（默认端口 11434）对外提供服务。

你可以把 Ollama 理解为“大模型界的 Docker”——它帮我们屏蔽了模型下载、量化、加载、CUDA 适配等底层琐事，让我们把精力集中在应用开发上。

2.2 工作流程

你自己的电脑
┌────────────────────────────────────────┐
│  Ollama 进程（端口 11434）              │
│  ┌──────────────────────────────────┐  │
│  │  Qwen2.5:7b 模型文件（约 4.7 GB） │  │
│  └──────────────────────────────────┘  │
│                 ↓                       │
│          提供 REST API                  │
│    http://localhost:11434              │
└────────────────────────────────────────┘
         ↑  HTTP 请求（本地回环）
┌────────────────────────────────────────┐
│  你的 Spring Boot 应用                  │
│  通过 Spring AI 的 ChatClient 调用     │
└────────────────────────────────────────┘

模型文件存在本地硬盘，Ollama 启动一个本地 HTTP 服务，你的 Java 程序通过这个本地服务完成推理，数据全程不出机器。

2.3 参数（Parameters）与量化

模型名称后面的数字（如 7b、14b）表示参数量，单位 B 是 Billion（十亿）。参数越多，模型越“聪明”，但也越吃显存。

量化（Quantization）是把高精度的模型参数压缩到低精度（如 4-bit），以显著降低显存需求，代价是轻微的精度损失。Ollama 默认使用 Q4_K_M 量化，这是速度和精度的最佳平衡点。

三、环境准备

3.1 硬件最低要求

硬件	最低要求	推荐配置
内存	8 GB	16 GB+
显存（GPU）	无 GPU 也可用 CPU	8 GB+（跑 7B 模型）
磁盘	20 GB 空闲	50 GB+（方便下载多模型）

没有独立显卡也能跑，只是慢一些。有 NVIDIA 显卡（CUDA 支持）的话，推理速度会快很多。Mac 用户注意：Apple Silicon 的统一内存可以当显存用，M2 Pro 32GB 约等于 24GB 显存的体验。

3.2 安装 Ollama

访问 ollama.com/download，根据你的操作系统选择安装包。

Windows 用户：下载 .exe 安装包，双击一路 Next，安装完成后 Ollama 会自动以后台服务运行，任务栏右下角会出现小图标。如果官网下载慢，可以用国内镜像：https://mirror.ghproxy.com/https://github.com/ollama/ollama/releases/latest/download/OllamaSetup.exe。

Mac 用户：下载 .dmg 文件，拖入 Applications 即可。

Linux 用户：执行一行命令完成安装：

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

安装完成后，可以用以下命令验证：

ollama --version
# 输出类似：ollama version 0.23.x

3.3 配置模型存储路径（重要！）

Ollama 默认把模型下载到 C 盘（Windows）或系统盘（Mac/Linux），模型文件动辄几个 GB，C 盘很容易爆满。建议立刻修改存储路径。

Windows：

1. 按 Win+R，输入 sysdm.cpl。
2. 依次点击“高级 → 环境变量”。
3. 新建用户变量：变量名 OLLAMA_MODELS，变量值设为你的目标路径，如 D:\Ollama\Models。
4. 重启电脑生效。

Mac / Linux：在终端配置文件中（如 ~/.bashrc 或 ~/.zshrc）添加：

export OLLAMA_MODELS=/你的路径/ollama_models

然后执行 source ~/.bashrc 使其生效。

3.4 Maven 依赖

在 pom.xml 中，将 spring-ai-starter-model-openai 替换为 spring-ai-starter-model-ollama：

<!-- Spring AI Ollama Starter：为 Ollama 本地模型提供自动配置 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>

注意：这个 starter 和之前的 spring-ai-starter-model-openai 互斥，不要同时引入，除非你很明确自己的场景和依赖冲突处理策略。

如果你还想保留 spring-ai-starter-model-openai，理论上可以做多模型共存，但在学习阶段建议先只用 Ollama starter，避免配置冲突。

四、拉取模型：选一个适合你的

4.1 模型选择指南

Ollama 支持上百种模型。我们不必纠结，按“适合大多数人的性价比”来选。以下是 2026 年 Ollama 社区最常用的几个模型及其硬件要求：

模型	参数量	量化后大小	最低显存	特点
Qwen2.5:7b	7B	4.7 GB	8 GB	中文能力强，全能型
Llama3.1:8b	8B	4.7 GB	6 GB	英文强，生态好
DeepSeek-r1:7b	7B	~4.7 GB	8 GB	推理和代码能力强
Phi-3:mini	3.8B	2.3 GB	4 GB	体积最小，速度快
Qwen2.5:14b	14B	9.0 GB	16 GB	高质量中文生成
Llama3.1:70b	70B	40 GB	64 GB+	顶级综合能力

新手推荐：如果你的内存是 16 GB，选择 Qwen2.5:7b；如果内存是 8 GB 或没有独立显卡，选 Phi-3:mini；如果主要做代码相关，选 DeepSeek-r1:7b。

4.2 拉取模型

打开终端，执行：

# 拉取 Qwen2.5 7B 模型（中文优化，推荐）
ollama pull qwen2.5:7b

# 如果你主要做代码工作，也可以拉这个
ollama pull deepseek-r1:7b

# 查看已安装的模型
ollama list

第一次拉取会下载几个 GB 的文件，耐心等待。下载完成后，可以先用命令行测试一下：

ollama run qwen2.5:7b "你好，请用一句话介绍你自己"

如果返回了正常的回复，说明 Ollama 安装和模型都就绪了。

4.3 配置 Ollama 允许外部访问（可选）

默认情况下，Ollama 只监听 127.0.0.1:11434，同一台机器上的程序访问没问题。如果你的 Spring Boot 应用部署在其他机器上，需要让 Ollama 监听所有网络接口。

Linux（systemd）：

sudo systemctl edit ollama
# 添加以下内容：
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
# 保存后重启
sudo systemctl daemon-reload
sudo systemctl restart ollama

Windows：在系统环境变量中添加 OLLAMA_HOST，值设为 0.0.0.0:11434，然后重启 Ollama 服务。

注意：将 Ollama 暴露在公网有安全风险，建议只在内网环境使用，或配合防火墙规则限制访问来源。

五、代码实战：Spring AI 接入 Ollama

5.1 application.yml 配置

spring:
  application:
    name: spring-ai-ollama-demo

  ai:
    ollama:
      base-url: http://localhost:11434          # Ollama 默认地址
      init:
        pull-model-strategy: never              # 启动时不自动拉取模型
      chat:
        options:
          model: qwen2.5:7b                     # 使用的模型名称
          temperature: 0.7

核心配置项说明：

• spring.ai.ollama.base-url：Ollama 服务的 HTTP 地址，默认就是 http://localhost:11434，如果 Ollama 跑在另一台机器上，改成对应 IP。
• spring.ai.ollama.chat.options.model：要使用的模型名称，必须与 ollama list 中显示的名称完全一致（注意大小写和冒号）。
• spring.ai.ollama.init.pull-model-strategy：启动时是否自动拉取模型。设为 never 可避免网络问题阻塞启动。可选值还有 always（启动时立即拉取）和 when_missing（缺少时自动拉取）。

5.2 创建 ChatController

package com.example.springaihelloworld.controller;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class OllamaChatController {

    private final ChatClient chatClient;

    public OllamaChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    /**
     * 本地模型同步对话
     * 访问：http://localhost:8080/ollama/chat?msg=你好
     */
    @GetMapping("/ollama/chat")
    public String chat(@RequestParam String msg) {
        return chatClient
                .prompt()
                .user(msg)
                .call()
                .content();
    }

    /**
     * 本地模型流式对话（打字机效果）
     */
    @GetMapping(value = "/ollama/stream", produces = org.springframework.http.MediaType.TEXT_EVENT_STREAM_VALUE)
    public reactor.core.publisher.Flux<String> stream(@RequestParam String msg) {
        return chatClient
                .prompt()
                .user(msg)
                .stream()
                .content();
    }
}

看，调用方式完全没变——还是 .prompt().user().call().content()。Spring AI 的抽象层让我们无需关心底层是云端的 DeepSeek 还是本地的 Qwen，业务代码一模一样。

这就是我们在第 3 篇里反复强调的“改配置，不改代码”的延续——甚至换了一个完全不同的 provider（从 OpenAI 兼容 API 切换到 Ollama API），代码依然零改动。

5.3 带角色预设的本地对话

@GetMapping("/ollama/advisor")
public String advisor(@RequestParam String msg) {
    return chatClient
            .prompt()
            .system("你是一个资深的 Java 架构师，回答问题要专业、简洁，用代码示例辅助说明。")
            .user(msg)
            .call()
            .content();
}

从云端到本地，角色预设、流式输出、结构化输出这些高级能力依然可用（效果取决于模型本身的能力）。如果需要结构化输出，代码与第 6 篇完全一致，只需确认你选择的本地模型有足够的指令遵循能力（7B 以上模型通常没问题）。

六、运行与演示

6.1 确保 Ollama 在运行

打开终端，确认 Ollama 服务正常：

ollama list
# 输出示例：
# NAME                 ID              SIZE      MODIFIED
# qwen2.5:7b          abc123def456    4.7 GB    2 days ago

如果能列出模型，说明服务正常。

6.2 启动 Spring Boot 应用

在 IDEA 中直接运行启动类，或执行 mvn spring-boot:run。

6.3 测试接口

浏览器访问：

http://localhost:8080/ollama/chat?msg=用一句话介绍Spring Boot

返回类似：

Spring Boot 是一个基于 Spring 框架的快速开发工具，通过自动配置和起步依赖简化了 Java 应用的搭建与部署。

再试一下流式接口，用 curl：

curl -N "http://localhost:8080/ollama/stream?msg=讲一个程序员笑话"

你会看到逐字蹦出的打字机效果。本地推理的延迟比云端更低，因为数据不需要过公网。实测在 RTX 3060（8GB 显存）上跑 Qwen2.5:7b，生成速度可达 40+ tokens/秒，远快于人类阅读速度。

6.4 与云端调用对比

对比维度	云端 API（DeepSeek）	本地 Ollama（Qwen2.5:7b）
网络要求	必须联网	不需要
数据隐私	数据上传云端	完全本地
费用	按量计费	免费
首次响应延迟	含网络开销	更低
模型能力	强（更大参数）	取决于选择的模型
部署复杂度	低（配 API Key 即可）	中等（需安装和下载模型）

七、常见问题与避坑提示

问题一：Ollama 安装后无法启动

Windows 用户：检查 Ollama 服务是否已启动，在服务管理器（services.msc）中找 “Ollama” 服务，确认状态为“正在运行”。

Mac / Linux 用户：在终端执行 ollama serve 看是否有错误输出。常见原因是端口 11434 被其他程序占用。

问题二：模型回答很慢

没有 GPU 时，Ollama 会使用 CPU 推理。7B 模型在纯 CPU 上生成速度可能在 2-10 tokens/秒，属于正常现象。解决办法：换更小的模型（如 Phi-3:mini、Qwen2.5:1.5b），或者加一块显卡。

问题三：Spring Boot 连接被拒（Connection refused）

java.net.ConnectException: Connection refused

原因：Ollama 服务没有启动，或者 Spring Boot 配置的 base-url 不对。

排查：

1. 确认 Ollama 在运行：终端执行 ollama list，能列出模型说明服务正常。
2. 确认端口：默认是 http://localhost:11434。
3. 如果 Spring Boot 跑在 Docker 容器里，且需要访问宿主机的 Ollama，localhost 需要改为 host.docker.internal（Windows/Mac）或宿主机的内网 IP（Linux）。

问题四：模型名称不匹配

model "qwen2.5:7b" not found

原因：配置中的模型名称与 ollama list 列出的不一致。注意区分大小写和冒号。在终端执行 ollama list 查看准确名称，然后回填到 application.yml 中。

问题五：内存不足（OOM）

7B 模型需要约 8GB 可用内存。如果运行时报 OutOfMemoryError，可以：

• 换更小的模型（Phi-3:mini 只需 2.3GB）。
• 增加系统内存或使用 GPU。
• 关闭其他占用内存的程序。

八、小结与下一步预告

本篇回顾

• 理解了本地大模型的适用场景：隐私合规、成本控制、实验自由、网络受限环境
• 完成了 Ollama 的安装和模型存储路径配置
• 学习了模型参数和量化的基本概念
• 掌握了模型选择策略：按硬件条件选择 7B/14B/70B 等不同规模的模型
• 用 spring-ai-starter-model-ollama 成功接入本地 Ollama 服务
• 实现了与云端调用完全相同的代码体验（同步对话 + 流式输出）

一个重要的思维转变

从今天起，AI 不再是“远方的服务”，而是你电脑上实实在在跑着的进程。这意味着你可以：把公司内部文档喂给它分析而不担心泄露、深夜断网时依然做开发、自由切换几十个开源模型来对比效果。

下一步预告

Ollama 是本地大模型的入口，但 Spring AI 在国内还有一个更重要的落地选择——Spring AI Alibaba。下一篇我们将接入阿里云百炼平台，使用通义千问系列模型，体验 ChatClient 与多模态图像理解功能。国产大模型生态正在快速崛起，不容错过。

下一篇见。

---

本系列博客基于 Spring AI 1.1.6 版本编写。Ollama 版本会持续更新，建议在实际使用时查阅 Ollama 官方文档 获取最新信息。不同模型的指令遵循能力和生成质量存在差异，实际项目中建议针对所选模型进行充分测试。