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.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=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 |
错误和特殊情况
如果您看到类似 spring.ai.embedding.transformer.tokenizer.options.padding=true |
如果您收到类似 spring.ai.embedding.transformer.onnx.modelOutputName=token_embeddings |
如果您收到类似
目前唯一的解决方法是将大型 |
如果您收到类似 <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();
}