获取最新的快照版本，请使用 Spring AI 1.1.3！spring-doc.cadn.net.cn

变换器（ONNX）嵌入

数字TransformersEmbeddingModel是一个EmbeddingModel实现，它本地计算使用选定的句子嵌入的句子转换器。spring-doc.cadn.net.cn

您可以使用任何HuggingFace嵌入模型。spring-doc.cadn.net.cn

它采用了预训练的变换器模型，以开放式神经网络交换（ONNX）格式序列化。spring-doc.cadn.net.cn

深度Java库Deep Java Library与微软的ONNX Java运行时库ONNX Java Runtime被用于在Java中运行ONNX模型并计算嵌入向量。spring-doc.cadn.net.cn

前提条件

在Java中运行程序，我们需要将Tokenizer和Transformer模型序列化为ONNX格式。spring-doc.cadn.net.cn

使用optimum-cli进行序列化 - 一个快速实现此目的的方法是使用optimum-cli命令行工具。 以下代码片段准备了一个Python虚拟环境，安装了所需包，并使用optimum-cli序列化（例如，导出）指定的模型：spring-doc.cadn.net.cn

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

该代码片段将转换器导出到onnx-output-folder文件夹中。该文件夹包含了嵌入模型所使用的tokenizer.json和model.onnx文件。 spring-doc.cadn.net.cn

您可以选择任何Hugging Face Transformer的标识符来替代all-MiniLM-L6-v2，或者直接提供文件路径。spring-doc.cadn.net.cn

自动配置

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。spring-doc.cadn.net.cn

Spring AI 为 ONNX Transformer 嵌入模型提供了 Spring Boot 自动配置。要启用它，请在项目的 Maven pom.xml 文件中添加以下依赖项：spring-doc.cadn.net.cn

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

或者添加到您的Gradle 构建脚本文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-transformers'
}
参考依赖管理部分，将Spring AI BOM添加到您的构建文件中。 参考制品仓库部分，将这些仓库添加到您的构建系统中。

要进行配置，请使用spring.ai.embedding.transformer.*属性。spring-doc.cadn.net.cn

例如，向您的application.properties文件中添加以下内容，以使用文本嵌入模型配置客户端： spring-doc.cadn.net.cn

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

支持的属性完整列表包括：spring-doc.cadn.net.cn

嵌入属性

启用和禁用嵌入式自动配置现在通过带有前缀 spring.ai.model.embedding 的顶级属性进行配置。spring-doc.cadn.net.cn

要启用，请设置 spring.ai.model.embedding=transformers （默认情况下已启用）spring-doc.cadn.net.cn

要禁用，请设置 spring.ai.model.embedding=none（或任何不匹配 transformers 的值）spring-doc.cadn.net.cn

这种修改是为了允许配置多个模型。spring-doc.cadn.net.cn
属性 描述 默认

spring.ai.embedding.transformer.enabled（已移除，不再有效）spring-doc.cadn.net.cn

启用Transformer嵌入模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.model.embeddingspring-doc.cadn.net.cn

启用Transformer嵌入模型。spring-doc.cadn.net.cn

转换器spring-doc.cadn.net.cn

spring.ai.embedding.transformer.tokenizer.urispring-doc.cadn.net.cn

通过ONNX引擎创建的预训练HuggingFace分词器的URI（例如：tokenizer.json）。spring-doc.cadn.net.cn

onnx/all-MiniLM-L6-v2/tokenizer.jsonspring-doc.cadn.net.cn

spring.ai.embedding.transformer.tokenizer.optionsspring-doc.cadn.net.cn

HuggingFace分词器选项，如‘addSpecialTokens’、‘modelMaxLength’、‘truncation’、‘padding’、‘maxLength’、‘stride’、‘padToMultipleOf’。留空以使用默认值。spring-doc.cadn.net.cn

emptyspring-doc.cadn.net.cn

spring.ai.embedding.transformer.cache.enabledspring-doc.cadn.net.cn

启用远程资源缓存。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.embedding.transformer.cache.directoryspring-doc.cadn.net.cn

远程资源（如ONNX模型）的缓存目录路径spring-doc.cadn.net.cn

${java.io.tmpdir}/spring-ai-onnx-modelspring-doc.cadn.net.cn

spring.ai.embedding.transformer.onnx.modelUrispring-doc.cadn.net.cn

现有预训练的ONNX模型。spring-doc.cadn.net.cn

onnx/all-MiniLM-L6-v2/model.onnxspring-doc.cadn.net.cn

spring.ai.embedding.transformer.onnx.modelOutputNamespring-doc.cadn.net.cn

ONNX模型的输出节点名称，我们将使用它来进行嵌入计算。spring-doc.cadn.net.cn

last_hidden_statespring-doc.cadn.net.cn

spring.ai.embedding.transformer.onnx.gpuDeviceIdspring-doc.cadn.net.cn

在GPU上执行时使用的设备ID。仅当该值大于等于0时适用，否则将被忽略。（需要额外的onnxruntime_gpu依赖）spring-doc.cadn.net.cn

-1spring-doc.cadn.net.cn

spring.ai.embedding.transformer.metadataModespring-doc.cadn.net.cn

指定文档内容和元数据的哪些部分将用于计算嵌入。spring-doc.cadn.net.cn

NONEspring-doc.cadn.net.cn

错误和特殊案例

如果看到类似Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,..的错误，还需要在application.properties中启用分词器填充，如下所示：spring-doc.cadn.net.cn

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-doc.cadn.net.cn

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。spring-doc.cadn.net.cn

数字model.onnx_data被称为外部数据，应位于model.onnx的同一目录下。spring-doc.cadn.net.cn

目前唯一的解决方法是将大写的model.onnx_data复制到运行Boot应用程序的文件夹中。spring-doc.cadn.net.cn

如果遇到类似错误 ai.onnxruntime.OrtException: Error code - ORT_EP_FAIL - message: Failed to find CUDA shared provider， 这意味着您正在使用GPU参数 spring.ai.embedding.transformer.onnx.gpuDeviceId ，但缺少onnxruntime_gpu依赖项。spring-doc.cadn.net.cn

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

请选择与CUDA版本相匹配的onnxruntime_gpu版本(ONNX Java运行时)。spring-doc.cadn.net.cn

手动配置

如果不使用Spring Boot，您可以手动配置Onnx Transformers嵌入模型。 为此，请将spring-ai-transformers依赖项添加到项目Mavenpom.xml文件中:spring-doc.cadn.net.cn

<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模式)。spring-doc.cadn.net.cn

如果模型未被显式设置，默认使用TransformersEmbeddingModel表示sentence-transformers/all-MiniLM-L6-v2:spring-doc.cadn.net.cn

维度spring-doc.cadn.net.cn

384spring-doc.cadn.net.cn

平均性能spring-doc.cadn.net.cn

58.80spring-doc.cadn.net.cn

速度spring-doc.cadn.net.cn

14200 句/秒spring-doc.cadn.net.cn

大小spring-doc.cadn.net.cn

80MBspring-doc.cadn.net.cn

以下代码片段展示了如何手动使用 TransformersEmbeddingModel：spring-doc.cadn.net.cn

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。spring-doc.cadn.net.cn

更便捷（且推荐）的方式是将TransformersEmbeddingModel创建为Bean。 这样就不需要手动调用afterPropertiesSet()了。spring-doc.cadn.net.cn

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