Ollama 嵌入

透過 Ollama，您可以在本地執行各種 AI 模型並從中生成嵌入。嵌入是一個浮點數向量（列表）。兩個向量之間的距離衡量它們的關聯性。距離越小表示關聯性越高，距離越大表示關聯性越低。

OllamaEmbeddingModel 實現利用 Ollama 嵌入 API 端點。

先決條件

您首先需要訪問一個 Ollama 例項。有幾種選擇，包括以下內容：

下載並安裝 Ollama 到您的本地機器。
透過 Testcontainers 配置和執行 Ollama。
透過 Kubernetes 服務繫結繫結到 Ollama 例項。

您可以從 Ollama 模型庫中拉取您想在應用程式中使用的模型。

ollama pull <model-name>

您還可以拉取數千個免費的 GGUF Hugging Face 模型。

ollama pull hf.co/<username>/<model-repository>

或者，您可以啟用自動下載所需模型的選項：自動拉取模型。

自動配置

Spring AI 自動配置、啟動模組的工件名稱發生了重大變化。請參閱升級說明以獲取更多資訊。

Spring AI 為 Azure Ollama 嵌入模型提供了 Spring Boot 自動配置。要啟用它，請將以下依賴項新增到您的 Maven pom.xml 或 Gradle build.gradle 構建檔案中。

Maven
Gradle

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

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

請參閱依賴管理部分，將 Spring AI BOM 新增到您的構建檔案中。Spring AI 工件釋出在 Maven Central 和 Spring Snapshot 倉庫中。請參閱倉庫部分，將這些倉庫新增到您的構建系統。

基本屬性

字首 spring.ai.ollama 是配置與 Ollama 連線的屬性字首。

財產

描述

預設值

spring.ai.ollama.base-url

Ollama API 伺服器執行的基本 URL。

https://:11434

以下是用於初始化 Ollama 整合和自動拉取模型的屬性。

財產

描述

預設值

spring.ai.ollama.init.pull-model-strategy

是否在啟動時拉取模型以及如何拉取。

從不

spring.ai.ollama.init.timeout

等待模型拉取的時間。

5m

spring.ai.ollama.init.max-retries

模型拉取操作的最大重試次數。

0

spring.ai.ollama.init.embedding.include

在初始化任務中包含此型別的模型。

true

spring.ai.ollama.init.embedding.additional-models

除了透過預設屬性配置的模型之外，要初始化的其他模型。

[]

嵌入屬性

嵌入自動配置的啟用和停用現在透過字首為 spring.ai.model.embedding 的頂級屬性進行配置。

要啟用，spring.ai.model.embedding=ollama（預設啟用）

要停用，spring.ai.model.embedding=none（或任何不匹配 ollama 的值）

此更改是為了允許配置多個模型。

字首 spring.ai.ollama.embedding.options 是配置 Ollama 嵌入模型的屬性字首。它包括 Ollama 請求（高階）引數，例如 model、keep-alive 和 truncate，以及 Ollama 模型 options 屬性。

以下是 Ollama 嵌入模型的高階請求引數

財產

描述

預設值

spring.ai.ollama.embedding.enabled（已移除且不再有效）

啟用 Ollama 嵌入模型自動配置。

true

spring.ai.model.embedding

啟用 Ollama 嵌入模型自動配置。

ollama

spring.ai.ollama.embedding.options.model

要使用的支援模型的名稱。您可以使用專用的嵌入模型型別

mxbai-embed-large

spring.ai.ollama.embedding.options.keep_alive

控制模型在請求後在記憶體中載入的時長

spring.ai.ollama.embedding.options.truncate

截斷每個輸入的末尾以適應上下文長度。如果為 false 且超出上下文長度則返回錯誤。

true

其餘的 options 屬性基於 Ollama 有效引數和值以及 Ollama 型別。預設值基於：Ollama 型別預設值。

財產

描述

預設值

spring.ai.ollama.embedding.options.numa

是否使用 NUMA。

假

spring.ai.ollama.embedding.options.num-ctx

設定用於生成下一個標記的上下文視窗大小。

2048

spring.ai.ollama.embedding.options.num-batch

提示處理的最大批處理大小。

512

spring.ai.ollama.embedding.options.num-gpu

傳送到 GPU 的層數。在 macOS 上，預設為 1 以啟用 metal 支援，0 以停用。這裡的 1 表示應動態設定 NumGPU。

-1

spring.ai.ollama.embedding.options.main-gpu

當使用多個 GPU 時，此選項控制哪個 GPU 用於小型張量，對於這些張量，將計算分散到所有 GPU 的開銷不值得。所涉及的 GPU 將使用稍微更多的 VRAM 來儲存用於臨時結果的暫存緩衝區。

spring.ai.ollama.embedding.options.low-vram

假

spring.ai.ollama.embedding.options.f16-kv

true

spring.ai.ollama.embedding.options.logits-all

返回所有標記的 logits，而不僅僅是最後一個。要使補全返回 logprobs，此值必須為 true。

spring.ai.ollama.embedding.options.vocab-only

僅載入詞彙表，不載入權重。

spring.ai.ollama.embedding.options.use-mmap

預設情況下，模型被對映到記憶體中，這允許系統根據需要僅載入模型的必要部分。但是，如果模型大於您的總 RAM 量或系統可用記憶體不足，使用 mmap 可能會增加頁面換出的風險，從而對效能產生負面影響。停用 mmap 會導致載入時間變慢，但如果您不使用 mlock，可能會減少頁面換出。請注意，如果模型大於總 RAM 量，關閉 mmap 將完全阻止模型載入。

null

spring.ai.ollama.embedding.options.use-mlock

將模型鎖定在記憶體中，防止在記憶體對映時被交換出去。這可以提高效能，但以犧牲記憶體對映的一些優點為代價，因為它需要更多的 RAM 才能執行，並且可能會在模型載入到 RAM 中時減慢載入時間。

假

spring.ai.ollama.embedding.options.num-thread

設定計算期間使用的執行緒數。預設情況下，Ollama 將檢測此值以獲得最佳效能。建議將此值設定為系統擁有的物理 CPU 核心數（而不是邏輯核心數）。0 = 讓執行時決定

spring.ai.ollama.embedding.options.num-keep

spring.ai.ollama.embedding.options.seed

設定用於生成隨機數種子。將其設定為特定數字將使模型為相同的提示生成相同的文字。

-1

spring.ai.ollama.embedding.options.num-predict

生成文字時預測的最大標記數。（-1 = 無限生成，-2 = 填充上下文）

-1

spring.ai.ollama.embedding.options.top-k

降低生成無意義內容的可能性。較高的值（例如 100）將提供更多樣化的答案，而較低的值（例如 10）將更保守。

spring.ai.ollama.embedding.options.top-p

與 top-k 協同工作。較高的值（例如 0.95）將導致更多樣化的文字，而較低的值（例如 0.5）將生成更集中和保守的文字。

0.9

spring.ai.ollama.embedding.options.min-p

top_p 的替代方案，旨在確保質量和多樣性的平衡。引數 p 表示令牌被考慮的最小機率，相對於最可能令牌的機率。例如，當 p=0.05 且最可能令牌的機率為 0.9 時，小於 0.045 的 logits 將被過濾掉。

0.0

spring.ai.ollama.embedding.options.tfs-z

無尾取樣用於減少不太可能令牌對輸出的影響。較高的值（例如 2.0）將更大程度地減少影響，而 1.0 的值將停用此設定。

1.0

spring.ai.ollama.embedding.options.typical-p

1.0

spring.ai.ollama.embedding.options.repeat-last-n

設定模型向前檢視以防止重複的距離。（預設值：64，0 = 停用，-1 = num_ctx）

spring.ai.ollama.embedding.options.temperature

模型的溫度。增加溫度將使模型更具創造性地回答。

0.8

spring.ai.ollama.embedding.options.repeat-penalty

設定重複的懲罰強度。較高的值（例如 1.5）將更強烈地懲罰重複，而較低的值（例如 0.9）將更寬鬆。

1.1

spring.ai.ollama.embedding.options.presence-penalty

0.0

spring.ai.ollama.embedding.options.frequency-penalty

0.0

spring.ai.ollama.embedding.options.mirostat

啟用 Mirostat 取樣以控制困惑度。（預設值：0，0 = 停用，1 = Mirostat，2 = Mirostat 2.0）

spring.ai.ollama.embedding.options.mirostat-tau

控制輸出連貫性和多樣性之間的平衡。較低的值將導致更集中和連貫的文字。

5.0

spring.ai.ollama.embedding.options.mirostat-eta

影響演算法對生成文字反饋的響應速度。較低的學習率會導致較慢的調整，而較高的學習率將使演算法更具響應性。

0.1

spring.ai.ollama.embedding.options.penalize-newline

true

spring.ai.ollama.embedding.options.stop

設定要使用的停止序列。當遇到此模式時，LLM 將停止生成文字並返回。可以透過在 modelfile 中指定多個單獨的停止引數來設定多個停止模式。

spring.ai.ollama.embedding.options.functions

在單個提示請求中啟用函式呼叫的函式列表，由其名稱標識。具有這些名稱的函式必須存在於 functionCallbacks 登錄檔中。

所有以 spring.ai.ollama.embedding.options 為字首的屬性都可以在執行時透過向 EmbeddingRequest 呼叫新增請求特定的執行時選項來覆蓋。

執行時選項

OllamaEmbeddingOptions.java 提供了 Ollama 配置，例如要使用的模型、低階 GPU 和 CPU 調優等。

OllamaOptions 類已被棄用。請改用 OllamaChatOptions 用於聊天模型，OllamaEmbeddingOptions 用於嵌入模型。新類提供了型別安全、模型特定的配置選項。

預設選項也可以使用 spring.ai.ollama.embedding.options 屬性進行配置。

在啟動時使用 OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaEmbeddingOptions defaultOptions) 配置所有嵌入請求使用的預設選項。在執行時，您可以使用 OllamaEmbeddingOptions 例項作為 EmbeddingRequest 的一部分來覆蓋預設選項。

例如，為特定請求覆蓋預設模型名稱

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("Different-Embedding-Model-Deployment-Name"))
            .truncates(false)
            .build());

自動拉取模型

如果 Ollama 例項中沒有模型，Spring AI 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
        embedding:
          additional-models:
            - mxbai-embed-large
            - nomic-embed-text

如果您只想將拉取策略應用於特定型別的模型，您可以將嵌入模型從初始化任務中排除

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        embedding:
          include: false

此配置將把拉取策略應用於除嵌入模型之外的所有模型。

HuggingFace 模型

Ollama 可以開箱即用地訪問所有 GGUF Hugging Face 嵌入模型。您可以按名稱拉取其中任何一個模型：ollama pull hf.co/<username>/<model-repository> 或配置自動拉取策略：自動拉取模型

spring.ai.ollama.embedding.options.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=always

spring.ai.ollama.embedding.options.model：指定要使用的 Hugging Face GGUF 模型。
spring.ai.ollama.init.pull-model-strategy=always：（可選）在啟動時啟用自動模型拉取。對於生產環境，您應該預先下載模型以避免延遲：ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1。

示例控制器

這將建立一個 EmbeddingModel 實現，您可以將其注入到您的類中。這是一個使用 EmbeddingModel 實現的簡單 @Controller 類的示例。

@RestController
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

手動配置

如果您不使用 Spring Boot，可以手動配置 OllamaEmbeddingModel。為此，請將 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 依賴項還提供了對 OllamaChatModel 的訪問。有關 OllamaChatModel 的更多資訊，請參閱 Ollama 聊天客戶端部分。

接下來，建立一個 OllamaEmbeddingModel 例項，並使用它透過專用的 chroma/all-minilm-l6-v2-f32 嵌入模型計算兩個輸入文字的嵌入

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

var embeddingModel = new OllamaEmbeddingModel(this.ollamaApi,
        OllamaEmbeddingOptions.builder()
			.model(OllamaModel.MISTRAL.id())
            .build());

EmbeddingResponse embeddingResponse = this.embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("chroma/all-minilm-l6-v2-f32"))
            .truncate(false)
            .build());

OllamaEmbeddingOptions 提供所有嵌入請求的配置資訊。