OllamaChatModel API。
前提条件
你首先需要访问 Ollama 实例。有几种选择,包括以下几种:- 在你的本地计算机上下载并安装 Ollama。
- 通过 Testcontainers 配置并运行 Ollama。
- 通过 Kubernetes 服务绑定绑定到 Ollama 实例。
自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。
有关更多信息,请参阅升级说明。
pom.xml 或 Gradle build.gradle 构建文件中:
- Maven
- Gradle
基本属性
前缀spring.ai.ollama 是用于配置与 Ollama 连接的属性前缀。
以下是用于初始化 Ollama 集成和自动拉取模型的属性。
聊天属性
聊天自动配置的启用和禁用现在通过前缀为
spring.ai.model.chat 的顶级属性进行配置。要启用,spring.ai.model.chat=ollama (默认启用)要禁用,spring.ai.model.chat=none (或任何与 ollama 不匹配的值)此更改是为了允许配置多个模型。spring.ai.ollama.chat.options 是配置 Ollama 聊天模型的属性前缀。
它包括 Ollama 请求(高级)参数,例如 model、keep-alive 和 format,以及 Ollama 模型 options 属性。
以下是 Ollama 聊天模型的高级请求参数:
其余
options 属性基于 Ollama 有效参数和值 和 Ollama 类型。默认值基于 Ollama 类型默认值。
运行时选项
OllamaOptions.java 类提供模型配置,例如要使用的模型、温度等。 在启动时,可以使用OllamaChatModel(api, options) 构造函数或 spring.ai.ollama.chat.options.* 属性配置默认选项。
在运行时,你可以通过向 Prompt 调用添加新的、特定于请求的选项来覆盖默认选项。
例如,要为特定请求覆盖默认模型和温度:
自动拉取模型
当 Ollama 实例中没有可用模型时,Spring AI Ollama 可以自动拉取模型。 此功能对于开发和测试以及将应用程序部署到新环境特别有用。 有三种拉取模型的策略:always(在PullModelStrategy.ALWAYS中定义):始终拉取模型,即使它已经可用。用于确保你使用的是最新版本的模型。when_missing(在PullModelStrategy.WHEN_MISSING中定义):仅当模型尚不可用时才拉取模型。这可能会导致使用较旧版本的模型。never(在PullModelStrategy.NEVER中定义):从不自动拉取模型。
由于下载模型时可能会出现延迟,因此不建议在生产环境中使用自动拉取。相反,请考虑提前评估和预下载必要的模型。
在 Ollama 中所有指定的模型都可用之前,应用程序不会完成其初始化。根据模型大小和互联网连接速度,这可能会显著减慢应用程序的启动时间。
函数调用
你可以使用OllamaChatModel 注册自定义 Java 函数,并让 Ollama 模型智能地选择输出一个 JSON 对象,其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
阅读有关工具调用的更多信息。
多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力,包括文本、图像、音频和其他数据格式。 Ollama 中一些支持多模态的模型是 LLaVA 和 BakLLaVA(请参阅完整列表)。 有关更多详细信息,请参阅 LLaVA:大型语言和视觉助手。 Ollama 消息 API 提供了一个”图像”参数,用于将 base64 编码的图像列表与消息合并。 Spring AI 的 Message 接口通过引入 Media 类型来促进多模态 AI 模型。 此类型包含有关消息中媒体附件的数据和详细信息,利用 Spring 的org.springframework.util.MimeType 和 org.springframework.core.io.Resource 来获取原始媒体数据。
以下是从 OllamaChatModelMultimodalIT.java 中摘录的一个简单代码示例,说明了用户文本与图像的融合。
multimodal.test.png 图像作为输入:

结构化输出
Ollama 提供自定义结构化输出 API,可确保你的模型生成的响应严格符合你提供的JSON Schema。
除了现有的与 Spring AI 模型无关的结构化输出转换器之外,这些 API 还提供了增强的控制和精度。
配置
Spring AI 允许你使用OllamaOptions 构建器以编程方式配置响应格式。
使用聊天选项构建器
你可以使用OllamaOptions 构建器以编程方式设置响应格式,如下所示:
与 BeanOutputConverter 实用程序集成
你可以利用现有的 BeanOutputConverter 实用程序从你的域对象自动生成 JSON Schema,然后将结构化响应转换为特定于域的实例:确保使用
@JsonProperty(required = true,...) 注释来生成准确标记字段为 required 的模式。
尽管这对于 JSON Schema 是可选的,但建议这样做以使结构化响应正常工作。OpenAI API 兼容性
Ollama 与 OpenAI API 兼容,你可以使用 Spring AI OpenAI 客户端与 Ollama 通信并使用工具。 为此,你需要将 OpenAI 基本 URL 配置为你的 Ollama 实例:spring.ai.openai.chat.base-url=http://localhost:11434 并选择提供的 Ollama 模型之一:spring.ai.openai.chat.options.model=mistral。

HuggingFace 模型
Ollama 可以开箱即用地访问所有 GGUF Hugging Face 聊天模型。 你可以按名称拉取这些模型中的任何一个:ollama pull hf.co/<用户名>/<模型仓库> 或配置自动拉取策略:自动拉取模型:
spring.ai.ollama.chat.options.model:指定要使用的 Hugging Face GGUF 模型。spring.ai.ollama.init.pull-model-strategy=always:(可选)在启动时启用自动模型拉取。 对于生产环境,你应该预先下载模型以避免延迟:ollama pull hf.co/bartowski/gemma-2-2b-it-GGUF。
示例控制器
创建一个新的 Spring Boot 项目,并将spring-ai-starter-model-ollama 添加到你的 pom (或 gradle) 依赖项中。
在 src/main/resources 目录下添加一个 application.yaml 文件,以启用和配置 Ollama 聊天模型:
OllamaChatModel 实现,你可以将其注入到你的类中。
以下是一个简单的 @RestController 类的示例,该类使用聊天模型进行文本生成:
手动配置
如果你不想使用 Spring Boot 自动配置,可以在应用程序中手动配置OllamaChatModel。
OllamaChatModel 实现了 ChatModel 和 StreamingChatModel,并使用低级 API连接到 Ollama 服务。
要使用它,请将 spring-ai-ollama 依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中:
- Maven
- Gradle
OllamaChatModel 实例并将其用于发送文本生成请求:
OllamaOptions 为所有聊天请求提供配置信息。
低级 OllamaApi 客户端
OllamaApi 提供了轻量级的 Java 客户端,用于 Ollama 聊天补全 API。 以下类图说明了OllamaApi 聊天接口和构建块:

OllamaApi 是一个低级 API,不建议直接使用。请改用 OllamaChatModel。文档有误?请协助编辑
发现文档问题?点击此处直接在 GitHub 上编辑并提交 PR,帮助我们改进文档!