Ollama
本站(springdoc.cn)中的内容来源于 spring.io ,原始版权归属于 spring.io。由 springdoc.cn 进行翻译,整理。可供个人学习、研究,未经许可,不得进行任何转载、商用或与之相关的行为。 商标声明:Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。 |
通过 Ollama 可在本地运行多种大语言模型(LLM)并进行文本生成。Spring AI 通过 OllamaChatModel
API支持 Ollama 的聊天补全功能。
Ollama 还提供与 OpenAI API 兼容的端点。OpenAI API 兼容性 章节说明了如何使用 Spring AI OpenAI 连接 Ollama 服务器。 |
先决条件
首先需要访问 Ollama 实例,可通过以下方式实现:
-
在本地机器 下载并安装 Ollama
-
通过
Testcontainers
配置和运行 Ollama -
通过 Kubernetes Service Bindings 绑定 Ollama 实例
你可以从 Ollama 模型库 拉取应用程序所需的模型:
ollama pull <model-name>
你还可以拉取数千个免费的 GGUF 格式 Hugging Face 模型:
ollama pull hf.co/<username>/<model-repository>
或者,你可以启用自动下载所需模型的选项:自动拉取模型。
自动配置
Spring AI 自动配置及 Starter 模块的 artifact 名称已发生重大变更。具体升级说明请参阅 更新文档。 |
Spring AI 为 Ollama 聊天集成提供 Spring Boot 自动配置。要启用该功能,请将以下依赖项添加到项目的 Maven pom.xml
或 Gradle build.gradle
构建文件中:
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}
请参考 依赖管理 章节,将 Spring AI BOM 添加到构建文件中。 |
基础配置
前缀 spring.ai.ollama
是配置 Ollama 连接的属性前缀。
属性 |
说明 |
默认值 |
spring.ai.ollama.base-url |
Ollama API 服务器运行的 Base URL。 |
以下是初始化 Ollama 集成及 自动拉取模型 的配置属性。
Property |
Description |
Default |
spring.ai.ollama.init.pull-model-strategy |
是否在启动时拉取模型及拉取方式。 |
|
spring.ai.ollama.init.timeout |
拉取模型的最大等待时长。 |
|
spring.ai.ollama.init.max-retries |
模型拉取操作的最大重试次数。 |
|
spring.ai.ollama.init.chat.include |
初始化任务中需包含的模型类型。 |
|
spring.ai.ollama.init.chat.additional-models |
除默认属性配置外需额外初始化的模型列表。 |
|
聊天配置
聊天自动配置的启用/禁用现在通过顶级属性配置,前缀为
此项变更是为了支持多模型配置。 |
前缀 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 |
返回响应的格式。当前唯一支持的值为 |
- |
spring.ai.ollama.chat.options.keep_alive |
控制模型在请求完成后保留在内存中的时长。 |
5m |
其余选项属性基于 Ollama 有效参数与值 和 Ollama 类型,默认值遵循 Ollama 类型默认 设置。
属性 |
说明 |
默认值 |
spring.ai.ollama.chat.options.numa |
是否启用NUMA(非统一内存访问)。 |
false |
spring.ai.ollama.chat.options.num-ctx |
设置用于生成下一个 Token 的上下文窗口大小。 |
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 |
返回所有 Token 的逻辑值(logits),而不仅是最后一个。要使补全结果返回对数概率(logprobs),此参数必须设为 |
- |
spring.ai.ollama.chat.options.vocab-only |
仅加载词汇表,不加载权重。 |
- |
spring.ai.ollama.chat.options.use-mmap |
默认情况下,模型通过内存映射(mmap)加载,这使得系统能按需仅加载模型必要部分。但当模型大小超过系统总内存容量或可用内存不足时,使用 mmap 可能增加页面换出(pageout)风险,进而影响性能。禁用 mmap 会导致加载时间变长,但在未启用 mlock 时可减少页面换出。注意:若模型超过总内存容量,关闭 mmap 将导致模型无法加载。 |
null |
spring.ai.ollama.chat.options.use-mlock |
将模型锁定在内存中(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 |
生成文本时的最大预测 Token 数(-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 表示 Token 被考虑的最低概率(相对于最可能 Token 的概率)。例如 p=0.05 时,若最可能 Token 概率为 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 将停止生成文本并返回。可通过在 modelfile 中指定多个独立 stop 参数来设置多个停止模式。 |
- |
spring.ai.ollama.chat.options.functions |
函数名称列表,用于在单次提示请求中启用函数调用。这些名称对应的函数必须存在于 |
- |
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
调用添加新的请求专属选项来覆盖默认配置。例如,针对特定请求覆盖默认模型和温度值:
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates.",
OllamaOptions.builder()
.model(OllamaModel.LLAMA3_1)
.temperature(0.4)
.build()
));
除模型专属的 OllamaOptions 外,你还可使用通过 ChatOptionsBuilder#builder() 创建的可移植 ChatOptions 实例。 |
自动拉取模型功能
Spring AI Ollama 能在 Ollama 实例缺少所需模型时自动拉取。该特性对开发测试及部署到新环境特别有用。
你还可以按名称拉取数千个免费的 GGUF 格式 Hugging Face 模型。 |
模型拉取提供三种策略:
-
always
(定义于PullModelStrategy.ALWAYS
):始终拉取模型,即使已存在。适用于确保使用模型的最新版本。 -
when_missing
(定义于PullModelStrategy.WHEN_MISSING
):仅当模型不存在时拉取。可能导致使用旧版模型。 -
never
(定义于PullModelStrategy.NEVER
):禁止自动拉取模型。
由于模型下载可能存在延迟,生产环境不建议启用自动拉取。建议预先评估并手动下载所需模型。 |
所有通过配置属性和默认选项定义的模型均可在启动时自动拉取。你可通过以下配置属性设置拉取策略、超时时间及最大重试次数:
spring:
ai:
ollama:
init:
pull-model-strategy: always
timeout: 60s
max-retries: 1
应用程序将等待所有指定模型在 Ollama 中可用后才完成初始化。根据模型大小和网络连接速度,这可能显著延长应用的启动时间。 |
你可以在启动时初始化额外模型,这对运行时动态使用的模型特别有用:
spring:
ai:
ollama:
init:
pull-model-strategy: always
chat:
additional-models:
- llama3.2
- qwen2.5
若需仅对特定类型模型应用拉取策略,可从初始化任务中排除聊天模型:
spring:
ai:
ollama:
init:
pull-model-strategy: always
chat:
include: false
此配置将对除聊天模型外的所有模型应用拉取策略。
函数调用
你可为 OllamaChatModel
注册自定义 Java 函数,使 Ollama 模型能智能输出包含参数的 JSON 对象来调用一个或多个注册函数。这是将 LLM 能力与外部工具及 API 连接的强大技术。了解更多关于 工具调用 的信息。
使用函数调用功能需 Ollama 0.2.8 或更高版本,流式模式下使用需 Ollama 0.4.6 或更高版本。 |
多模态
多模态指模型同时理解和处理多种来源信息的能力,包括文本、图像、音频及其他数据格式。
Ollama 中支持多模态的模型包括 LLaVA 和 BakLLaVA(查看 完整列表)。更多细节请参阅 LLaVA: 大型语言与视觉助手文档。
Ollama Message 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.
结构化输出
Ollama
提供自定义 结构化输 API,确保模型生成严格符合你提供的 JSON Schema 的响应。除现有的 Spring AI 模型无关 结构化输出转换器 外,这些 API 提供更精细的控制与精确度。
配置
Spring AI 支持通过 OllamaOptions
Builder 以编程方式配置响应格式。
使用聊天选项 Builder
你可以通过 OllamaOptions
Builder 以编程方式设置响应格式,如下所示:
String jsonSchema = """
{
"type": "object",
"properties": {
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"explanation": { "type": "string" },
"output": { "type": "string" }
},
"required": ["explanation", "output"],
"additionalProperties": false
}
},
"final_answer": { "type": "string" }
},
"required": ["steps", "final_answer"],
"additionalProperties": false
}
""";
Prompt prompt = new Prompt("how can I solve 8x + 7 = -23",
OllamaOptions.builder()
.model(OllamaModel.LLAMA3_2.getName())
.format(new ObjectMapper().readValue(jsonSchema, Map.class))
.build());
ChatResponse response = this.ollamaChatModel.call(this.prompt);
集成 BeanOutputConverter 工具类
你可利用现有 BeanOutputConverter 工具类自动从领域对象生成 JSON Schema,并将结构化响应转换为领域实例:
record MathReasoning(
@JsonProperty(required = true, value = "steps") Steps steps,
@JsonProperty(required = true, value = "final_answer") String finalAnswer) {
record Steps(
@JsonProperty(required = true, value = "items") Items[] items) {
record Items(
@JsonProperty(required = true, value = "explanation") String explanation,
@JsonProperty(required = true, value = "output") String output) {
}
}
}
var outputConverter = new BeanOutputConverter<>(MathReasoning.class);
Prompt prompt = new Prompt("how can I solve 8x + 7 = -23",
OllamaOptions.builder()
.model(OllamaModel.LLAMA3_2.getName())
.format(outputConverter.getJsonSchemaMap())
.build());
ChatResponse response = this.ollamaChatModel.call(this.prompt);
String content = this.response.getResult().getOutput().getText();
MathReasoning mathReasoning = this.outputConverter.convert(this.content);
请确保使用 @JsonProperty(required = true,…) 注解生成 Schema,以精确标记必填字段。虽然这对 JSON Schema 是可选的,但建议添加以保证结构化响应的正确性。
|
OpenAI API 兼容性
Ollama 兼容 OpenAI API,你可使用 Spring AI OpenAI 客户端与 Ollama 交互并调用工具。需配置以下参数:
-
将 OpenAI Base 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=hf.co/bartowski/gemma-2-2b-it-GGUF
spring.ai.ollama.init.pull-model-strategy=always
-
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
示例 Controller
新建 Spring Boot 项目并在 pom(或 gradle)依赖中添加 spring-ai-starter-model-ollama
。
在 src/main/resources
目录下添加 application.yaml
文件以启用并配置 Ollama 聊天模型:
spring:
ai:
ollama:
base-url: http://localhost:11434
chat:
options:
model: mistral
temperature: 0.7
将 base-url 替换为你的 Ollama 服务器 URL。
|
这将创建一个可注入到类中的 OllamaChatModel
实现。以下是一个使用该聊天模型进行文本生成的简单 @RestController
类示例:
@RestController
public class ChatController {
private final OllamaChatModel chatModel;
@Autowired
public ChatController(OllamaChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generate")
public Map<String,String> generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", this.chatModel.call(message));
}
@GetMapping("/ai/generateStream")
public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}
手动配置
若不使用 Spring Boot 自动配置,可手动配置 OllamaChatModel
。 OllamaChatModel 实现了 ChatModel
和 StreamingChatModel
接口,通过 底层 OllamaApi 客户端 连接 Ollama 服务。
要使用该功能,请将 spring-ai-ollama
依赖添加到项目的 Maven pom.xml
或 Gradle build.gradle
构建文件中:
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-ollama</artifactId>
</dependency>
dependencies {
implementation 'org.springframework.ai:spring-ai-ollama'
}
请参考 依赖管理 章节,将 Spring AI BOM 添加到构建文件中。 |
spring-ai-ollama 依赖还提供对 OllamaEmbeddingModel 的访问。有关 OllamaEmbeddingModel 的更多信息,请参阅 Ollama 嵌入模型 章节。
|
接下来,创建 OllamaChatModel
实例并发送文本生成请求:
var ollamaApi = OllamaApi.builder().build();
var chatModel = OllamaChatModel.builder()
.ollamaApi(ollamaApi)
.defaultOptions(
OllamaOptions.builder()
.model(OllamaModel.MISTRAL)
.temperature(0.9)
.build())
.build();
ChatResponse response = this.chatModel.call(
new Prompt("Generate the names of 5 famous pirates."));
// Or with streaming responses
Flux<ChatResponse> response = this.chatModel.stream(
new Prompt("Generate the names of 5 famous pirates."));
OllamaOptions
为所有聊天请求提供配置信息。
底层 OllamaApi 客户端
OllamaApi 为 Ollama 聊天补全 API 提供轻量级 Java 客户端。
以下类图展示 OllamaApi
聊天接口及核心组件:

OllamaApi 是底层 API,不建议直接使用。请改用 OllamaChatModel 。
|
以下代码片段展示如何以编程方式使用该 API:
OllamaApi ollamaApi = new OllamaApi("YOUR_HOST:YOUR_PORT");
// Sync request
var request = ChatRequest.builder("orca-mini")
.stream(false) // not streaming
.messages(List.of(
Message.builder(Role.SYSTEM)
.content("You are a geography teacher. You are talking to a student.")
.build(),
Message.builder(Role.USER)
.content("What is the capital of Bulgaria and what is the size? "
+ "What is the national anthem?")
.build()))
.options(OllamaOptions.builder().temperature(0.9).build())
.build();
ChatResponse response = this.ollamaApi.chat(this.request);
// Streaming request
var request2 = ChatRequest.builder("orca-mini")
.ttream(true) // streaming
.messages(List.of(Message.builder(Role.USER)
.content("What is the capital of Bulgaria and what is the size? " + "What is the national anthem?")
.build()))
.options(OllamaOptions.builder().temperature(0.9).build().toMap())
.build();
Flux<ChatResponse> streamingResponse = this.ollamaApi.streamingChat(this.request2);