Spring AI 第二讲 之 Chat Model API 第二节Ollama Chat

通过 Ollama，您可以在本地运行各种大型语言模型 (LLM)，并从中生成文本。Spring AI 通过 OllamaChatModel 支持 Ollama 文本生成。

先决条件

首先需要在本地计算机上运行 Ollama。请参阅官方 Ollama 项目 README，开始在本地计算机上运行模型。
注意：安装 ollama 运行 llama3 将下载一个 4.7GB 的模型工件。

添加资源库和 BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 资源库中。请参阅 "资源库 "部分，将这些资源库添加到您的构建系统中。

为了帮助进行依赖性管理，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致的 Spring AI 版本。请参阅 "依赖关系管理 "部分，将 Spring AI BOM 添加到构建系统中。

自动配置

Spring AI 为 Ollama 聊天客户端提供了 Spring Boot 自动配置功能。要启用它，请在项目的 Maven pom.xml 文件中添加以下依赖项：

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

或 Gradle build.gradle 构建文件。

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

请参阅 "依赖关系管理 "部分，将 Spring AI BOM 添加到构建文件中。

聊天属性

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

Property	Description	Default
spring.ai.ollama.base-url	Base URL where Ollama API server is running.	localhost:11434

前缀 spring.ai.ollama.chat.options 是配置 Ollama 聊天模型的属性前缀。它包括 Ollama 请求（高级）参数（如模型、keep-alive 和 format）以及 Ollama 模型选项属性。

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

Property	Description	Default
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

其余选项属性基于 Ollama 有效参数和值以及 Ollama 类型。默认值基于 Ollama 类型默认值。

Property	Description	Default
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-gqa	变压器层中 GQA 组的数量。某些型号需要，例如 llama2:70b 为 8。	1
spring.ai.ollama.chat.options.num-gpu	要发送到 GPU 的层数。在 macOS 上，默认值为 1 表示启用金属支持，0 表示禁用。此处的 1 表示应动态设置 NumGPU	-1
spring.ai.ollama.chat.options.main-gpu		-
spring.ai.ollama.chat.options.low-vram		false
spring.ai.ollama.chat.options.f16-kv		true
spring.ai.ollama.chat.options.logits-all		-
spring.ai.ollama.chat.options.vocab-only		-
spring.ai.ollama.chat.options.use-mmap		true
spring.ai.ollama.chat.options.use-mlock		false
spring.ai.ollama.chat.options.num-thread	设置计算时使用的线程数。默认情况下，Ollama 会检测线程数以获得最佳性能。建议将此值设置为系统的物理 CPU 内核数（而不是逻辑内核数）。0 = 由运行时决定	0
spring.ai.ollama.chat.options.num-keep		0
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 为前缀的属性都可以通过在提示调用中添加特定于请求的运行时选项在运行时重写。

运行时选项

OllamaOptions.java 提供了模型配置，如要使用的模型、温度等。
启动时，可使用 OllamaChatModel(api, options) 构造函数或 spring.ai.ollama.chat.options.* 属性配置默认选项。
在运行时，您可以通过在提示调用中添加新的、针对特定请求的选项来覆盖默认选项。例如，覆盖特定请求的默认模型和温度：

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OllamaOptions.create()
            .withModel("llama2")
            .withTemperature(0.4)
    ));

除了特定于模型的 OllamaOptions 外，您还可以使用通过 ChatOptionsBuilder#builder()创建的便携式 ChatOptions 实例。

多模型

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

目前，LLaVa 和 bakllava Ollama 模型提供多模态支持。更多详情，请参阅 LLaVA：大型语言和视觉助手。

Ollama 消息 API 提供了一个 "图像 "参数，用于将 base64 编码的图像列表与消息结合在一起。

Spring AI 的消息通过引入 "媒体"（Media）类型，为多模态 AI 模型提供了便利。该类型包含有关消息中媒体附件的数据和详细信息，利用 Spring 的 org.springframework.util.MimeType 和 java.lang.Object 来处理原始媒体数据。

下面是从 OllamaChatModelMultimodalIT.java 中摘录的一个直接代码示例，说明了用户文本与图片的融合。

byte[] imageData = new ClassPathResource("/multimodal.test.png").getContentAsByteArray();

var userMessage = new UserMessage("Explain what do you see on this picture?",
        List.of(new Media(MimeTypeUtils.IMAGE_PNG, imageData)));

ChatResponse response = chatModel.call(
    new Prompt(List.of(userMessage), OllamaOptions.create().withModel("llava")));

logger.info(response.getResult().getOutput().getContent());

它的输入是 multimodal.test.png 图像：

以及文本信息 "解释一下您在这张图片上看到了什么？

图片展示了一个小金属篮子，里面装满了成熟的香蕉和红苹果。篮子放在一个平面上、
这似乎是一张桌子或台面，因为背景中隐约可见一个厨房橱柜或抽屉。
背景。篮子后面还有一个金色的圆环，这可能表明这张照片是在有金属的地方拍摄的。
这张照片是在一个有金属装饰或装置的地方拍摄的。从整体环境来看，这是一个家庭环境
摆放水果，可能是为了方便或美观。

示例Controller

创建一个新的 Spring Boot 项目，并将 spring-ai-ollama-spring-boot-starter 添加到你的 pom（或 gradle）依赖项中。
在 src/main/resources 目录下添加 application.properties 文件，以启用和配置 Ollama 聊天模型：

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

将 base-url 替换为您的 Ollama 服务器 URL。

这将创建一个 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) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return chatModel.stream(prompt);
    }

}

手动配置

如果不想使用 Spring Boot 自动配置，可以在应用程序中手动配置 OllamaChatModel。OllamaChatModel 实现了 ChatModel 和 StreamingChatModel，并使用底层 OllamaApi Client 连接到 Ollama 服务。
要使用它，请在项目的 Maven pom.xml 文件中添加 Spring-ai-ollama 依赖关系：

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

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

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

var ollamaApi = new OllamaApi();

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

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

// Or with streaming responses
Flux<ChatResponse> response = chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));

OllamaOptions 为所有聊天请求提供配置信息。

Low-level OllamaApi 客户端

OllamaApi为 Ollama 聊天完成 API Ollama 聊天完成 API 提供了一个轻量级 Java 客户端。
以下类图说明了 OllamaApi 聊天接口和构建模块：

下面是一个简单的片段，展示了如何以编程方式使用 API：

OllamaApi 是低级应用程序接口，不建议直接使用。请使用 OllamaChatModel。

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.9f))
    .build();

ChatResponse response = ollamaApi.chat(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.9f).toMap())
    .build();

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

下节：Spring AI 第二讲 之 Chat Model API 第三节Azure OpenAI Chat

代码讲解后续补充