Ollama 嵌入

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

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

前提條件

首先，你需要能夠訪問一個 Ollama 例項。有幾種選項，包括以下幾種：

你可以從 Ollama 模型庫中拉取你想在應用中使用的模型

ollama pull <model-name>

你也可以拉取數千個免費的 GGUF Hugging Face 模型中的任何一個

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

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

自動配置

Spring AI 自動配置、starter 模組的 artifact 名稱發生了重大變化。有關詳細資訊，請參閱升級說明。

Spring AI 為 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 artifact 釋出在 Maven Central 和 Spring Snapshot 倉庫中。請參閱倉庫部分，將這些倉庫新增到你的構建系統中。

基礎屬性

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.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

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

mistral

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。

false

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

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

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

false

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

true

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

返回所有 token 的 logits，而不僅僅是最後一個。要使 completions 返回 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 而減慢載入時間，從而犧牲了記憶體對映的一些優勢。

false

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

生成文字時預測的最大 token 數。（-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 表示 token 被考慮的最低機率，相對於最有可能的 token 的機率。例如，當 p=0.05 且最有可能的 token 的機率為 0.9 時，值小於 0.045 的 logits 將被過濾掉。

0.0

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

無尾取樣用於減少輸出中機率較低的 token 的影響。較高的值（例如 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 呼叫新增請求特定的執行時選項來覆蓋。

執行時選項

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

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

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

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

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaOptions.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。

示例 Controller

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

@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,
        OllamaOptions.builder()
			.model(OllamaModel.MISTRAL.id())
            .build());

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

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