4.10 Ollama ChatOllama Chat 概述 Ollama 允许您在本地运行大型语言模型。先决条件您

Ollama Chat

Spring AI 参考文档 - Ollama 聊天模型集成指南

概述

Ollama 允许您在本地运行大型语言模型。

提示：Ollama 将模型捆绑到单独的应用程序包中。包包含模型的权重和配置。通过 REST API 的服务器提供本地处理 Ollama 的模型。

重要：Ollama 模型存储在 Ollama 配置文件中的特定路径中。对于 Windows，路径为 %APPDATA%，对于 macOS/Linux，路径为 ~/.ollama。

重要：默认情况下，Ollama 仅允许本地连接。要允许其他计算机访问 Ollama，请使用环境变量 OLLAMA_HOST=0.0.0.0。

先决条件

您需要在本地运行 Ollama 服务器才能访问 Ollama 语言模型。

要开始，请按照 Ollama 安装指南操作。

# 下载 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型（以 Llama 3 为例）
ollama pull llama3

# 与模型聊天
ollama run llama3

您可以使用以下设置来启动 Ollama 服务器：

ollama serve

默认情况下，Ollama 服务器在 localhost:11434 上运行。

自动配置

注意：Spring AI 自动配置和启动器模块的构件名称已发生重大变化。请参阅升级说明了解更多信息。

Spring AI 为 Ollama 聊天客户端提供 Spring Boot 自动配置。

要启用它，请将以下依赖项添加到您项目的 Maven pom.xml 文件中：

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

或者添加到您的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}

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

聊天属性

注意：聊天自动配置的启用和禁用现在通过前缀为 spring.ai.model.chat 的顶级属性配置。

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

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

进行此更改是为了允许多个模型的配置。

前缀 spring.ai.ollama 是属性前缀，让您可以为 Ollama 配置聊天模型实现。

属性	描述	默认值
spring.ai.ollama.base-url	连接的 URL	`http://localhost:11434`
spring.ai.ollama.chat.enabled (已移除，不再有效)	启用 Ollama 聊天模型	true
spring.ai.model.chat	启用 Ollama 聊天模型	ollama

重试属性

前缀 spring.ai.retry 用作属性前缀，让您可以为 Ollama 聊天模型配置重试机制。

属性	描述	默认值
spring.ai.retry.max-attempts	最大重试尝试次数	10
spring.ai.retry.backoff.initial-interval	指数退避策略的初始睡眠持续时间	2 秒
spring.ai.retry.backoff.multiplier	退避间隔乘数	5
spring.ai.retry.backoff.max-interval	最大退避持续时间	3 分钟
spring.ai.retry.on-client-errors	如果为 false，则抛出 NonTransientAiException，并且不会尝试重试 `4xx` 客户端错误代码	false
spring.ai.retry.exclude-on-http-codes	不应触发重试的 HTTP 状态代码列表（例如，抛出 NonTransientAiException）	空
spring.ai.retry.on-http-codes	应触发重试的 HTTP 状态代码列表（例如，抛出 TransientAiException）	空

聊天选项属性

属性	描述	默认值
spring.ai.ollama.chat.options.model	这是要使用的 Ollama 模型	-
spring.ai.ollama.chat.options.num-ctx	调整模型上下文窗口的大小。	2048
spring.ai.ollama.chat.options.num-_predict	生成文本时要预测的最大令牌数。	-1
spring.ai.ollama.chat.options.seed	设置随机数种子。	-1
spring.ai.ollama.chat.options.temperature	模型的温度。增加温度会使模型回答更有创意，而降低温度会使其更专注和确定。	0.8
spring.ai.ollama.chat.options.stop	设置模型停止的停止序列。	-
spring.ai.ollama.chat.options.top-k	减少产生无意义结果的概率。更高的采样方法，如 top-p，用于选择高分标记的集合，从中选择最终标记。	40
spring.ai.ollama.chat.options.top-p	与 top-k 一起工作。较低的值会忽略可能性较低的选项，产生更稳定的输出。	0.9
spring.ai.ollama.chat.options.mirostat	启用 Mirostat 抽样，用于控制困惑度。（默认：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0）	0
spring.ai.ollama.chat.options.mirostat-eta	影响算法对生成文本反馈的响应速度。较低的学习率会导致较慢的调整。	0.1
spring.ai.ollama.chat.options.mirostat-tau	控制输出的连贯性和多样性之间的平衡。较低的 tau 值会导致更专注和连贯的文本。	5.0
spring.ai.ollama.chat.options.repeat-penalty	设置模型对重复文本的惩罚程度。较高的值会导致较少的重复。	1.1
spring.ai.ollama.chat.options.repeat-last-n	设置模型回顾以防止重复的上下文大小。0 表示禁用，-1 表示为 num-ctx。	64
spring.ai.ollama.chat.options.tfs-z	自由度采样的最后一个选项。	1
spring.ai.ollama.chat.options.num-keep	指定 n_predict 生成时要保留在提示中的标记数。	-1
spring.ai.ollama.chat.options.typical-p	典型 p 采样。	0.7
spring.ai.ollama.chat.options.presence-penalty	负值有助于模型谈论新主题。	0
spring.ai.ollama.chat.options.frequency-penalty	负值有助于模型避免重复。	0

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

运行时选项

OllamaChatOptions.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("llama3:8b")
            .temperature(0.5)
        .build()
    ));

提示：除了模型特定的 OllamaOptions 外，您还可以使用通过 ChatOptions#builder() 创建的可移植 ChatOptions 实例。

自动拉取模型

如果本地不存在指定的模型，OllamaChatModel 可以从 Ollama 库中自动拉取模型。

要启用此功能，您需要将 spring.ai.ollama.chat.options.autopull 属性设置为 true：

spring:
  ai:
    ollama:
      chat:
        options:
          model: "dolphin-phi"
          autopull: true

在 Java 代码中，它也可以通过 OllamaOptions 启用：

var chatOptions = OllamaOptions.builder()
        .model("dolphin-phi")
        .withAutopull(true)
        .build();

var chatModel = new OllamaChatModel(new OllamaApi(), chatOptions);

示例控制器

创建一个新的 Spring Boot 项目，并将 spring-ai-starter-model-ollama 添加到您的 pom（或 gradle）依赖项中。

在 src/main/resources 目录下添加 application.properties 文件，以启用和配置 Ollama 聊天模型：

spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=llama3
spring.ai.ollama.chat.options.temperature=0.7

这将创建一个可以注入到您的类中的 OllamaChatModel 实现。这是一个使用聊天模型进行文本生成的简单 @Controller 类示例。

@RestController
public class ChatController {

    private final OllamaChatModel chatModel;

    @Autowired
    public ChatController(OllamaChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        var prompt = new Prompt(new UserMessage(message));
        return chatModel.stream(prompt);
    }
}

手动配置

除了自动配置之外，您还可以手动创建 OllamaChatModel。

将 spring-ai-ollama 依赖项添加到您项目的 Maven pom.xml 文件中：

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

或者添加到您的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama'
}

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

var ollamaApi = new OllamaApi();

var chatModel = new OllamaChatModel(ollamaApi, OllamaOptions.builder()
                .withModel("llama3")
                .withTemperature(0.9)
                .build());

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

// 或使用流式响应
Flux<ChatResponse> streamResponse = this.chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));

OllamaOptions 为聊天请求提供配置信息。 OllamaOptions.Builder 是一个流畅的选项构建器。

低级 OllamaApi 客户端

OllamaApi 提供了一个用于 Ollama REST API 的轻量级 Java 客户端。

这是一个显示如何以编程方式使用 API 的简单片段：

OllamaApi ollamaApi = new OllamaApi();

// 同步请求
ResponseEntity<ChatCompletion> response = this.ollamaApi.chatCompletionEntity(
    new ChatCompletionRequest("llama3", List.of(new ChatCompletionMessage("Hello world", Role.USER))));

// 流式请求
Flux<ChatCompletionChunk> streamResponse = this.ollamaApi.chatCompletionStream(
    new ChatCompletionRequest("llama3", List.of(new ChatCompletionMessage("Hello world", Role.USER))));

请遵循 OllamaApi.java 的 JavaDoc 获取更多信息。

OllamaApi 示例

OllamaApiIT.java 测试提供了一些如何使用轻量级库的通用示例。
OllamaChatModelFunctionCallingIT.java 测试显示了函数调用的示例。
OllamaChatModelMultimodalIT.java 测试显示了多模态的示例。

函数调用

您可以使用 OllamaChatModel 注册自定义 Java 函数，让 Ollama 模型智能地选择输出包含调用一个或多个注册函数参数的 JSON 对象。这是将 LLM 功能与外部工具和 API 连接的强大技术。

Ollama 支持函数调用（在 Ollama 术语中称为"工具支持"）。

Spring AI 在两种函数调用风格之间实现了不同的转换：

Function Calling：用于 OpenAI 格式的工具，用于 OpenAI、Mistral AI、Ollama 等
Tool Calling：用于 Vertex AI、Anthropic、Gemini 工具

重要：并非所有 Ollama 模型都针对函数调用进行了微调。支持工具/函数调用支持的模型包括：llama3.1:8b、llama3.1:70b、llama3.1:405b、llama3-groq-128b 等。

工具示例

以下是如何在 Spring AI 中使用 Ollama 函数调用的简单示例：

@SpringBootApplication
public class OllamaApplication {

    public static void main(String[] args) {
        SpringApplication.run(OllamaApplication.class, args);
    }

    @Bean
    CommandLineRunner runner(ChatClient.Builder chatClientBuilder) {
        return args -> {
            var chatClient = chatClientBuilder.build();

            var response = chatClient.prompt()
                .user("What's the weather like in San Francisco, Tokyo, and Paris?")
                .functions("weatherFunction") // 通过 bean 名称引用。
                .call()
                .content();

            System.out.println(response);
        };
    }

    @Bean
    @Description("Get the weather in location")
    public Function<WeatherRequest, WeatherResponse> weatherFunction() {
        return new MockWeatherService();
    }

    public record WeatherRequest(String location, String unit) {}
    public record WeatherResponse(double temp, String unit) {}

    public static class MockWeatherService implements Function<WeatherRequest, WeatherResponse> {

        public WeatherResponse apply(WeatherRequest request) {
            double temperature = request.location().contains("San Francisco") ? 15 : 25;
            return new WeatherResponse(temperature, request.unit());
        }
    }
}

在此示例中，当模型需要天气信息时，它将自动调用 weatherFunction bean，然后可以获取实时天气数据。预期的响应是："旧金山的天气是 15 摄氏度，东京和巴黎的天气是 25 摄氏度。"

阅读更多关于 Ollama 函数调用的信息。

多模态

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

支持视觉的 Ollama 模型包括：llava、llava-llama3、bakllava、moondream、llava、cogvlm 和 qwen2-vl 等。您可以查看 Ollama 文档中的所有视觉模型。

Spring AI 的 Message 接口通过引入 Media 类型促进多模态 AI 模型。此类型包含消息中媒体附件的数据和详细信息，利用 Spring 的 org.springframework.util.MimeType 和 org.springframework.core.io.Resource 用于原始媒体数据。

以下是从 OllamaChatModelMultimodalIT.java 摘录的代码示例，说明用户文本与图像的融合：

var imageResource = new ClassPathResource("/test.png");

var userMessage = new UserMessage("Explain what do you see on this picture?",
    new Media(MimeTypeUtils.IMAGE_JPEG, this.imageResource));

ChatResponse response = chatModel.call(new Prompt(List.of(this.userMessage),
        OllamaOptions.builder().withModel(OllamaModel.LLAVA).build()));

提示：您也可以传递多个图像。

结构化输出

某些 Ollama 模型可以使用函数调用功能生成结构化输出，如 JSON。

例如，要从 Ollama 模型获取结构化的电影信息，可以使用 @JsonClassDescription 注释和函数调用机制：

record Movie(@JsonProperty(required = true) String title, @JsonProperty(required = true) int year) {}

@Bean
@JsonClassDescription("Get information about a movie")
public Function<MovieRequest, Movie> movieFunction() {
    return request -> new Movie(request.title(), request.year());
}

public record MovieRequest(String title, int year) {}

现在，如果给模型一个类似 "Tell me about the movie 'The Matrix'" 的提示，它将返回一个 JSON 格式的响应，包含标题和年份。

OpenAI API 兼容性

Ollama 还提供了与 OpenAI API 的兼容性层，允许您为 Ollama 更改 OpenAI 客户端的 baseUrl。

提示：Ollama 的 OpenAI 兼容性是实验性的，可能会发生变化。

此兼容性允许您使用现有的 OpenAI 集成与 Ollama 模型通信。

Spring AI OpenAI 示例

查看 OllamaWithOpenAiChatModelIT.java 测试，了解如何在 Spring AI 中使用 Ollama 的 OpenAI API 兼容性。

HuggingFace 模型

Ollama 支持运行 HuggingFace GGUF 格式的模型。

这是一个显示如何从 Ollama 下载和运行 HuggingFace 模型的示例：

ollama run hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF:Q8_0

查看 Ollama 文档获取更多关于使用 HuggingFace 模型的信息。

4.10 Ollama Chat