このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.0.3 を使用してください。

Transformers (ONNX) 埋め込み

TransformersEmbeddingModel は、選択された sentence transformer (英語) を使用して sentence embeddings (英語) をローカルに計算する EmbeddingModel 実装です。

任意の HuggingFace 埋め込みモデル (英語) を使用できます。

オープンニューラルネットワーク交換 (ONNX) (英語) 形式に直列化された、事前トレーニング済み (英語) のトランスフォーマーモデルを使用します。

ディープ Java ライブラリ (英語) と Microsoft ONNX Java ランタイム (英語) ライブラリは、ONNX モデルを実行し、Java で埋め込みを計算するために適用されます。

前提条件

Java で実行するには、Tokenizer と Transformer モデルを ONNX 形式に直列化する必要があります。

optimum-cli で直列化 - これを実現する簡単な方法の 1 つは、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 ファイルが含まれます。

all-MiniLM-L6-v2 の代わりに、任意の huggingface トランス識別子を選択するか、直接ファイルパスを指定できます。

自動構成

Spring AI 自動構成、スターターモジュールのアーティファクト名に大きな変更がありました。詳細については、アップグレードノートを参照してください。

Spring AI は、ONNX Transformer Embedding Model 用の 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 BOM をビルドファイルに追加するには、依存関係管理セクションを参照してください。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリセクションを参照してください。

これを構成するには、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

サポートされているプロパティの完全なリストは次のとおりです。

埋め込みプロパティ

埋め込み自動構成の有効化と無効化は、プレフィックス spring.ai.model.embedding を持つ最上位プロパティを介して構成されるようになりました。

有効にするには、spring.ai.model.embedding=transformers (デフォルトで有効になっています)

無効にするには、spring.ai.model.embedding=none (またはトランスフォーマーと一致しない値)

この変更は、複数のモデルの構成を可能にするために行われます。

プロパティ 説明 デフォルト

spring.ai.embedding.transformer.enabled (削除され、無効になりました)

Transformer Embedding モデルを有効にします。

true

spring.ai.model.embedding

Transformer Embedding モデルを有効にします。

トランスフォーマー

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

ドキュメントのコンテンツとメタデータのどの部分を埋め込みの計算に使用するかを指定します。

NONE

エラーと特殊なケース

Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,.. のようなエラーが表示された場合は、次のように application.properties のトークナイザーパディングも有効にする必要があります。

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.ai.embedding.transformer.onnx.modelOutputName=token_embeddings

ai.onnxruntime.OrtException: Error code - ORT_FAIL - message: Deserialize tensor onnx::MatMul_10319 failed.GetFileLength for ./model.onnx_data failed:Invalid fd was supplied: -1 のようなエラーが発生した場合は、モデルが 2GB より大きく、model.onnx と model.onnx_data の 2 つのファイルに直列化されていることを意味します。

model.onnx_data は外部データ (英語) と呼ばれ、model.onnx と同じディレクトリにあると予想されます。

現在、唯一の回避策は、Boot アプリケーションを実行するフォルダーに大きな model.onnx_data をコピーすることです。

ai.onnxruntime.OrtException: Error code - ORT_EP_FAIL - message: Failed to find CUDA shared provider のようなエラーが発生した場合は、GPU パラメーター spring.ai.embedding.transformer.onnx.gpuDeviceId を使用しているものの、onnxruntime_gpu 依存関係が欠落していることを意味します。

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

CUDA バージョン (ONNX Java ランタイム (英語) ) に基づいて適切な onnxruntime_gpu バージョンを選択してください。

手動構成

Spring Boot を使用していない場合は、Onnx Transformers Embedding Model を手動で構成できます。そのためには、プロジェクトの Maven pom.xml ファイルに spring-ai-transformers 依存関係を追加します。

<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();
}