Ollama Embeddings

透過 Ollama，您可以在本機執行各種人工智慧模型，並從中產生嵌入。嵌入是一個浮點數的向量（列表）。兩個向量之間的距離衡量它們的相關性。小距離表示高度相關，大距離表示低度相關。

OllamaEmbeddingModel 實作利用 Ollama Embeddings API 端點。

先決條件

您首先需要存取 Ollama 實例。有幾種選項，包括以下

在您的本機電腦上下載並安裝 Ollama。
透過Testcontainers 配置並執行 Ollama。
透過Kubernetes Service Bindings 綁定到 Ollama 實例。

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

ollama pull <model-name>

您也可以提取數千個免費的 GGUF Hugging Face 模型

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

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

自動配置

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

Maven
Gradle

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

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

請參閱依賴項管理章節，將 Spring AI BOM 新增到您的建置檔案中。Spring AI artifacts 發佈在 Spring Milestone 和 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.ollama.embedding.options 是用於配置 Ollama 嵌入模型的屬性前綴。它包括 Ollama 請求（進階）參數，例如 model、keep-alive 和 truncate，以及 Ollama 模型 options 屬性。

以下是 Ollama 嵌入模型的進階請求參數

屬性

描述

預設值

spring.ai.ollama.embedding.enabled

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

true

spring.ai.ollama.embedding.options.model

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

mistral

spring.ai.ollama.embedding.options.keep_alive

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

spring.ai.ollama.embedding.options.truncate

截斷每個輸入的結尾，以符合上下文長度。如果為 false 且超出上下文長度，則傳回錯誤。

true

剩餘的 options 屬性基於 Ollama Valid Parameters and Values 和 Ollama Types。預設值基於：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，而不僅僅是最後一個。若要啟用完成以傳回 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.tfs-z

Tail-free 採樣用於減少輸出中較低機率 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 中指定多個單獨的 stop 參數來設定多個停止模式。

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()
            .withModel("Different-Embedding-Model-Deployment-Name"))
            .withtTuncates(false)
            .build());

自動提取模型

當 Spring AI Ollama 模型在您的 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

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

範例控制器

這將建立一個 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 Chat Client 章節。

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

var ollamaApi = new OllamaApi();

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

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

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