TransformersEmbeddingModel 是一种 EmbeddingModel 实现，它可以在本地使用选定的句子转换器模型计算句子嵌入向量。你可以使用任意 HuggingFace 嵌入模型，它采用预训练的 Transformer 模型，并序列化为开放神经网络交换（ONNX）格式。
该实现使用 Deep Java Library 和微软 ONNX Java 运行时库，在 Java 环境中运行 ONNX 模型并计算嵌入向量。
前提条件
要在 Java 中运行，需要将分词器（Tokenizer）和 Transformer 模型序列化为 ONNX 格式。
最快捷的方式是使用 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 文件。
你可以替换为任意 HuggingFace 模型标识或本地文件路径。
自动配置
Spring AI 自动配置与启动器模块名称已变更，详情请参考升级说明。
Spring AI 为 ONNX Transformer 嵌入模型提供 Spring Boot 自动配置，在 Maven 中添加依赖：
org.springframework.aispring-ai-starter-model-transformers
Gradle 依赖：
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-transformers'
}参考依赖管理章节添加 Spring AI BOM，参考构件仓库章节添加仓库源。
使用 spring.ai.embedding.transformer.* 配置属性，示例（使用 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.model.embedding=transformers（默认启用）禁用：
spring.ai.model.embedding=none
| 配置属性 | 说明 | 默认值 |
|---|---|---|
| spring.ai.embedding.transformer.enabled（已废弃） | 启用 Transformer 嵌入模型 | true |
| spring.ai.model.embedding | 启用 Transformer 嵌入模型 | transformers |
| spring.ai.embedding.transformer.tokenizer.uri | 分词器 JSON 文件地址 | onnx/all-MiniLM-L6-v2/tokenizer.json |
| spring.ai.embedding.transformer.tokenizer.options | 分词器参数（padding、truncation 等） | 空 |
| spring.ai.embedding.transformer.cache.enabled | 启用远程资源缓存 | true |
| spring.ai.embedding.transformer.cache.directory | 缓存目录 | ${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 | 模型输出节点名称 | last_hidden_state |
| spring.ai.embedding.transformer.onnx.gpuDeviceId | GPU 设备 ID（≥0 生效） | -1 |
| spring.ai.embedding.transformer.metadataMode | 文档元数据嵌入模式 | NONE |
常见错误与解决方案
数组不规整错误：
Supplied array is ragged
spring.ai.embedding.transformer.tokenizer.options.padding=true
输出节点不匹配：don’t contain expected: last_hidden_state
spring.ai.embedding.transformer.onnx.modelOutputName=token_embeddings
模型大于 2GB 外部数据错误：将 model.onnx_data 放到应用启动目录，与 model.onnx 同级
CUDA 共享提供程序缺失：添加 GPU 依赖
com.microsoft.onnxruntimeonnxruntime_gpu
手动配置
不使用 Spring Boot 时，手动添加依赖：
org.springframework.aispring-ai-transformers
手动创建 TransformersEmbeddingModel 示例：
TransformersEmbeddingModel embeddingModel = new TransformersEmbeddingModel();
// 设置分词器
embeddingModel.setTokenizerResource("classpath:/onnx/all-MiniLM-L6-v2/tokenizer.json");
// 设置模型
embeddingModel.setModelResource("classpath:/onnx/all-MiniLM-L6-v2/model.onnx");
// 设置缓存目录
embeddingModel.setResourceCacheDirectory("/tmp/onnx-zoo");
// 启用填充
embeddingModel.setTokenizerOptions(Map.of("padding", "true"));
// 必须调用
embeddingModel.afterPropertiesSet();
// 生成嵌入向量
List> embeddings = embeddingModel.embed(List.of("Hello world", "World is big"));注意：手动创建必须调用 afterPropertiesSet()，首次调用会下载并缓存模型，耗时较长。
推荐注册为 Bean：
@Bean
public EmbeddingModel embeddingModel() {
return new TransformersEmbeddingModel();
}默认模型信息
模型：sentence-transformers/all-MiniLM-L6-v2
向量维度：384
平均性能：58.80
速度：14200 句/秒
大小：80MB
