Ollama 聊天
使用 Ollama,你可以在本地运行各种大型语言模型 (LLM) 并从中生成文本。
Spring AI 支持 Ollama 聊天补全功能,并提供 OllamaChatModel
API。
Ollama 也提供 OpenAI API 兼容端点。 请查看 OpenAI API 兼容性 部分,了解如何使用 Spring AI OpenAI 集成与 Ollama 服务器通信。
前提条件
你首先需要访问 Ollama 实例。有几种选择,包括以下几种:
- 在你的本地计算机上下载并安装 Ollama。
- 通过 Testcontainers 配置并运行 Ollama。
- 通过 Kubernetes 服务绑定绑定到 Ollama 实例。
你可以从 Ollama 模型库中拉取要在应用程序中使用的模型:
你还可以拉取数千个免费的 GGUF Hugging Face 模型中的任何一个:
或者,你可以启用自动下载任何所需模型的选项:自动拉取模型。
自动配置
Spring AI 自动配置、启动器模块的构件名称发生了重大变化。 有关更多信息,请参阅升级说明。
Spring AI 为 Ollama 聊天集成提供 Spring Boot 自动配置。
要启用它,请将以下依赖项添加到项目的 Maven pom.xml
或 Gradle build.gradle
构建文件中:
请参阅依赖管理部分,将 Spring AI BOM 添加到你的构建文件中。
基本属性
前缀 spring.ai.ollama
是用于配置与 Ollama 连接的属性前缀。
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.ollama.base-url | Ollama API 服务器运行的基本 URL。 | http://localhost:11434 |
以下是用于初始化 Ollama 集成和自动拉取模型的属性。
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.ollama.init.pull-model-strategy | 是否在启动时拉取模型以及如何拉取。 | never |
spring.ai.ollama.init.timeout | 等待模型拉取的时间。 | 5m |
spring.ai.ollama.init.max-retries | 模型拉取操作的最大重试次数。 | 0 |
spring.ai.ollama.init.chat.include | 在初始化任务中包含此类型的模型。 | true |
spring.ai.ollama.init.chat.additional-models | 除了通过默认属性配置的模型之外,还要初始化的其他模型。 | [] |
聊天属性
聊天自动配置的启用和禁用现在通过前缀为 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 聊天模型的高级请求参数:
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.ollama.chat.enabled (已移除且不再有效) | 启用 Ollama 聊天模型。 | true |
spring.ai.model.chat | 启用 Ollama 聊天模型。 | ollama |
spring.ai.ollama.chat.options.model | 要使用的支持的模型的名称。 | mistral |
spring.ai.ollama.chat.options.format | 返回响应的格式。目前,唯一接受的值是 json | - |
spring.ai.ollama.chat.options.keep_alive | 控制请求后模型在内存中保留多长时间 | 5m |
其余 options
属性基于 Ollama 有效参数和值 和 Ollama 类型。默认值基于 Ollama 类型默认值。
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.ollama.chat.options.numa | 是否使用 NUMA。 | false |
spring.ai.ollama.chat.options.num-ctx | 设置用于生成下一个标记的上下文窗口的大小。 | 2048 |
spring.ai.ollama.chat.options.num-batch | 提示处理最大批处理大小。 | 512 |
spring.ai.ollama.chat.options.num-gpu | 要发送到 GPU 的层数。在 macOS 上,默认为 1 以启用 metal 支持,0 以禁用。此处的 1 表示应动态设置 NumGPU | -1 |
spring.ai.ollama.chat.options.main-gpu | 使用多个 GPU 时,此选项控制哪个 GPU 用于小型张量,对于这些张量,跨所有 GPU 拆分计算的开销不值得。相关 GPU 将使用稍多的 VRAM 来存储用于临时结果的暂存缓冲区。 | 0 |
spring.ai.ollama.chat.options.low-vram | - | false |
spring.ai.ollama.chat.options.f16-kv | - | true |
spring.ai.ollama.chat.options.logits-all | 返回所有标记的 logits,而不仅仅是最后一个。要使补全返回 logprobs,此项必须为 true。 | - |
spring.ai.ollama.chat.options.vocab-only | 仅加载词汇表,而不加载权重。 | - |
spring.ai.ollama.chat.options.use-mmap | 默认情况下,模型会映射到内存中,这允许系统根据需要仅加载模型的必要部分。但是,如果模型大于你的总 RAM 量,或者你的系统可用内存不足,则使用 mmap 可能会增加页面换出的风险,从而对性能产生负面影响。禁用 mmap 会导致加载时间变慢,但如果你不使用 mlock,则可能会减少页面换出。请注意,如果模型大于总 RAM 量,则关闭 mmap 将阻止模型完全加载。 | null |
spring.ai.ollama.chat.options.use-mlock | 将模型锁定在内存中,防止在内存映射时将其换出。这可以提高性能,但会牺牲内存映射的一些优势,因为它需要更多 RAM 才能运行,并且随着模型加载到 RAM 中,可能会减慢加载时间。 | false |
spring.ai.ollama.chat.options.num-thread | 设置计算期间要使用的线程数。默认情况下,Ollama 会检测此值以获得最佳性能。建议将此值设置为系统具有的物理 CPU 内核数(而不是逻辑内核数)。0 = 让运行时决定 | 0 |
spring.ai.ollama.chat.options.num-keep | - | 4 |
spring.ai.ollama.chat.options.seed | 设置用于生成的随机数种子。将其设置为特定数字将使模型为相同的提示生成相同的文本。 | -1 |
spring.ai.ollama.chat.options.num-predict | 生成文本时要预测的最大标记数。(-1 = 无限生成,-2 = 填充上下文) | -1 |
spring.ai.ollama.chat.options.top-k | 降低生成无意义内容的概率。较高的值(例如 100)将提供更多样化的答案,而较低的值(例如 10)将更保守。 | 40 |
spring.ai.ollama.chat.options.top-p | 与 top-k 一起使用。较高的值(例如 0.95)将导致更多样化的文本,而较低的值(例如 0.5)将生成更集中和保守的文本。 | 0.9 |
spring.ai.ollama.chat.options.min-p | top_p 的替代方案,旨在确保质量和多样性的平衡。参数 p 表示要考虑的标记的最小概率,相对于最可能标记的概率。例如,当 p=0.05 且最可能标记的概率为 0.9 时,值小于 0.045 的 logits 将被过滤掉。 | 0.0 |
spring.ai.ollama.chat.options.tfs-z | 无尾采样用于减少输出中不太可能的标记的影响。较高的值(例如 2.0)将更多地减少影响,而值 1.0 将禁用此设置。 | 1.0 |
spring.ai.ollama.chat.options.typical-p | - | 1.0 |
spring.ai.ollama.chat.options.repeat-last-n | 设置模型向后查看多远以防止重复。(默认值:64,0 = 禁用,-1 = num_ctx) | 64 |
spring.ai.ollama.chat.options.temperature | 模型的温度。增加温度会使模型回答更具创造性。 | 0.8 |
spring.ai.ollama.chat.options.repeat-penalty | 设置对重复的惩罚强度。较高的值(例如 1.5)将更强烈地惩罚重复,而较低的值(例如 0.9)将更宽松。 | 1.1 |
spring.ai.ollama.chat.options.presence-penalty | - | 0.0 |
spring.ai.ollama.chat.options.frequency-penalty | - | 0.0 |
spring.ai.ollama.chat.options.mirostat | 启用 Mirostat 采样以控制困惑度。(默认值:0,0 = 禁用,1 = Mirostat,2 = Mirostat 2.0) | 0 |
spring.ai.ollama.chat.options.mirostat-tau | 控制输出的连贯性和多样性之间的平衡。较低的值将导致更集中和连贯的文本。 | 5.0 |
spring.ai.ollama.chat.options.mirostat-eta | 影响算法对生成文本反馈的响应速度。较低的学习率将导致较慢的调整,而较高的学习率将使算法更具响应性。 | 0.1 |
spring.ai.ollama.chat.options.penalize-newline | - | true |
spring.ai.ollama.chat.options.stop | 设置要使用的停止序列。遇到此模式时,LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的 stop 参数来设置多个停止模式。 | - |
spring.ai.ollama.chat.options.functions | 在单个提示请求中启用函数调用的函数列表(按其名称标识)。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 | - |
spring.ai.ollama.chat.options.proxy-tool-calls | 如果为 true,Spring AI 将不会在内部处理函数调用,而是将它们代理到客户端。然后由客户端负责处理函数调用,将它们分派到适当的函数,并返回结果。如果为 false(默认值),Spring AI 将在内部处理函数调用。仅适用于具有函数调用支持的聊天模型 | false |
所有以 spring.ai.ollama.chat.options
为前缀的属性都可以在运行时通过向 Prompt
调用添加特定于请求的聊天选项来覆盖。
运行时选项
OllamaOptions.java 类提供模型配置,例如要使用的模型、温度等。
在启动时,可以使用 OllamaChatModel(api, options)
构造函数或 spring.ai.ollama.chat.options.*
属性配置默认选项。
在运行时,你可以通过向 Prompt
调用添加新的、特定于请求的选项来覆盖默认选项。
例如,要为特定请求覆盖默认模型和温度:
除了特定于模型的 OllamaOptions之外,你还可以使用通过 ChatOptionsBuilder#builder() 创建的可移植 ChatOptions 实例。
自动拉取模型
当 Ollama 实例中没有可用模型时,Spring AI Ollama 可以自动拉取模型。 此功能对于开发和测试以及将应用程序部署到新环境特别有用。
你还可以按名称拉取数千个免费的 GGUF Hugging Face 模型中的任何一个。
有三种拉取模型的策略:
always
(在PullModelStrategy.ALWAYS
中定义):始终拉取模型,即使它已经可用。用于确保你使用的是最新版本的模型。when_missing
(在PullModelStrategy.WHEN_MISSING
中定义):仅当模型尚不可用时才拉取模型。这可能会导致使用较旧版本的模型。never
(在PullModelStrategy.NEVER
中定义):从不自动拉取模型。
由于下载模型时可能会出现延迟,因此不建议在生产环境中使用自动拉取。相反,请考虑提前评估和预下载必要的模型。
所有通过配置属性和默认选项定义的模型都可以在启动时自动拉取。 你可以使用配置属性配置拉取策略、超时和最大重试次数:
在 Ollama 中所有指定的模型都可用之前,应用程序不会完成其初始化。根据模型大小和互联网连接速度,这可能会显著减慢应用程序的启动时间。
你可以在启动时初始化其他模型,这对于在运行时动态使用的模型很有用:
如果你只想将拉取策略应用于特定类型的模型,则可以从初始化任务中排除聊天模型:
此配置将拉取策略应用于除聊天模型之外的所有模型。
函数调用
你可以使用 OllamaChatModel
注册自定义 Java 函数,并让 Ollama 模型智能地选择输出一个 JSON 对象,其中包含调用一个或多个已注册函数的参数。
这是将 LLM 功能与外部工具和 API 连接起来的强大技术。
阅读有关工具调用的更多信息。
你需要 Ollama 0.2.8 或更高版本才能使用函数调用功能,需要 Ollama 0.4.6 或更高版本才能在流模式下使用它们。
多模态
多模态是指模型同时理解和处理来自各种来源的信息的能力,包括文本、图像、音频和其他数据格式。
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
。
请查看 OllamaWithOpenAiChatModelIT.java 测试,获取通过 Spring AI OpenAI 使用 Ollama 的示例。
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 聊天模型:
将 base-url
替换为你的 Ollama 服务器 URL。
这将创建一个 OllamaChatModel
实现,你可以将其注入到你的类中。
以下是一个简单的 @RestController
类的示例,该类使用聊天模型进行文本生成:
手动配置
如果你不想使用 Spring Boot 自动配置,可以在应用程序中手动配置 OllamaChatModel
。
OllamaChatModel 实现了 ChatModel
和 StreamingChatModel
,并使用低级 API连接到 Ollama 服务。
要使用它,请将 spring-ai-ollama
依赖项添加到项目的 Maven pom.xml
或 Gradle build.gradle
构建文件中:
请参阅依赖管理部分,将 Spring AI BOM 添加到你的构建文件中。
spring-ai-ollama
依赖项还提供对 OllamaEmbeddingModel
的访问。
有关 OllamaEmbeddingModel
的更多信息,请参阅 Ollama 嵌入模型 部分。
接下来,创建一个 OllamaChatModel
实例并将其用于发送文本生成请求:
OllamaOptions
为所有聊天请求提供配置信息。
低级 OllamaApi 客户端
OllamaApi 提供了轻量级的 Java 客户端,用于 Ollama 聊天补全 API。
以下类图说明了 OllamaApi
聊天接口和构建块:
OllamaApi
是一个低级 API,不建议直接使用。请改用 OllamaChatModel
。
以下是一个简单的代码片段,展示了如何以编程方式使用 API:
文档有误?请协助编辑
发现文档问题?点击此处直接在 GitHub 上编辑并提交 PR,帮助我们改进文档!