此版本仍在开发中，尚未被视为稳定版本。最新的快照版本请使用 Spring AI 1.0.0-SNAPSHOT！spring-doc.cn

转换器 （ONNX） 嵌入

这是一种使用选定的 sentence transformer 在本地计算句子嵌入的实现。TransformersEmbeddingModelEmbeddingModelspring-doc.cn

您可以使用任何 HuggingFace Embedding 模型。spring-doc.cn

它使用预先训练的 transformer 模型，序列化为 Open Neural Network Exchange （ONNX） 格式。spring-doc.cn

Deep Java 库和 Microsoft ONNX Java 运行时库用于运行 ONNX 模型并计算 Java 中的嵌入。spring-doc.cn

先决条件

要在 Java 中运行，我们需要将 Tokenizer 和 Transformer Model 序列化为格式。ONNXspring-doc.cn

使用 optimum-cli 进行序列化 - 实现此目的的一种快速方法是使用 optimum-cli 命令行工具。 以下代码段准备 python 虚拟环境，安装所需的包并使用 ：optimum-clispring-doc.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

该代码段将 sentence-transformers/all-MiniLM-L6-v2 转换器导出到文件夹中。后者包括嵌入模型使用的 and 文件。onnx-output-foldertokenizer.jsonmodel.onnxspring-doc.cn

您可以选择任何 huggingface 转换器标识符或提供直接文件路径，而不是全 MiniLM-L6-v2。spring-doc.cn

自动配置

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

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

或您的 Gradle 构建文件。build.gradlespring-doc.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-transformers-spring-boot-starter'
}
请参阅 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。 请参阅 Repositories 部分，将这些存储库添加到您的构建系统中。

要配置它，请使用 properties.spring.ai.embedding.transformer.*spring-doc.cn

例如，将此内容添加到您的 application.properties 文件中，以使用 intfloat/e5-small-v2 文本嵌入模型配置客户端：spring-doc.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.cn

嵌入属性

财产 描述 违约

spring.ai.embedding.transformer.enabledspring-doc.cn

启用 Transformer Embedding 模型。spring-doc.cn

真spring-doc.cn

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

由 ONNX 引擎创建的预训练 HuggingFaceTokenizer 的 URI（例如 tokenizer.json）。spring-doc.cn

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

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

HuggingFaceTokenizer 选项，例如 'addSpecialTokens'、'modelMaxLength'、'truncation'、'padding'、'maxLength'、'stride'、'padToMultipleOf'。留空可回退到默认值。spring-doc.cn

空spring-doc.cn

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

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

真spring-doc.cn

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

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

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

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

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

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

spring.ai.embedding.transformer.onnx.model输出名称spring-doc.cn

ONNX 模型的输出节点名称，我们将用于嵌入计算。spring-doc.cn

last_hidden_statespring-doc.cn

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

要执行的 GPU 设备 ID。仅当 >= 0 时适用。否则为 Ignored。（需要额外的 onnxruntime_gpu 依赖项）spring-doc.cn

-1spring-doc.cn

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

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

没有spring-doc.cn

错误和特殊情况

如果您看到类似 的错误，则还需要启用分词器填充，如下所示：Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,..application.propertiesspring-doc.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.cn

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

如果您收到类似 ， 这意味着您的模型大于 2GB，并序列化为两个文件：和 .ai.onnxruntime.OrtException: Error code - ORT_FAIL - message: Deserialize tensor onnx::MatMul_10319 failed.GetFileLength for ./model.onnx_data failed:Invalid fd was supplied: -1model.onnxmodel.onnx_dataspring-doc.cn

称为 External Data，应位于 的同一目录下。model.onnx_datamodel.onnxspring-doc.cn

目前，唯一的解决方法是将 large 复制到运行 Boot 应用程序的文件夹中。model.onnx_dataspring-doc.cn

如果您收到类似 ， 这意味着您使用的是 GPU parameters ，但缺少 onnxruntime_gpu 依赖项。ai.onnxruntime.OrtException: Error code - ORT_EP_FAIL - message: Failed to find CUDA shared providerspring.ai.embedding.transformer.onnx.gpuDeviceIdspring-doc.cn

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

请根据 CUDA 版本（ONNX Java Runtime）选择合适的 onnxruntime_gpu 版本。spring-doc.cn

手动配置

如果您不使用 Spring Boot，则可以手动配置 Onnx Transformers Embedding Model。 为此，请将依赖项添加到项目的 Maven 文件中：spring-ai-transformerspom.xmlspring-doc.cn

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-transformers</artifactId>
</dependency>
请参阅 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。

然后创建一个新实例，并使用 and 方法设置导出的 and 文件的 URI。（或 URI 架构）。TransformersEmbeddingModelsetTokenizerResource(tokenizerJsonUri)setModelResource(modelOnnxUri)tokenizer.jsonmodel.onnxclasspath:file:https:spring-doc.cn

如果未明确设置模型，则默认为 sentence-transformers/all-MiniLM-L6-v2：TransformersEmbeddingModelspring-doc.cn

尺寸spring-doc.cn

384spring-doc.cn

平均性能spring-doc.cn

58.80spring-doc.cn

速度spring-doc.cn

14200 句/秒spring-doc.cn

大小spring-doc.cn

80兆字节spring-doc.cn

以下代码段说明了如何手动使用：TransformersEmbeddingModelspring-doc.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"));
如果手动创建 的实例，则必须在设置属性之后和使用客户端之前调用该方法。TransformersEmbeddingModelafterPropertiesSet()

第一次调用下载大型 ONNX 模型并将其缓存在本地文件系统上。 因此，第一次调用可能需要比平时更长的时间。 使用该方法将 ONNX 模型的存储位置设置为本地文件夹。 默认缓存文件夹为 .embed()#setResourceCacheDirectory(<path>)${java.io.tmpdir}/spring-ai-onnx-modelspring-doc.cn

将 TransformersEmbeddingModel 创建为 . 然后，您不必手动调用 。BeanafterPropertiesSet()spring-doc.cn

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