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://hugging-face.cn/intfloat/e5-small-v2/resolve/main/model.onnx
spring.ai.embedding.transformer.tokenizer.uri=https://hugging-face.cn/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();
}