跳到主要内容
版本：2.0.1

Ollama 聊天

QWen 3.8 中英对照 Ollama Ollama Chat

借助 Ollama，你可以在本地运行各种大语言模型（LLM）并从中生成文本。Spring AI 通过 OllamaChatModel API 支持 Ollama 的聊天补全功能。

提示

Ollama 还提供了与 OpenAI API 兼容的端点。OpenAI API 兼容性 章节介绍了如何使用 Spring AI OpenAI 连接 Ollama 服务器。

前提条件​

你需要先获取一个 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 构建文件中：

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
提示

请参考 依赖管理 部分，将 Spring AI BOM 添加到您的构建文件中。

基础属性​

spring.ai.ollama 前缀是用于配置与 Ollama 连接的属性前缀。

属性描述默认值
spring.ai.ollama.base-urlOllama 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除通过默认属性配置的模型外，需要额外初始化的模型。[]

聊天属性​

备注

聊天自动配置（chat auto-configurations）的启用和禁用现已通过前缀为 spring.ai.model.chat 的顶层属性进行配置。

启用：spring.ai.model.chat=ollama（默认已启用）

禁用：spring.ai.model.chat=none（或不匹配 ollama 的任何值）

此项变更旨在支持多模型的配置。

前缀 spring.ai.ollama.chat 是用于配置 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.model要使用的 支持模型 的名称。mistral
spring.ai.ollama.chat.format返回响应时使用的格式。接受 "json"（任意 JSON 结构）或 JSON Schema 对象（强制结构）。有关详细信息，请参阅 结构化输出。-
spring.ai.ollama.chat.keep_alive控制请求完成后模型在内存中保持加载的时间5m
spring.ai.ollama.chat.think控制模型是否在给出最终答案之前输出其推理轨迹。-

其余的 options 属性基于 Ollama Valid Parameters and Values 和 Ollama Types。默认值基于 Ollama Types Defaults。

属性描述Default
spring.ai.ollama.chat.numa是否使用 NUMA。false
spring.ai.ollama.chat.num-ctx设置用于生成下一个 token 的上下文窗口大小。2048
spring.ai.ollama.chat.num-batch提示词处理的最大批处理大小。512
spring.ai.ollama.chat.num-gpu要发送到 GPU 的层数。在 macOS 上，默认值为 1 以启用 metal 支持，设为 0 则禁用。此处值为 1 表示 NumGPU 应动态设置。-1
spring.ai.ollama.chat.main-gpu在使用多 GPU 时，此选项用于控制哪些 GPU 用于处理小张量。对于小张量，将其计算任务拆分到所有 GPU 上是不值得的。相关 GPU 会使用稍多的 VRAM 来存储用于临时结果的 scratch buffer。0
spring.ai.ollama.chat.low-vram-false
spring.ai.ollama.chat.f16-kv-true
spring.ai.ollama.chat.logits-all返回所有标记（tokens）的 logits，而不仅仅是最后一个标记。若要启用补全返回 logprobs 功能，此项必须为 true。-
spring.ai.ollama.chat.vocab-only仅加载词汇表，不加载权重。-
spring.ai.ollama.chat.use-mmap默认情况下，模型会被映射到内存中（mmap），这允许系统仅按需加载模型中必要的部分。然而，如果模型大小超过了你的总 RAM 容量，或者你的系统可用内存较低，使用 mmap 可能会增加页换出（pageouts）的风险，从而对性能产生负面影响。禁用 mmap 会导致加载时间变慢，但如果你没有使用 mlock，它可能会减少页换出。请注意，如果模型大小超过了总 RAM 容量，关闭 mmap 将导致模型完全无法加载。null
spring.ai.ollama.chat.use-mlock将模型锁定在内存中，防止其在内存映射时被换出（swap out）。这可以提升性能，但会牺牲内存映射的部分优势，因为需要更多的 RAM 来运行，并可能因模型加载到 RAM 中而延长加载时间。false
spring.ai.ollama.chat.num-thread设置计算过程中使用的线程数。默认情况下，Ollama 会自动检测此值以实现最佳性能。建议将此值设置为系统的物理 CPU 核心数（而非逻辑核心数）。0 表示由运行时决定。0
spring.ai.ollama.chat.num-keep-4
spring.ai.ollama.chat.seed设置用于生成的随机数种子。将其设置为特定数字时，模型将针对相同的提示生成相同的文本。-1
spring.ai.ollama.chat.num-predict生成文本时要预测的最大 token 数量。（-1 = 无限生成，-2 = 填充上下文）-1
spring.ai.ollama.chat.top-k降低生成无意义内容的概率。较高的值（例如 100）会产生更多样化的回答，而较低的值（例如 10）则更为保守。40
spring.ai.ollama.chat.top-p与 top-k 协同工作。较高的值（例如，0.95）会产生更多样化的文本，而较低的值（例如，0.5）则会生成更聚焦且保守的文本。0.9
spring.ai.ollama.chat.min-p作为 top_p 的替代方案，旨在确保质量和多样性的平衡。参数 p 表示考虑某个 token 所需的最小概率，该概率相对于最可能 token 的概率。例如，当 p=0.05 且最可能 token 的概率为 0.9 时，logits 值小于 0.045 的将被过滤掉。0.0
spring.ai.ollama.chat.tfs-z无尾部采样用于降低输出中低概率 token 的影响。较高的值（例如 2.0）会进一步减小这种影响，而值为 1.0 时则禁用该设置。1.0
spring.ai.ollama.chat.typical-p-1.0
spring.ai.ollama.chat.repeat-last-n设置模型回溯以防止重复生成的步数。（默认值：64，0 = 禁用，-1 = num_ctx）64
spring.ai.ollama.chat.temperature模型的温度。提高温度会使模型的回答更具创造性。0.8
spring.ai.ollama.chat.repeat-penalty设置重复惩罚的强度。较高的值（例如 1.5）会更严格地惩罚重复，而较低的值（例如 0.9）则更为宽松。1.1
spring.ai.ollama.chat.presence-penalty-0.0
spring.ai.ollama.chat.frequency-penalty-0.0
spring.ai.ollama.chat.mirostat启用 Mirostat 采样以控制困惑度。（默认值：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0）0
spring.ai.ollama.chat.mirostat-tau控制输出连贯性与多样性的平衡。数值越低，生成的文本将更聚焦且连贯。5.0
spring.ai.ollama.chat.mirostat-eta影响算法对生成文本反馈的响应速度。较低的学习率会导致调整速度变慢，而较高的学习率会使算法更具响应性。0.1
spring.ai.ollama.chat.penalize-newline-true
spring.ai.ollama.chat.stop设置要使用的停止序列。当遇到此模式时，LLM 将停止生成文本并返回。可以在 modelfile 中通过指定多个独立的 stop 参数来设置多个停止模式。-
spring.ai.ollama.chat.tool-callbacks要注册给 ChatModel 的 Tool Callbacks。-
提示

所有以 spring.ai.ollama.chat 为前缀的属性，都可以通过在 Prompt 调用中添加请求特定的运行时选项在运行时被覆盖。

运行时选项​

OllamaChatOptions.java 类提供了模型配置，例如要使用的 model、temperature、thinking mode 等。

important

OllamaOptions 类已弃用。对于聊天模型，请改用 OllamaChatOptions；对于嵌入模型，请改用 OllamaEmbeddingOptions。新类提供类型安全且针对特定模型的配置选项。

启动时，默认选项可以通过 OllamaChatModel(api, options) 构造函数或 spring.ai.ollama.chat.* 属性进行配置。

在运行时，你可以通过向 Prompt 调用添加新的、针对特定请求的选项来覆盖默认选项。例如，要为某个特定请求覆盖默认的 model 和 temperature：

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#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 支持工具调用。模型可以请求执行工具，但不会自行运行工具 — Spring AI 负责执行。

提示

使用工具调用功能需要 Ollama 0.2.8 或更高版本，而在流式模式下使用则需要 Ollama 0.4.6 或更高版本。

对于大多数应用，请使用 ChatClient 配合自动注册的 ToolCallingAdvisor — 参见 Tool Calling。如果需要自行控制循环的低级别操作，参见 ChatModel Tool Calling。

思考模式（推理）​

Ollama 支持推理模型的思考模式，这些模型可以在给出最终答案前输出其内部推理过程。此功能适用于 Qwen3、DeepSeek-v3.1、DeepSeek R1 和 GPT-OSS 等模型。

提示

思考模式有助于你理解模型的推理过程，并提升复杂问题的响应质量。

important

默认行为（Ollama 0.12+）：具备思考能力的模型（如 qwen3:*-thinking、deepseek-r1、deepseek-v3.1）在未显式设置 think 选项时，会默认自动启用思考功能。标准模型（如 qwen2.5:*、llama3.2）则默认不启用思考功能。如需显式控制此行为，请使用 .enableThinking() 或 .disableThinking()。

启用思考模式​

大多数模型（Qwen3、DeepSeek-v3.1、DeepSeek R1）支持简单的布尔值启用/禁用：

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();

您也可以显式地禁用思考功能：

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

思考级别（仅适用于 GPT-OSS）​

GPT-OSS 模型要求使用显式的思考级别，而非布尔值：

// 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()
    ));

访问思考内容​

思考内容可在响应元数据中获取：

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"

流式传输与思考​

思考模式也支持流式响应：

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 元数据字段将为空值或空。

多模态​

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

Ollama 中支持多模态的部分模型包括 LLaVA 和 BakLLaVA（参见完整列表）。更多详情请参考 LLaVA: Large Language and Vision Assistant。

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

该示例展示了一个模型，其输入为 multimodal.test.png 图像：

多模态测试图像

配合文本消息“请解释一下你在这张图片中看到了什么？”，并生成类似以下的响应：

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 提供了自定义的 Structured Outputs API，确保模型生成的响应严格遵循你提供的 JSON Schema。除了现有的 Spring AI 模型无关的 Structured Output 外，这些 API 还提供了增强的控制和精度。

结构化输出的两种模式​

Ollama 支持通过 format 参数进行两种不同的结构化输出模式：

  1. 简单 "json" 格式：指示 Ollama 返回任何有效的 JSON 结构（模式不可预测）
  2. JSON Schema 格式：指示 Ollama 返回符合特定模式的 JSON（结构可预测）

简单的 “json” 格式​

当您希望获得 JSON 输出，但不需要特定结构时，请使用此方法：

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

模型可以返回其选择的任意 JSON 结构：

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

JSON Schema 格式（推荐用于生产环境）​

当您需要保证结构的可预测性时，请使用此方法：

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()
    ));

模型必须返回此确切结构：

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

配置​

Spring AI 允许你通过 OllamaChatOptions 构建器以编程方式配置响应格式。

使用 Chat Options Builder 与 JSON Schema​

你可以使用 OllamaChatOptions 构建器以编程方式设置响应格式：

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 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",
        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() 与 .outputSchema()​

Spring AI 提供了两种配置结构化输出的方法：

Method使用场景示例
.format("json")简单 JSON 模式 - 任意结构.format("json")
.outputSchema(jsonSchemaString)JSON Schema 模式 - 强制结构.outputSchema("{\"type\":\"object\",…​}")
.format(mapObject)JSON Schema 模式 - 替代 API.format(new JsonMapper().readValue(schema, Map.class))
提示

对于大多数用例，请使用 .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/v1，并选择提供的 Ollama 模型之一：spring.ai.openai.chat.model=mistral。

提示

在使用 OpenAI 客户端与 Ollama 时，您可以通过 extraBody 选项 传入 Ollama 特定的参数（如 top_k、repeat_penalty、num_predict）。这允许您在 OpenAI 客户端中充分利用 Ollama 的全部功能。

Ollama OpenAI API 兼容性

通过 OpenAI 兼容性推理内容​

Ollama 的 OpenAI 兼容端点支持针对具备思考能力的模型（例如 qwen3:*-thinking、deepseek-r1、deepseek-v3.1）的 reasoning_content 字段。当使用 Spring AI OpenAI 客户端配合 Ollama 时，模型的推理过程会被自动捕获，并通过响应元数据提供访问。

备注

这是使用 Ollama 原生思考模式 API 的替代方案（已在上述 思考模式（推理） 中记录）。这两种方式都适用于 Ollama 的思考模型，但 OpenAI 兼容端点使用 reasoning_content 字段名，而非 thinking。

以下是通过 OpenAI 客户端从 Ollama 访问推理内容的示例：

// Configure Spring AI OpenAI client to point to Ollama
@Configuration
class OllamaConfig {
    @Bean
    OpenAiChatModel ollamaChatModel() {
        return OpenAiChatModel.builder()
            .options(OpenAiChatOptions.builder()
                .baseUrl("http://localhost:11434/v1")
                .apiKey("ollama")
                .model("deepseek-r1")  // or qwen3, deepseek-v3.1, etc.
                .build())
            .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);
提示

Ollama（0.12+）中支持思考能力的模型通过 OpenAI 兼容端点访问时，会自动启用思考模式。推理内容会被自动捕获，无需进行额外配置。

查看 OllamaWithOpenAiChatModelIT.java 测试，了解在 Spring AI OpenAI 中通过 Ollama 进行调用的示例。

HuggingFace 模型​

Ollama 开箱即可访问所有 GGUF Hugging Face 聊天模型。你可以通过名称拉取其中任意模型：ollama pull hf.co/<用户名>/<模型仓库>，或者配置自动拉取策略：自动拉取模型：

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

  • spring.ai.ollama.chat.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 聊天模型：

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 构建文件中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>
提示

请参见 依赖管理 章节，以在您的构建文件中添加 Spring AI BOM。

提示

spring-ai-ollama 依赖项还提供了对 OllamaEmbeddingModel 的访问。有关 OllamaEmbeddingModel 的更多信息，请参阅 Ollama Embedding Model 部分。

接下来，创建一个 OllamaChatModel 实例，并使用它发送文本生成请求：

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

var chatModel = OllamaChatModel.builder()
                    .ollamaApi(ollamaApi)
                    .options(
                        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 提供所有聊天请求的配置信息。

底层 OllamaApi 客户端​

OllamaApi 为 Ollama Chat Completion API Ollama Chat Completion API 提供了一个轻量级的 Java 客户端。

以下类图展示了 OllamaApi 聊天接口和构建模块：

OllamaApi Chat Completion API Diagram

备注

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(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);