Ollama 聊天

使用 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 为 Ollama 聊天集成提供 Spring Boot 自动配置。要启用它,请将以下依赖项添加到您项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中

  • Maven

  • Gradle

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama-spring-boot-starter'
}
请参考 依赖管理 部分,将 Spring AI BOM 添加到您的构建文件中。

基本属性

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

属性

描述

默认值

spring.ai.ollama.base-url

运行 Ollama API 服务器的基本 URL。

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.ollama.chat.options 是配置 Ollama 聊天模型的属性前缀。它包括 Ollama 请求(高级)参数,例如 modelkeep-aliveformat,以及 Ollama 模型 options 属性。

以下是 Ollama 聊天模型的高级请求参数

属性

描述

默认值

spring.ai.ollama.chat.enabled

启用 Ollama 聊天模型。

true

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.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 将停止生成文本并返回。可以通过在模型文件中指定多个单独的停止参数来设置多个停止模式。

-

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调用添加新的、特定于请求的选项来覆盖默认选项。例如,要覆盖特定请求的默认模型和温度

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OllamaOptions.builder()
            .withModel(OllamaModel.LLAMA3_1)
            .withTemperature(0.4)
            .build()
    ));
除了特定于模型的OllamaOptions之外,您还可以使用可移植的ChatOptions实例,该实例使用ChatOptionsBuilder#builder()创建。

自动拉取模型

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 函数调用

您需要 Ollama 0.2.8 或更高版本才能使用函数调用功能。
目前,Ollama API (0.3.8) 不支持流模式下的函数调用。

多模态

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

Ollama 中一些支持多模态的可用模型是LLaVabakllava(请参见完整列表)。有关更多详细信息,请参阅LLaVA:大型语言和视觉助手

Ollama 消息 API 提供一个“images”参数,用于将 base64 编码的图像列表与消息结合使用。

Spring AI 的Message接口通过引入Media类型来促进多模态 AI 模型。此类型包含有关消息中媒体附件的数据和详细信息,使用 Spring 的org.springframework.util.MimeTypeorg.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().withModel(OllamaModel.LLAVA)).build());

该示例显示一个模型将multimodal.test.png图像作为输入

Multimodal Test Image

以及文本消息“解释你在这张图片上看到了什么?”,并生成类似这样的响应

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.

OpenAI API 兼容性

Ollama 与 OpenAI API 兼容,您可以使用Spring AI OpenAI客户端与 Ollama 通信并使用工具。为此,您需要将 OpenAI 基本 URL 配置到您的 Ollama 实例:spring.ai.openai.chat.base-url=https://127.0.0.1:11434并选择一个提供的 Ollama 模型:spring.ai.openai.chat.options.model=mistral

Ollama OpenAI API compatibility

查看OllamaWithOpenAiChatModelIT.java测试,了解通过 Spring AI OpenAI 使用 Ollama 的示例。

示例控制器

创建一个新的 Spring Boot 项目,并将spring-ai-ollama-spring-boot-starter添加到您的 pom(或 gradle)依赖项中。

src/main/resources目录下添加一个application.yaml文件,以启用和配置 Ollama 聊天模型

spring:
  ai:
    ollama:
      base-url: https://127.0.0.1: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实现了ChatModelStreamingChatModel,并使用低级 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 = new OllamaApi();

var chatModel = new OllamaChatModel(this.ollamaApi,
            OllamaOptions.create()
                .withModel(OllamaOptions.DEFAULT_MODEL)
                .withTemperature(0.9));

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 客户端Ollama 聊天完成 API

下图说明了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")
    .withStream(false) // not streaming
    .withMessages(List.of(
            Message.builder(Role.SYSTEM)
                .withContent("You are a geography teacher. You are talking to a student.")
                .build(),
            Message.builder(Role.USER)
                .withContent("What is the capital of Bulgaria and what is the size? "
                        + "What is the national anthem?")
                .build()))
    .withOptions(OllamaOptions.create().withTemperature(0.9))
    .build();

ChatResponse response = this.ollamaApi.chat(this.request);

// Streaming request
var request2 = ChatRequest.builder("orca-mini")
    .withStream(true) // streaming
    .withMessages(List.of(Message.builder(Role.USER)
        .withContent("What is the capital of Bulgaria and what is the size? " + "What is the national anthem?")
        .build()))
    .withOptions(OllamaOptions.create().withTemperature(0.9).toMap())
    .build();

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