Spring Boot 深度集成 Ollama 指南：从聊天模型配置到生产级应用开发

前言

在人工智能应用开发中，大语言模型（LLM）的本地化部署需求日益增长。Ollama 作为开源的本地LLM运行平台，支持Mistral、LLaMA等主流模型，并提供与OpenAI兼容的API接口，而 Spring AI 则为Java开发者提供了便捷的集成工具链。本文将结合Spring Boot框架，详细讲解如何通过Spring AI实现Ollama聊天模型的全生命周期管理，涵盖基础配置、高级功能开发及生产环境优化，帮助开发者构建高效、可控的本地化智能应用。

一、Ollama 环境搭建与 Spring Boot 集成

1. 安装与启动 Ollama

本地安装：
从 Ollama 官网下载对应系统的二进制文件（如Windows、macOS或Linux），启动后默认监听端口 11434。
```
# 启动命令（示例）
./ollama server
```

模型拉取：
通过命令行预拉取模型，避免运行时延迟：

ollama pull mistral       # 拉取默认聊天模型
ollama pull hf.co/llama3 # 拉取Hugging Face GGUF格式模型

2. Spring Boot 依赖配置

在 pom.xml 中引入Spring AI对Ollama的支持模块：

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
<dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-bom</artifactId><version>3.2.0</version> <!-- 替换为最新版本 --><type>pom</type><scope>import</scope></dependency></dependencies>
</dependencyManagement>

二、核心配置：聊天模型参数与自动管理

1. 基础连接与模型初始化

在 application.yaml 中配置Ollama服务地址及模型拉取策略：

spring:ai:ollama:base-url: http://localhost:11434  # Ollama API地址init:pull-model-strategy: when_missing  # 自动拉取策略（always/never/when_missing）timeout: 10m                      # 拉取超时时间max-retries: 2                    # 拉取失败重试次数chat:include: true                   # 是否初始化聊天模型additional-models: ["llama3-13b"] # 额外预拉取的模型列表

2. 聊天模型参数详解

通过 spring.ai.ollama.chat.options 前缀配置模型行为，关键参数如下：

属性	描述	示例配置
`model`	目标模型名称（如`mistral`、`llava`）	`model: mistral`
`temperature`	生成随机性（0.0保守，1.0创意）	`temperature: 0.7`
`num-ctx`	上下文窗口大小（影响历史对话记忆，单位：Token）	`num-ctx: 4096`
`stop`	终止生成的字符序列（如`["###", "\nEND"]`）	`stop: ["###"]`
`keep-alive`	模型在内存中保持加载的时间（避免频繁重新加载）	`keep-alive: 10m`
`num-gpu`	GPU加速层数（macOS设为1启用Metal，-1自动检测）	`num-gpu: 1`

完整配置示例：

spring:ai:ollama:chat:options:model: mistraltemperature: 0.8num-ctx: 2048stop: ["用户:", "###"]top-k: 50

三、高级功能开发：从函数调用到多模态支持

1. 函数调用（Tool Calling）

通过Ollama的函数调用能力，实现LLM与外部工具的联动（需Ollama ≥0.2.8）：

@RestController
public class ToolController {private final OllamaChatModel chatModel;@Autowiredpublic ToolController(OllamaChatModel chatModel) {this.chatModel = chatModel;}@PostMapping("/tool/call")public ChatResponse toolCall(@RequestBody String prompt) {// 注册可调用的函数列表List<String> functions = Arrays.asList("searchWeather", "calculate");return chatModel.call(new Prompt(prompt, OllamaOptions.builder().functions(functions).build()));}
}

LLM将返回包含函数名和参数的JSON，例如：

{"function_call": {"name": "searchWeather","parameters": { "city": "北京", "date": "2023-10-01" }}
}

2. 多模态支持（文本+图像）

利用LLaVA等多模态模型处理图像输入（需Ollama支持多模态模型）：

@GetMapping("/multimodal")
public ChatResponse multimodalQuery() throws IOException {// 加载图像资源ClassPathResource imageResource = new ClassPathResource("cat.jpg");Media imageMedia = new Media(MimeTypeUtils.IMAGE_JPEG, imageResource);// 构造包含图像的用户消息UserMessage userMessage = new UserMessage("描述图片中的动物", imageMedia);return chatModel.call(new Prompt(userMessage, OllamaOptions.builder().model("llava").build()));
}

多模态是指模型同时理解和处理来自各种来源的信息（包括文本、图像、音频和其他数据格式）的能力。

Ollama 中支持多模态的一些模型是 LLaVA 和 BakLLaVA（请参阅完整列表）。有关更多详细信息，请参阅 LLaVA：大型语言和视觉助手。

Ollama 消息 API 提供了一个 “images” 参数，用于将 base64 编码的图像列表与消息合并。

Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型。此类型包含有关消息中媒体附件的数据和详细信息，使用 Spring 的org.springframework.util.MimeType以及org.springframework.core.io.Resource对于原始媒体数据。

下面是一个摘自 OllamaChatModelMultimodalIT.java 的简单代码示例，说明了用户文本与图像的融合。

var imageResource = new ClassPathResource("/multimodal.test.png");var userMessage = new UserMessage("Explain what do you see on this picture?",new Media(MimeTypeUtils.IMAGE_PNG, this.imageResource));ChatResponse response = chatModel.call(new Prompt(this.userMessage,OllamaOptions.builder().model(OllamaModel.LLAVA)).build());

该示例显示了一个模型，将multimodal.test.png图像：
多模态测试图像
以及文本消息 “Explain what do you see on this picture？”，并生成如下响应：

The image shows a small metal basket filled with ripe bananas and red apples. The basket is placed on a surface,
which appears to be a table or countertop, as there's a hint of what seems like a kitchen cabinet or drawer in
the background. There's also a gold-colored ring visible behind the basket, which could indicate that this
photo was taken in an area with metallic decorations or fixtures. The overall setting suggests a home environment
where fruits are being displayed, possibly for convenience or aesthetic purposes.

3. 结构化输出与JSON Schema

强制模型返回符合指定格式的结构化数据，便于后续解析：

// 定义JSON Schema
String schema = """{"type": "object","properties": {"steps": {"type": "array","items": { "type": "string" }},"result": { "type": "number" }},"required": ["steps", "result"]}
""";// 在请求中指定格式
ChatResponse response = chatModel.call(new Prompt("计算1+2+3的步骤", OllamaOptions.builder().format(new ObjectMapper().readValue(schema, Map.class)).build()
));

四、生产环境优化与最佳实践

1. 模型管理策略

禁用自动拉取：生产环境中通过 pull-model-strategy: never 关闭自动拉取，提前通过 ollama pull 预下载模型。
模型版本控制：固定模型版本（如mistral:latest），避免因模型更新导致的行为变化。

2. 资源性能调优

GPU加速：设置 num-gpu: -1 自动检测GPU，或根据硬件指定层数（如num-gpu: 8）。
内存优化：启用 low-vram: true 减少显存占用，或 use-mlock: true 锁定模型内存防止交换。

3. 连接与容错

连接池配置：通过 OllamaApi 配置连接超时（如connectTimeout(5000)）和重试机制。
监控与日志：集成Micrometer监控Ollama请求延迟、错误率，或通过SLF4J记录模型调用日志。

五、OpenAI API 兼容模式：无缝迁移现有应用

Ollama提供与OpenAI API兼容的端点，允许直接复用Spring AI的OpenAI客户端：

spring:ai:openai:chat:base-url: http://localhost:11434  # 指向Ollama服务options:model: mistral                  # 使用Ollama模型temperature: 0.9

此模式下，原有基于OpenAI的代码（如函数调用、流式响应）无需修改即可运行，示例：

@Autowired
private OpenAIAsyncChatClient openAiClient;public String openAICompatQuery() {return openAiClient.chat(Collections.singletonList(new ChatMessage(ChatMessageRole.USER, "推荐一本技术书籍"))).block();
}

在这里插入图片描述

六、手动配置与低级API使用

若需自定义Bean或绕过自动配置，可手动构建OllamaChatModel：

@Configuration
public class OllamaConfig {@Beanpublic OllamaChatModel ollamaChatModel() {OllamaApi ollamaApi = OllamaApi.builder().baseUrl("http://remote-ollama-server:11434").build();return OllamaChatModel.builder().ollamaApi(ollamaApi).defaultOptions(OllamaOptions.builder().model("mistral").temperature(0.6).build()).build();}
}