Transformers (ONNX) 埋め込み

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

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

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

トークナイザーと Transformer モデルを直列化する

Java で実行するには、Tokenizer と Transformer Model を 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
(venv) optimum-cli export onnx --generative 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 トランス識別子を選択するか、直接ファイルパスを指定できます。

ONNX Transformers モデルの使用

spring-ai-transformers プロジェクトを maven 依存関係に追加します。

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

Transformers エンベデッド Spring Boot スターター

次の Spring Boot スターターを使用して TransformersEmbeddingModel をブートストラップしてオートワイヤーできます。

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-transformers-spring-boot-starter</artifactId>
</dependency>
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.embedding.transformer.enabled

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

true

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 の場合にのみ適用されます。それ以外の場合は無視されます。

-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
Exception in thread "main" java.lang.IllegalArgumentException: The generative output names doesn’t contain expected: last_hidden_state のようなエラーが発生した場合は、モデルごとにモデル出力名を正しい値に設定する必要があります。例:
spring.ai.embedding.transformer.onnx.modelOutputName=token_embeddings