接入 Ollama 本地模型

14.1 Ollama 是什么

前几章接的都是云端 API，模型在厂商服务器上跑。Ollama 不一样，它把模型下载到本机，推理也在本机完成。

本地部署有三个实际好处：数据不出机器，适合敏感场景；不按 token 收费，随便测；断网也能用。代价是效果不如顶级云端模型，而且吃本机硬件。

Ollama 的模型通过命令拉取，不需要 API Key。整个过程零配置，这也是它成为本地模型首选的原因。

14.2 安装与拉取模型

到 ollama.com/download 下载安装包。Windows 和 macOS 都是图形化安装，装完 Ollama 服务会自动启动，默认监听 http://localhost:11434。

验证安装：

ollama --version

然后从模型库拉一个模型。模型库在 ollama.com/library，几行命令的事：

ollama pull qwen2.5
ollama pull llama3.2
ollama pull deepseek-r1

模型名可以带大小后缀，比如 qwen2.5:0.5b、qwen2.5:7b。后缀里的数字表示参数量，7b 的量化模型权重约 4-5GB，加上上下文缓存，建议至少 8GB 显存；0.5b、1.5b 这类小模型 CPU 也能跑。后缀决定模型体积，也决定硬件要求。

14.3 添加依赖与配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>

连接配置只有一个必填项：

spring.ai.ollama.base-url=http://localhost:11434

spring.ai.ollama.chat.model=qwen2.5
spring.ai.ollama.chat.temperature=0.7

base-url 默认就是 http://localhost:11434，本机部署可以不写。chat.model 默认是 mistral，建议显式改成你拉取的模型名。

Ollama 的采样参数很丰富，常用的几个：

属性	说明	默认值
spring.ai.ollama.chat.num-ctx	上下文窗口大小	2048
spring.ai.ollama.chat.num-predict	最大生成 token 数，-1 不限	-1
spring.ai.ollama.chat.top-k	top-k 采样	40
spring.ai.ollama.chat.top-p	核采样	0.9
spring.ai.ollama.chat.keep-alive	模型驻留内存的时间	5m
spring.ai.ollama.chat.num-gpu	送 GPU 的层数，-1 自动	-1

num-ctx 影响模型能”记住”多少上下文，调大消耗更多显存。keep-alive 控制模型在内存里的驻留时间，频繁调用建议调长，避免反复加载。

14.4 第一个对话接口

配置好之后，注入 OllamaChatModel 使用：

@RestController
public class ChatController {

    private final OllamaChatModel chatModel;

    public ChatController(OllamaChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map<String, String> generate(@RequestParam(defaultValue = "讲个笑话") String message) {
        return Map.of("generation", chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(defaultValue = "讲个笑话") String message) {
        return chatModel.stream(new Prompt(new UserMessage(message)));
    }
}

运行时覆盖参数用 OllamaChatOptions：

ChatResponse response = chatModel.call(new Prompt(
        "列出 5 个 Java 集合类",
        OllamaChatOptions.builder()
                .model("qwen2.5")
                .temperature(0.4)
                .build()));

14.5 启动时自动拉取模型

开发环境经常换机器，忘了拉模型是常事。Spring AI 支持启动时自动拉取，策略有三种：never 不拉（默认）、when_missing 缺了才拉、always 每次都拉最新。

spring.ai.ollama.init.pull-model-strategy=when_missing
spring.ai.ollama.init.timeout=60s
spring.ai.ollama.init.max-retries=1

应用会等模型就绪才完成启动。模型大、网速慢时，启动时间会明显变长，所以官方明确不推荐生产环境用自动拉取，生产应该提前 ollama pull 预下载。

还能一次初始化多个模型，给运行时动态切换用：

spring.ai.ollama.init.pull-model-strategy=always
spring.ai.ollama.init.chat.additional-models[0]=llama3.2
spring.ai.ollama.init.chat.additional-models[1]=qwen2.5

14.6 思考模式

Ollama 支持推理模型的思考模式。qwen3、deepseek-r1、deepseek-v3.1 这类模型会先输出推理过程，再给答案。

Ollama 0.12 之后，思考型模型默认自动开启思考。想显式控制用 builder 方法：

ChatResponse response = chatModel.call(new Prompt(
        "strawberry 这个单词里有几个字母 r？",
        OllamaChatOptions.builder()
                .model("deepseek-r1")
                .enableThinking()
                .build()));

// 推理过程在元数据里
String thinking = response.getResult().getMetadata().get("thinking");
String answer = response.getResult().getOutput().getText();

思考内容存在响应的 thinking 元数据键里，最终答案照常在 getText()。禁用思考用 disableThinking()。流式调用同样支持，每个 chunk 都会带 thinking 元数据。

14.7 结构化输出

Ollama 原生支持结构化输出，通过 format 参数约束。两种模式：

简单模式，只要合法 JSON，不限定结构：

ChatResponse response = chatModel.call(new Prompt(
        "列出欧洲的 3 个国家",
        OllamaChatOptions.builder()
                .model("llama3.2")
                .format("json")
                .build()));

严格模式，给一个 JSON Schema，模型必须按这个结构返回：

String jsonSchema = """
        {
          "type": "object",
          "properties": {
            "countries": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["countries"]
        }
        """;

ChatResponse response = chatModel.call(new Prompt(
        "列出欧洲的 3 个国家",
        OllamaChatOptions.builder()
                .model("llama3.2")
                .outputSchema(jsonSchema)
                .build()));

生产环境优先用 outputSchema。结构不确定的 JSON 会给下游解析埋坑。

14.8 走 OpenAI 兼容端点

Ollama 自带 OpenAI 兼容端点，地址是 /v1。不想用 Ollama 专属 starter 的话，可以用 OpenAI 客户端连它：

spring.ai.openai.chat.base-url=http://localhost:11434/v1
spring.ai.openai.chat.model=qwen2.5
spring.ai.openai.api-key=ollama

api-key 随便填一个占位就行，Ollama 本地不校验。兼容端点也能拿到思考型模型的推理内容，字段名是 reasoningContent，对应 Ollama 原生模式的 thinking。

Ollama 专属参数（top_k、repeat_penalty 等）想传的话，用 extra-body 前缀：

spring.ai.openai.chat.extra-body.num_predict=100
spring.ai.openai.chat.extra-body.top_k=40

注意这些参数名沿用 Ollama 兼容端点的命名习惯，和 OpenAI 官方参数不同，别混用。

14.9 常见问题排查

本地部署的报错，基本都集中在服务和模型上。

连接被拒绝（Connection refused），先确认 Ollama 服务在跑。Windows 上装完 Ollama 是开机自启的，任务栏能看到图标。再确认 base-url 没写错，默认端口 11434，改成别的端口要两边一致。

模型不存在（model not found），就是没拉模型或名字写错。ollama list 查看本机已有模型，名字要和列表完全一致，大小后缀也要对上。

显存不足或生成极慢，模型和硬件不匹配。换更小的模型，或调小 num-ctx 上下文窗口。num-ctx 直接决定 KV 缓存占多少显存，从 2048 降到 1024 能省不少。

14.10 工具调用与多模态

Ollama 支持工具调用，走统一的 ToolCallback 机制，ChatClient 自动闭环。工具调用的完整写法与第 12 章相同，只需把示例里的 chatModel 换成 OllamaChatModel，完整示例见 12.8。

两个版本门槛记住：工具调用要 Ollama 0.2.8+，流式工具调用要 0.4.6+。版本太老会静默失效。

多模态方面，llava、bakllava 这类视觉模型支持图片输入，用法和前面章节的 Media 一致：

var imageResource = new ClassPathResource("/multimodal.png");

var userMessage = new UserMessage("这张图里有什么？",
        new Media(MimeTypeUtils.IMAGE_PNG, imageResource));

ChatResponse response = chatModel.call(new Prompt(userMessage,
        OllamaChatOptions.builder().model("llava").build()));

14.11 小结

Ollama 的接入是所有厂商里最简单的：装软件、拉模型、配 base-url，连 API Key 都不需要。难点在硬件：模型大小和显存要匹配，跑不动就换小模型。它还兼容 OpenAI 规范，一套客户端通吃云上和本地。到这里，云厂商和本地模型两大路线都走通了，下一章开始看更多厂商的接入。