此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3spring-doc.cadn.net.cn

Ollama Chat

使用Ollama,您可以在本地运行各种大型语言模型(LLMs)并生成文本。 Spring AI 支持通过OllamaChatModel API 的 Ollama 对话完成功能。spring-doc.cadn.net.cn

Ollama 提供了一个与 OpenAI API 兼容的端点。 OpenAI API 兼容性 部分解释了如何使用 Spring AI OpenAI 连接到一个 Ollama 服务器。

前置条件

您首先需要访问一个Ollama 实例。有几种选择,包括以下内容:spring-doc.cadn.net.cn

您可以从Ollama模型库拉取您想要在应用程序中使用的模型:spring-doc.cadn.net.cn

ollama pull <model-name>

您也可以拉取数千个免费的GGUF Hugging Face 模型:spring-doc.cadn.net.cn

ollama pull hf.co/<username>/<model-repository>

您可以启用自动下载任何所需模型的选项:自动拉取模型spring-doc.cadn.net.cn

Auto-configuration

Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。spring-doc.cadn.net.cn

Spring AI 提供了对 Ollama 聊天集成的 Spring Boot 自动配置。 要启用它,请将以下依赖项添加到项目中的 Maven pom.xml 或 Gradle build.gradle 构建文件中:spring-doc.cadn.net.cn

<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添加到您的构建文件中。

基属性

`0` 前缀是配置连接到 Ollama 的属性前缀。spring-doc.cadn.net.cn

<property> </property>spring-doc.cadn.net.cn

<description> </description>spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.base-urlspring-doc.cadn.net.cn

Ollama API服务器正在运行的基础URL。spring-doc.cadn.net.cn

http://localhost:11434spring-doc.cadn.net.cn

这里用于初始化Ollama集成和自动拉取模型的属性。spring-doc.cadn.net.cn

<property> </property>spring-doc.cadn.net.cn

<description> </description>spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.init.pull-model-strategyspring-doc.cadn.net.cn

是否在启动时拉取模型以及如何操作。spring-doc.cadn.net.cn

neverspring-doc.cadn.net.cn

spring.ai.ollama.init.timeoutspring-doc.cadn.net.cn

等待模型拉取所需的时间。spring-doc.cadn.net.cn

5mspring-doc.cadn.net.cn

spring.ai.ollama.init.max-retriesspring-doc.cadn.net.cn

模型拉取操作的最大重试次数。spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.init.chat.includespring-doc.cadn.net.cn

包含此类模型在内的初始化任务。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.ollama.init.chat.additional-modelsspring-doc.cadn.net.cn

除了默认属性配置之外还需要初始化的其他模型。spring-doc.cadn.net.cn

[]spring-doc.cadn.net.cn

聊天属性

现在通过带有前缀spring.ai.model.chat的顶级属性来配置聊天自动配置的启用和禁用。spring-doc.cadn.net.cn

要启用,请设置:spring.ai.model.chat=ollama(默认已启用)spring-doc.cadn.net.cn

要禁用,请设置 spring.ai.model.chat=none(或任何与 ollama 不匹配的值)spring-doc.cadn.net.cn

此更改是为了允许配置多个模型。spring-doc.cadn.net.cn

The prefix spring.ai.ollama.chat.options 是配置 Ollama 聊天模型的属性前缀。 它包括 Ollama 请求(高级)参数如 modelkeep-aliveformat 以及 Ollama 模型 options 属性。spring-doc.cadn.net.cn

这里是Ollama聊天模型的高级请求参数:spring-doc.cadn.net.cn

<property> </property>spring-doc.cadn.net.cn

<description> </description>spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.chat.enabled (已移除且不再有效)spring-doc.cadn.net.cn

启用Ollama聊天模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.model.chatspring-doc.cadn.net.cn

启用Ollama聊天模型。spring-doc.cadn.net.cn

Ollamaspring-doc.cadn.net.cn

spring.ai.ollama.chat.options.modelspring-doc.cadn.net.cn

使用的支持的模型名称。spring-doc.cadn.net.cn

mistralspring-doc.cadn.net.cn

spring.ai.ollama.chat.options.formatspring-doc.cadn.net.cn

返回响应的格式。接受"json"(任意JSON结构)或JSON模式对象(强制结构)。详情请参见结构化输出spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.keep_alivespring-doc.cadn.net.cn

控制模型在响应请求后将在内存中保留多长时间spring-doc.cadn.net.cn

5mspring-doc.cadn.net.cn

<property> </property>spring-doc.cadn.net.cn

<description> </description>spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.numaspring-doc.cadn.net.cn

是否使用NUMA。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.ollama.chat.options.num-ctxspring-doc.cadn.net.cn

设置用于生成下一个标记的上下文窗口大小。spring-doc.cadn.net.cn

2048spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.num-batchspring-doc.cadn.net.cn

提示处理最大批量大小。spring-doc.cadn.net.cn

512spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.num-gpuspring-doc.cadn.net.cn

发送到GPU的数量。在macOS上,默认值为1以启用metal支持,0以禁用。这里的1表示NumGPU应该动态设置。spring-doc.cadn.net.cn

-1spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.main-gpuspring-doc.cadn.net.cn

当使用多个GPU时,此选项控制对于计算拆分到所有GPU上的开销不值得的小张量,在哪个GPU上进行处理。该GPU会稍微多占用一些VRAM来存储临时结果的缓冲区。spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.low-vramspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.ollama.chat.options.f16-kvspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.ollama.chat.options.logits-allspring-doc.cadn.net.cn

返回所有标记的logits,而不仅仅是最后一个。要使完成返回logprobs,此设置必须为true。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.vocab-onlyspring-doc.cadn.net.cn

仅加载词汇表,不加载权重。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.use-mmapspring-doc.cadn.net.cn

默认情况下,模型会被映射到内存中,这使得系统可以根据需要仅加载必要的模型部分。然而,如果模型大小超过了您的总内存容量或系统可用内存较低时,使用mmap可能会增加换页的风险,从而负面影响性能。禁用mmap会导致加载时间变慢,但如果未启用mlock,则可能减少换页次数。请注意,如果模型大小超过总内存容量,关闭mmap将导致模型无法加载。spring-doc.cadn.net.cn

nullspring-doc.cadn.net.cn

spring.ai.ollama.chat.options.use-mlockspring-doc.cadn.net.cn

锁定模型在内存中,防止其在内存映射时被交换出去。这可以提高性能,但会牺牲一些内存映射的优势,因为它需要更多的RAM来运行,并且可能在模型加载到RAM时减慢加载时间。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.ollama.chat.options.num-threadspring-doc.cadn.net.cn

设置在计算过程中使用的线程数。默认情况下,Ollama 将检测此值以实现最佳性能。建议将此值设置为您系统中的物理 CPU 核心数量(而不是逻辑核心的数量)。0 = 由运行时决定spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.num-keepspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

4spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.seedspring-doc.cadn.net.cn

设置用于生成的随机数种子。将此值设置为特定数字,可以在相同的提示下使模型生成相同的文字。spring-doc.cadn.net.cn

-1spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.num-predictspring-doc.cadn.net.cn

当生成文本时预测的最大токен数。(-1 表示无限生成,-2 表示填充上下文)spring-doc.cadn.net.cn

-1spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.top-kspring-doc.cadn.net.cn

减小生成onsense的概率。数值越大(例如,100),答案的多样性越高;数值越小(例如,10),答案就越保守。spring-doc.cadn.net.cn

40spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.top-pspring-doc.cadn.net.cn

与 top-k 共同工作。较高的值(例如,0.95)会导致生成更多样化的文本,而较低的值(例如,0.5)将生成更加聚焦且保守的文本。spring-doc.cadn.net.cn

0.9spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.min-pspring-doc.cadn.net.cn

替代top_p,旨在确保质量和多样性的平衡。参数p表示一个Tokens被考虑的最小概率,相对于最可能Tokens的概率。例如,在p=0.05且最可能Tokens的概率为0.9的情况下,值小于0.045的logits会被过滤掉。spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.tfs-zspring-doc.cadn.net.cn

无尾采样用于减少较少可能出现的Tokens对输出的影响。更高的值(例如,2.0)会更多地降低这些影响,而值为1.0则禁用此设置。spring-doc.cadn.net.cn

1.0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.typical-pspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

1.0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.repeat-last-nspring-doc.cadn.net.cn

设置模型回溯的长度,以防止重复。默认值:64,0表示禁用,-1表示使用上下文长度。spring-doc.cadn.net.cn

64spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.temperaturespring-doc.cadn.net.cn

模型的温度。提高温度会使模型的回答更具创造性。spring-doc.cadn.net.cn

0.8spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.repeat-penaltyspring-doc.cadn.net.cn

设置重复的惩罚力度。较高的值(例如,1.5)将更严格地惩罚重复情况,而较低的值(例如,0.9)将更为宽容。spring-doc.cadn.net.cn

1.1spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.presence-penaltyspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.frequency-penaltyspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.mirostatspring-doc.cadn.net.cn

启用Mirostat采样以控制困惑度。(默认: 0,0 = 禁用,1 = Mirostat,2 = Mirostat 2.0)spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.mirostat-tauspring-doc.cadn.net.cn

控制输出的连贯性和多样性之间的平衡。数值较低会导致生成的文字更加集中和连贯。spring-doc.cadn.net.cn

5.0spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.mirostat-etaspring-doc.cadn.net.cn

影响算法对生成文本反馈的响应速度。学习率较低会导致调整较慢,而较高的学习率会使算法更加灵敏。spring-doc.cadn.net.cn

0.1spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.penalize-newlinespring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.ollama.chat.options.stopspring-doc.cadn.net.cn

设置要使用的停止序列。当遇到此模式时,LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的停止参数来设置多个停止模式。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.tool-namesspring-doc.cadn.net.cn

使用名称标识的工具列表,以在单个提示请求中启用功能调用。具有这些名称的工具必须存在于ToolCallback注册表中。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.tool-callbacksspring-doc.cadn.net.cn

使用回调注册与ChatModel相关的工具。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.internal-tool-execution-enabledspring-doc.cadn.net.cn

如果为假,Spring AI 将不会内部处理工具调用,而是将它们代理给客户端。然后需要由客户端负责处理这些工具调用、将其分派到适当的函数,并返回结果。如果为真(默认值),Spring AI 将会内部处理这些函数调用。仅适用于支持功能调用的聊天模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

所有以spring.ai.ollama.chat.options开头的属性可以在运行时通过向Prompt调用添加请求特定的运行时选项来覆盖。

运行时选项

The OllamaChatOptions.java 类提供了模型配置,例如要使用的模型、温度、思考模式等。spring-doc.cadn.net.cn

OllamaOptions 类已弃用。请使用 OllamaChatOptions 用于聊天模型,OllamaEmbeddingOptions 用于嵌入模型代替。新类提供了类型安全且特定于模型的配置选项。

启动时,可以使用OllamaChatModel(api, options)构造函数或spring.ai.ollama.chat.options.*属性来配置默认选项。spring-doc.cadn.net.cn

在运行时,您可以通过向Prompt调用添加新的、针对请求的选项来覆盖默认选项。 例如,要为特定请求覆盖默认模型和温度设置:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OllamaChatOptions.builder()
            .model(OllamaModel.LLAMA3_1)
            .temperature(0.4)
            .build()
    ));
除了针对特定模型的OllamaChatOptions,您还可以使用一个通用的ChatOptions 实例,通过调用 ChatOptions#builder() 创建。

自动拉取模型

Spring AI Ollama 可以在您的 Ollama 实例中不存在这些模型时自动拉取模型。 此功能特别适用于开发和测试,以及将应用程序部署到新环境。spring-doc.cadn.net.cn

您还可以通过名称拉取数千个免费的GGUF Hugging Face 模型

有三种策略用于拉取模型:<br>spring-doc.cadn.net.cn

  • always (定义在 PullModelStrategy.ALWAYS):始终拉取模型,即使模型已经可用。这有助于确保你使用的是最新版本的模型。spring-doc.cadn.net.cn

  • when_missing (定义在PullModelStrategy.WHEN_MISSING):仅在模型不可用时拉取模型。这可能会导致使用较旧版本的模型。spring-doc.cadn.net.cn

  • never (定义在 PullModelStrategy.NEVER):从不自动拉取模型。spring-doc.cadn.net.cn

由于下载模型可能会有潜在的延迟,因此不建议在生产环境中自动拉取。相反,请考虑提前评估并预下载所需的模型。

所有通过配置属性和默认选项定义的模型可以在启动时自动拉取。 您可以使用配置属性来配置拉取策略、超时时间和最大重试次数:spring-doc.cadn.net.cn

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        timeout: 60s
        max-retries: 1
该应用程序不会在所有指定模型均在Ollama中可用之前完成初始化。这可能会显著减慢您的应用程序启动时间,具体取决于模型大小和互联网连接速度。

可以在启动时初始化额外的模型,这对于在运行时动态使用的模型非常有用:spring-doc.cadn.net.cn

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        chat:
          additional-models:
            - llama3.2
            - qwen2.5

如果只想将拉取策略应用于特定类型的模型,则可以从初始化任务中排除聊天模型:spring-doc.cadn.net.cn

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        chat:
          include: false

此配置将应用拉取策略于所有模型,但不包括聊天模型。spring-doc.cadn.net.cn

函数调用

您可以在OllamaChatModel中注册自定义的Java函数,并让Ollama模型智能选择输出一个包含调用已注册函数参数的JSON对象。 这是一种强大的技术,可以将LLM能力与外部工具和API连接起来。 有关工具调用的更多信息,请继续阅读。spring-doc.cadn.net.cn

您需要使用 Ollama 0.2.8 或更新版本才能利用功能调用能力,使用 Ollama 0.4.6 或更新版本则可以在流式模式下使用这些功能。

思考模式(推理)

Ollama 支持思考模式,这是一种推理模型可以在提供最终答案之前发出其内部推理过程的功能。此功能适用于 Qwen3、DeepSeek-v3.1、DeepSeek R1 和 GPT-OSS 等模型。spring-doc.cadn.net.cn

思考模式有助于您理解模型的推理过程,并能提高复杂问题响应的质量。
默认行为(Ollama 0.12+): 具备思考能力的模型(如qwen3:*-thinkingdeepseek-r1deepseek-v3.1)在未明确设置think选项时,默认启用思考功能。标准模型(如qwen2.5:*llama3.2)默认不启用思考功能。要显式控制此行为,请使用.enableThinking().disableThinking()

启用思考模式

大多数模型(Qwen3、DeepSeek-v3.1、DeepSeek R1)支持简单的启用/禁用布尔值:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "How many letter 'r' are in the word 'strawberry'?",
        OllamaChatOptions.builder()
            .model("qwen3")
            .enableThinking()
            .build()
    ));

// Access the thinking process
String thinking = response.getResult().getMetadata().get("thinking");
String answer = response.getResult().getOutput().getText();

您也可以显式禁用思考:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "What is 2+2?",
        OllamaChatOptions.builder()
            .model("deepseek-r1")
            .disableThinking()
            .build()
    ));

思维层次(仅适用于GPT-OSS)

GPT-OSS 模型需要显式的思考层级而非布尔值:spring-doc.cadn.net.cn

// Low thinking level
ChatResponse response = chatModel.call(
    new Prompt(
        "Generate a short headline",
        OllamaChatOptions.builder()
            .model("gpt-oss")
            .thinkLow()
            .build()
    ));

// Medium thinking level
ChatResponse response = chatModel.call(
    new Prompt(
        "Analyze this dataset",
        OllamaChatOptions.builder()
            .model("gpt-oss")
            .thinkMedium()
            .build()
    ));

// High thinking level
ChatResponse response = chatModel.call(
    new Prompt(
        "Solve this complex problem",
        OllamaChatOptions.builder()
            .model("gpt-oss")
            .thinkHigh()
            .build()
    ));

访问思考内容

思考内容将在响应元数据中提供:spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "Calculate 17 × 23",
        OllamaChatOptions.builder()
            .model("deepseek-r1")
            .enableThinking()
            .build()
    ));

// Get the reasoning process
String thinking = response.getResult().getMetadata().get("thinking");
System.out.println("Reasoning: " + thinking);
// Output: "17 × 20 = 340, 17 × 3 = 51, 340 + 51 = 391"

// Get the final answer
String answer = response.getResult().getOutput().getText();
System.out.println("Answer: " + answer);
// Output: "The answer is 391"

流式处理与思考

思考模式同样支持流式响应:spring-doc.cadn.net.cn

Flux<ChatResponse> stream = chatModel.stream(
    new Prompt(
        "Explain quantum entanglement",
        OllamaChatOptions.builder()
            .model("qwen3")
            .enableThinking()
            .build()
    ));

stream.subscribe(response -> {
    String thinking = response.getResult().getMetadata().get("thinking");
    String content = response.getResult().getOutput().getText();

    if (thinking != null && !thinking.isEmpty()) {
        System.out.println("[Thinking] " + thinking);
    }
    if (content != null && !content.isEmpty()) {
        System.out.println("[Response] " + content);
    }
});
当思考被禁用或未设置时,thinking元数据字段将为null或空。

多模态

多模态指的是模型同时理解和处理来自多种来源的信息的能力,包括文本、图像、音频以及其他数据格式。spring-doc.cadn.net.cn

一些在 Ollama 中支持多模态的模型包括LLaVABakLLaVA(请参见完整的列表)。 如需更多详细信息,请参阅LLaVA:大型语言和视觉助手spring-doc.cadn.net.cn

Ollama 消息API 提供了"images"参数,用于在消息中包含一系列base64编码的图像。spring-doc.cadn.net.cn

Spring AI的Message接口通过引入Media类型来促进多模态AI模型。 这种类型包含了消息中媒体附件的数据和详细信息,利用了Spring的org.springframework.util.MimeType和一个org.springframework.core.io.Resource来处理原始媒体数据。spring-doc.cadn.net.cn

下面是从OllamaChatModelMultimodalIT.java摘取的一段简单代码示例,展示了用户文本与图片的融合。spring-doc.cadn.net.cn

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,
        OllamaChatOptions.builder().model(OllamaModel.LLAVA)).build());

该示例显示了一个模型将输入一个multimodal.test.png图像:spring-doc.cadn.net.cn

Multimodal Test Image

<p> along with the text message &quot;请解释你在图片上看到了什么?&quot;, 并生成类似这样的响应:</p>spring-doc.cadn.net.cn

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-doc.cadn.net.cn

结构化输出的两种模式

Ollama 支持通过 format 参数的两种不同的结构化输出模式:spring-doc.cadn.net.cn

  1. 简单的“json”格式:指示Ollama返回任何有效的JSON结构(不可预测的模式)spring-doc.cadn.net.cn

  2. JSON Schema 格式:指示 Ollama 返回符合特定模式(可预测结构)的 JSON 数据spring-doc.cadn.net.cn

简单 "json" 格式

使用此功能时,您将获得JSON输出但不需要特定结构。spring-doc.cadn.net.cn

ChatResponse response = chatModel.call(
    new Prompt(
        "List 3 countries in Europe",
        OllamaChatOptions.builder()
            .model("llama3.2")
            .format("json")  // Any valid JSON
            .build()
    ));

该模型可以返回它选择的任何JSON结构:spring-doc.cadn.net.cn

["France", "Germany", "Italy"]
// or
{"countries": ["France", "Germany", "Italy"]}
// or
{"data": {"european_countries": ["France", "Germany", "Italy"]}}

需要保证和预测结构时,请使用此功能:spring-doc.cadn.net.cn

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

ChatResponse response = chatModel.call(
    new Prompt(
        "List 3 countries in Europe",
        OllamaChatOptions.builder()
            .model("llama3.2")
            .outputSchema(jsonSchema)  // Enforced schema
            .build()
    ));

The model 必须返回此精确结构:spring-doc.cadn.net.cn

{"countries": ["France", "Germany", "Italy"]}

配置

Spring AI 允许您通过使用 OllamaChatOptions 构建器程序化地配置您的响应格式。spring-doc.cadn.net.cn

使用 Chat Options 构建器与 JSON 方案

您可以使用OllamaChatOptions构建器编程设置响应格式:spring-doc.cadn.net.cn

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",
        OllamaChatOptions.builder()
            .model(OllamaModel.LLAMA3_2.getName())
            .outputSchema(jsonSchema)  // Pass JSON Schema as string
            .build());

ChatResponse response = this.ollamaChatModel.call(this.prompt);

集成BeanOutputConverter 工具

您可以利用现有的BeanOutputConverter 工具自动生成领域对象的 JSON 方案,并稍后将结构化的响应转换为特定于领域的实例:spring-doc.cadn.net.cn

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",
        OllamaChatOptions.builder()
            .model(OllamaModel.LLAMA3_2.getName())
            .outputSchema(outputConverter.getJsonSchema())  // Get JSON Schema as string
            .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,…​)注解来生成一个准确标记字段为required的schema。 尽管这对于JSON Schema来说是可选的,但为了使结构化响应正确工作,建议使用此注解。

API 方法:.format() vs .outputSchema()

Spring AI 提供了两种配置结构化输出的方法:spring-doc.cadn.net.cn

方法 用例 例举

.format("json")spring-doc.cadn.net.cn

简单JSON模式 - 任意结构spring-doc.cadn.net.cn

.format("json")spring-doc.cadn.net.cn

.outputSchema(jsonSchemaString)spring-doc.cadn.net.cn

JSON Schema模式 - 强制结构spring-doc.cadn.net.cn

.outputSchema("{\"type\":\"object\",…​}")spring-doc.cadn.net.cn

.format(mapObject)spring-doc.cadn.net.cn

JSON Schema模式 - 替代APIspring-doc.cadn.net.cn

.format(new ObjectMapper().readValue(schema, Map.class))spring-doc.cadn.net.cn

对于大多数用例,使用.outputSchema(jsonSchemaString)进行JSON Schema验证或使用.format("json")生成简单的JSON输出。 .format(Map)方法也支持,但需要手动解析JSON。

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.spring-doc.cadn.net.cn

当使用OpenAI客户端与Ollama配合时,你可以通过extraBody选项传递Ollama特定的参数(如top_krepeat_penaltynum_predict)。 这使得你能够在使用OpenAI客户端的同时充分利用Ollama的全部功能。
Ollama OpenAI API compatibility

通过OpenAI兼容性进行推理内容

Ollama 的 OpenAI 兼容端点支持 reasoning_content 字段用于思考能力模型(例如 qwen3:*-thinking, deepseek-r1, deepseek-v3.1)。 当使用 Spring AI OpenAI 客户端与 Ollama 一起工作时,模型的推理过程会自动被捕获并通过响应元数据提供。spring-doc.cadn.net.cn

这是使用Ollama原生思考模式API(在上方的思考模式(推理)中有所文档化)的一种替代方案。 两种方法都可以与Ollama的思考模型协同工作,但兼容OpenAI的端点使用reasoning_content字段名称而不是thinking

这里是一个通过OpenAI客户端访问Ollama推理内容的示例:spring-doc.cadn.net.cn

// Configure Spring AI OpenAI client to point to Ollama
@Configuration
class OllamaConfig {
    @Bean
    OpenAiChatModel ollamaChatModel() {
        var openAiApi = new OpenAiApi("http://localhost:11434", "ollama");
        return new OpenAiChatModel(openAiApi,
            OpenAiChatOptions.builder()
                .model("deepseek-r1")  // or qwen3, deepseek-v3.1, etc.
                .build());
    }
}

// Use the model with thinking-capable models
ChatResponse response = chatModel.call(
    new Prompt("How many letter 'r' are in the word 'strawberry'?"));

// Access the reasoning process from metadata
String reasoning = response.getResult().getMetadata().get("reasoningContent");
if (reasoning != null && !reasoning.isEmpty()) {
    System.out.println("Model's reasoning process:");
    System.out.println(reasoning);
}

// Get the final answer
String answer = response.getResult().getOutput().getText();
System.out.println("Answer: " + answer);
Thinking-capable 模型在 Ollama (0.12+) 中,在通过 OpenAI 兼容端点访问时会自动启用思考模式。 推理内容会自动捕获,无需额外配置。

检查OllamaWithOpenAiChatModelIT.java测试用例,了解如何在Spring AI OpenAI中使用Ollama。spring-doc.cadn.net.cn

HuggingFace 模型

Ollama 可以直接访问所有 GGUF Hugging Face 聊天模型。 你可以通过名称拉取任意这些模型:ollama pull hf.co/<username>/<model-repository> 或配置自动拉取策略:自动拉取模型:spring-doc.cadn.net.cn

spring.ai.ollama.chat.options.model=hf.co/bartowski/gemma-2-2b-it-GGUF
spring.ai.ollama.init.pull-model-strategy=always

样本控制器

创建一个新的Spring Boot项目,并在pom(或gradle)依赖中添加spring-ai-starter-model-ollamaspring-doc.cadn.net.cn

src/main/resources目录下添加一个application.yaml文件,以启用并配置Ollama聊天模型:spring-doc.cadn.net.cn

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: mistral
          temperature: 0.7
请将base-url替换为您的Ollama服务器URL。

这将创建一个OllamaChatModel实现,您可以将其注入到您的类中。 以下是一个简单的@RestController类的示例,该类使用聊天模型进行文本生成。spring-doc.cadn.net.cn

@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自动配置,可以在应用中手动配置OllamaChatModelOllamaChatModel实现了ChatModelStreamingChatModel接口,并通过低级OllamaApi客户端连接到Ollama服务。spring-doc.cadn.net.cn

要使用它,请将以下spring-ai-ollama依赖项添加到您的项目Mavenpom.xml或Gradlebuild.gradle构建文件中:spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama'
}
请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。
The spring-ai-ollama 依赖提供了对 OllamaEmbeddingModel 的访问。 有关 OllamaEmbeddingModel 的更多信息,请参阅 Ollama嵌入模型 部分。

接下来,创建一个OllamaChatModel实例,并使用它发送文本生成请求:spring-doc.cadn.net.cn

var ollamaApi = OllamaApi.builder().build();

var chatModel = OllamaChatModel.builder()
                    .ollamaApi(ollamaApi)
                    .defaultOptions(
                        OllamaChatOptions.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."));

OllamaChatOptions 提供了所有聊天请求的配置信息。spring-doc.cadn.net.cn

低级OllamaApi客户端

The OllamaApi 提供了一个轻量级的 Java 客户端,用于 Ollama 聊天补全 API Ollama 聊天补全 APIspring-doc.cadn.net.cn

The following class diagram illustrates the OllamaApi chat interfaces and building blocks:spring-doc.cadn.net.cn

OllamaApi Chat Completion API Diagram
OllamaApi 是低级 API,不建议直接使用。请使用 OllamaChatModel 代替。

这里是一个简单的示例,展示了如何通过编程方式使用API:spring-doc.cadn.net.cn

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(OllamaChatOptions.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(OllamaChatOptions.builder().temperature(0.9).build().toMap())
    .build();

Flux<ChatResponse> streamingResponse = this.ollamaApi.streamingChat(this.request2);