TransformersEmbeddingClient`是一个`EmbeddingClient`实现，它在本地使用选定的[sentence transformer](sentence embeddings(https://www.sbert.net/examples/applications/computing-embeddings/README.html#sentence-embeddings-with-transformers)。

它使用了预训练的变换器模型，这些模型被序列化成Open Neural Network Exchange (ONNX)格式。

"The Deep Java Library和Microsoft ONNX Java Runtime图书馆用于运行ONNX模型并在Java中计算嵌入。"

序列化分词器和变换模型

在Java中运行程序，我们需要将分词器和变换模型序列化为ONNX格式。

使用optimum-cli序列化

一个快速实现这一目的的方法，是使用https://huggingface.co/docs/optimum/exporters/onnx/usage_guides/export_a_model#exporting-a-model-to-onnx-using-the-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
(venv) optimum-cli export onnx --generative sentence-transformers/all-MiniLM-L6-v2 onnx-output-folder

片段将https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2[sentence-transformers/all-MiniLM-L6-v2]转换器导出到`onnx-output-folder`文件夹中。之后包括嵌入客户端使用的`tokenizer.json`和`model.onnx`文件。

您可以选择任何huggingface变换器标识符或直接提供文件路径，以替代all-MiniLM-L6-v2。

使用ONNX Transformers模型

将 spring-ai-transformers 项目添加到你的maven依赖中：

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

然后创建一个新的 TransformersEmbeddingClient 实例，并使用 setTokenizerResource(tokenizerJsonUri) 和 setModelResource(modelOnnxUri) 方法来设置导出的 tokenizer.json 和 model.onnx 文件的URI（支持 classpath:、file: 或 https: URI方案）。

如果模型没有被显式设置，TransformersEmbeddingClient 默认使用 sentence-transformers/all-MiniLM-L6-v2；

维度

384

平均性能

58.80

速度

14200 句/秒

大小

80MB

以下代码片段展示了如何手动使用`TransformersEmbeddingClient`：

TransformersEmbeddingClient embeddingClient = new TransformersEmbeddingClient();

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

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

// (optional) defaults to ${java.io.tmpdir}/spring-ai-onnx-model
// 默认情况下，只有http/https资源会被缓存。
embeddingClient.setResourceCacheDirectory("/tmp/onnx-zoo");

// (可选) 如果您看到类似以下错误，请设置分词器的填充选项：
// "ai.onnxruntime.OrtException: 提供的数组是不规则的，..."
embeddingClient.setTokenizerOptions(Map.of("padding", "true"));

embeddingClient.afterPropertiesSet();

List<List<Double>> embeddings = embeddingClient.embed(List.of("Hello world", "World is big"));
Note
 在手动创建时，你必须在设置属性后和使用客户端之前调用`afterPropertiesSet()`方法。

第一次调用`embed()会下载大型ONNX模型并将其缓存到本地文件系统上。因此，第一次调用可能会比平时更久。使用#setResourceCacheDirectory(<path>)方法来设置存储ONNX模型的本地文件夹。默认的缓存文件夹是${java.io.tmpdir}/spring-ai-onnx-model`。

把 TransformersEmbeddingClient 作为一个 Bean 创建会更方便（并且更受欢迎）。这样你就不必手动调用 afterPropertiesSet() 方法了。

@Bean
public EmbeddingClient embeddingClient() {
   return new TransformersEmbeddingClient();
}

Transformers 嵌入式 Spring Boot 启动器

您可以使用以下Spring Boot启动器来引导和自动装配`TransformersEmbeddingClient`：

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-transformers-spring-boot-starter</artifactId>
</dependency>
Tip
 请参阅依赖管理部分，以将Spring AI BOM添加到您的构建文件中。

要配置它，请使用 spring.ai.embedding.transformer.* 属性。

例如，将此添加到您的_application.properties_文件中，以使用https://huggingface.co/intfloat/e5-small-v2[intfloat/e5-small-v2]文本嵌入模型配置客户端：

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.ai.embedding.transformer.enabled

启用 Transformer Embedding 客户端。

true

spring.ai.embedding.transformer.tokenizer.uri

由 ONNX 引擎创建的预训练 HuggingFace Tokenizer的 URI（例如 tokenizer.json）。

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

spring.ai.embedding.transformer.tokenizer.options

HuggingFace Tokenizer 选项，例如 ‘addSpecialTokens’, ‘modelMaxLength’, ‘truncation’, ‘padding’, ‘maxLength’, ‘stride’, ‘padToMultipleOf’。若为空，则使用默认设置。

empty

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.gpuDeviceId

要执行的 GPU 设备 ID。仅当 >= 0 时适用。否则忽略。

-1

spring.ai.embedding.transformer.metadataMode

指定在计算嵌入时将使用文档内容和元数据的哪些部分。

NONE
Note
 如果你看到类似`Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,..`的错误，你需要在`application.properties`中启用分词器填充，如下所示： 
spring.ai.embedding.transformer.tokenizer.options.padding=true