通過 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;@Autowiredpublic 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

代碼講解后續補充