Transformers (ONNX) Embeddings
TransformersEmbeddingModel
是一种 EmbeddingModel
实现,它通过选定的 sentence transformer
在本地计算 sentence embeddings
。
您可以使用任何 HuggingFace 嵌入模型
它使用 预训练 的 transformer 模型,并序列化为 开放神经网络交换(ONNX)
格式。
Deep Java Library 与微软的 ONNX Java 运行时 库被应用于运行 ONNX 模型并在 Java 中计算嵌入。
前提条件(Prerequisites)
要在 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 转换器导出至 onnx-output-folder
文件夹。后者包含了嵌入模型所使用的 tokenizer.json
和 model.onnx
文件。
您可以选择任何 Hugging Face 的 transformer 标识符或直接提供文件路径
,以替代 all-MiniLM-L6-v2
。
自动配置(Auto-configuration)
Spring AI 为ONNX Transformer 嵌入客户端提供了 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.embedding.transformer.*
属性。
如,将此添加到您的 application.properties 文件中,以使用 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
支持的完整属性列表如下:
嵌入属性(Embedding Properties)
属性 | 描述 | 默认值 |
---|---|---|
spring.ai.embedding.transformer.enabled (已移除且无效) | 启用Transformer嵌入模型 | true |
spring.ai.model.embedding | 启用Transformer嵌入模型 | 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’等 | 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.modelOutputName | 用于嵌入计算的ONNX模型输出节点名称 | last_hidden_state |
spring.ai.embedding.transformer.onnx.gpuDeviceId | 执行的GPU设备ID(需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
- 如果遇到类似 “生成输出名称不包含预期值:last_hidden_state。请考虑使用以下可用模型输出之一:token_embeddings,…” 的错误,您需要根据您的模型将模型输出名称设置为正确的值。请参考错误消息中列出的名称。例如:
spring.ai.embedding.transformer.onnx.modelOutputName=token_embeddings
- 如果您遇到类似‘ai.onnxruntime.OrtException: 错误代码 - ORT_FAIL - 消息:反序列化张量 onnx::MatMul_10319 失败。获取./model.onnx_data 的文件长度失败:提供的文件描述符无效:-1‘的错误,这意味着您的模型大小超过 2GB,并被序列化为两个文件:model.onnx 和 model.onnx_data。
Model.onnx_data 被称为 外部数据 ,并预期与 model.onnx 位于同一目录下。
目前唯一的解决办法是将大型的‘model.onnx_data‘文件复制到运行 Boot 应用程序的文件夹中。 - 如果您遇到类似 ‘ai.onnxruntime.OrtException: 错误代码 - ORT_EP_FAIL - 消息: 未能找到 CUDA 共享提供程序‘ 的错误,这意味着您正在使用 GPU 参数 ‘spring.ai.embedding.transformer.onnx.gpuDeviceId‘,但缺少 ‘onnxruntime_gpu‘ 依赖项。
请根据 CUDA 版本选择合适的 onnxruntime_gpu 版本(ONNX Java 运行时 )。<dependency> <groupId>com.microsoft.onnxruntime</groupId> <artifactId>onnxruntime_gpu</artifactId> </dependency>
手动配置(Manual Configuration)
如果您未使用 Spring Boot,可以手动配置 Onnx Transformers
嵌入模型。为此,请将 spring-ai-transformers
依赖项添加到项目的 Maven pom.xml
文件中:
要启用它,添加 spring-oci-genai-openai
依赖到你的项目 Maven pom.xml
文件:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-transformers</artifactId>
</dependency>
随后创建一个新的 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"));
首次调用 embed ()
方法会下载大型 ONNX 模型并将其缓存到本地文件系统中。因此,首次调用可能会比平常花费更长时间。可以使用 ‘#setResourceCacheDirectory (< 路径>)‘
方法来设置存储 ONNX 模型的本地文件夹。默认的缓存文件夹是 ‘${java.io.tmpdir}/spring-ai-onnx-model‘
。
将 TransformersEmbeddingModel
创建为 Bean 更为便捷(且推荐)。这样,您就无需手动调用 afterPropertiesSet ()
方法。
@Bean
public EmbeddingModel embeddingModel() {
return new TransformersEmbeddingModel();
}
最后编辑:Jeebiz 更新时间:2025-08-31 23:07