Ollama 埋め込み
Ollama (英語) を使用すると、さまざまな AI モデル (英語) をローカルで実行し、そこから埋め込みを生成できます。埋め込みは、浮動小数点数のベクトル (リスト) です。2 つのベクトル間の距離は、それらの関連性を測定します。距離が小さいと関連性が高く、距離が大きいと関連性が低いことを示します。
OllamaEmbeddingModel 実装では、Ollama Embeddings API [GitHub] (英語) エンドポイントを活用します。
前提条件
まず、Ollama インスタンスにアクセスする必要があります。次のようないくつかのオプションがあります。
ローカルマシン上の Ollama をダウンロードしてインストールします (英語) 。
Kubernetes サービスバインディングを介して Ollama インスタンスにバインドします。
アプリケーションで使用するモデルを Ollama モデルライブラリ (英語) から取得できます。
ollama pull <model-name>何千もの中からフリーで GGUF Hugging Face モデル (英語) を引くこともできます:
ollama pull hf.co/<username>/<model-repository>あるいは、必要なモデル自動プルモデルを自動的にダウンロードするオプションを有効にすることもできます。
自動構成
Spring AI は、Azure Ollama 埋め込みモデル用の Spring Boot 自動構成を提供します。これを有効にするには、Maven pom.xml または Gradle build.gradle ビルドファイルに次の依存関係を追加します。
Maven
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-ollama-spring-boot-starter'
}| 依存関係管理セクションを参照して、Spring AI BOM をビルドファイルに追加してください。Spring AI アーティファクトは、Maven Central リポジトリと Spring スナップショットリポジトリで公開されています。これらのリポジトリをビルドシステムに追加するには、リポジトリセクションを参照してください。 |
基本プロパティ
接頭辞 spring.ai.ollama は、Ollama への接続を構成するためのプロパティ接頭辞です。
プロパティ | 説明 | デフォルト |
spring.ai.ollama.base-url | Ollama API サーバーが実行されているベース URL。 |
Ollama 統合および自動プルモデルを初期化するためのプロパティを次に示します。
プロパティ | 説明 | デフォルト |
spring.ai.ollama.init.pull-model-strategy | 起動時にモデルをプルするかどうか、およびその方法。 |
|
spring.ai.ollama.init.timeout | モデルがプルされるまで待機する時間。 |
|
spring.ai.ollama.init.max-retries | モデルプル操作の最大再試行回数。 |
|
spring.ai.ollama.init.embedding.include | この型のモデルを初期化タスクに含めます。 |
|
spring.ai.ollama.init.embedding.additional-models | デフォルトのプロパティで構成されたモデル以外に初期化する追加のモデル。 |
|
埋め込みプロパティ
プレフィックス spring.ai.ollama.embedding.options は、Ollama 埋め込みモデルを構成するプロパティプレフィックスです。これには、model、keep-alive、truncate などの Ollama リクエスト (詳細) パラメーターと、Ollama モデル options プロパティが含まれます。
Ollama 埋め込みモデルの高度なリクエストパラメーターは次のとおりです。
プロパティ | 説明 | デフォルト |
spring.ai.ollama.embedding.enabled | Ollama 埋め込みモデルの自動構成を有効にします。 | true |
spring.ai.ollama.embedding.options.model | 使用するサポート対象モデル [GitHub] (英語) の名前。専用の埋め込みモデル (英語) 型を使用できます | ミストラル |
spring.ai.ollama.embedding.options.keep_alive | リクエスト後にモデルがメモリにロードされたままになる時間を制御します | 5 分 |
spring.ai.ollama.embedding.options.truncate | 各入力の末尾を切り捨てて、コンテキストの長さに合わせます。false でコンテキストの長さを超えた場合はエラーを返します。 | true |
残りの options プロパティは、Ollama の有効なパラメーターと値 [GitHub] (英語) および Ollama 型 [GitHub] (英語) に基づいています。デフォルト値は、Ollama 型のデフォルト [GitHub] (英語) に基づいています。
プロパティ | 説明 | デフォルト |
spring.ai.ollama.embedding.options.numa | NUMA を使用するかどうか。 | false |
spring.ai.ollama.embedding.options.num-ctx | 次のトークンの生成に使用されるコンテキストウィンドウのサイズを設定します。 | 2048 |
spring.ai.ollama.embedding.options.num-batch | プロンプト処理の最大バッチサイズ。 | 512 |
spring.ai.ollama.embedding.options.num-gpu | GPU に送信するレイヤーの数。macOS では、メタルサポートを有効にする場合はデフォルトで 1、無効にする場合は 0 です。ここで 1 は、NumGPU を動的に設定する必要があることを示します | -1 |
spring.ai.ollama.embedding.options.main-gpu | 複数の GPU を使用する場合、このオプションは、すべての GPU に計算を分割するオーバーヘッドが価値のない小さなテンソルに使用する GPU を制御します。問題の GPU は、一時的な結果用のスクラッチバッファーを保存するために、わずかに多くの VRAM を使用します。 | 0 |
spring.ai.ollama.embedding.options.low-vram | - | false |
spring.ai.ollama.embedding.options.f16-kv | - | true |
spring.ai.ollama.embedding.options.logits-all | 最後のトークンだけでなく、すべてのトークンの logits を返します。補完が logprob を返すようにするには、これが true である必要があります。 | - |
spring.ai.ollama.embedding.options.vocab-only | 重みではなく語彙のみをロードします。 | - |
spring.ai.ollama.embedding.options.use-mmap | デフォルトでは、モデルはメモリにマップされるため、システムは必要に応じてモデルの必要な部分のみを読み込むことができます。ただし、モデルが RAM の合計量よりも大きい場合、またはシステムの使用可能なメモリが少ない場合は、mmap を使用するとページアウトのリスクが高まり、パフォーマンスに悪影響を与える可能性があります。mmap を無効にすると読み込み時間が遅くなりますが、mlock を使用していない場合はページアウトが減る可能性があります。モデルが RAM の合計量よりも大きい場合、mmap をオフにするとモデルがまったく読み込まれなくなることに注意してください。 | null |
spring.ai.ollama.embedding.options.use-mlock | モデルをメモリにロックし、メモリマップ時にスワップアウトされないようにします。これによりパフォーマンスは向上しますが、実行により多くの RAM が必要になり、モデルが RAM にロードされるときにロード時間が遅くなる可能性があるため、メモリマッピングの利点の一部が失われます。 | false |
spring.ai.ollama.embedding.options.num-thread | 計算中に使用するスレッドの数を設定します。デフォルトでは、Ollama は最適なパフォーマンスを得るためにこれを検出します。この値を、(論理コア数ではなく) システムに搭載されている物理 CPU コア数に設定することをお勧めします。0 = ランタイムに決定させる | 0 |
spring.ai.ollama.embedding.options.num-keep | - | 4 |
spring.ai.ollama.embedding.options.seed | 生成に使用する乱数シードを設定します。これを特定の数値に設定すると、モデルは同じプロンプトに対して同じテキストを生成します。 | -1 |
spring.ai.ollama.embedding.options.num-predict | テキストを生成するときに予測するトークンの最大数。(-1 = 無限生成、-2 = コンテキストを埋める) | -1 |
spring.ai.ollama.embedding.options.top-k | ナンセンスが生成される確率を減らします。値が大きいほど (100 など)、より多様な回答が得られますが、値が小さいほど (10 など) より保守的になります。 | 40 |
spring.ai.ollama.embedding.options.top-p | top-k と連携します。値が大きいほど (0.95 など)、より多様なテキストが生成され、値が小さいほど (0.5 など)、より焦点が絞られた控えめなテキストが生成されます。 | 0.9 |
spring.ai.ollama.embedding.options.tfs-z | テールフリーサンプリングは、出力からの可能性の低いトークンの影響を軽減するために使用されます。値が大きいほど (2.0 など)、影響はさらに軽減されますが、値 1.0 はこの設定を無効にします。 | 1.0 |
spring.ai.ollama.embedding.options.typical-p | - | 1.0 |
spring.ai.ollama.embedding.options.repeat-last-n | 繰り返しを防ぐために、モデルがどこまで遡るかを設定します。(デフォルト: 64, 0 = 無効、-1 = num_ctx) | 64 |
spring.ai.ollama.embedding.options.temperature | モデルの温度。温度を上げると、モデルはより創造的に答えられるようになります。 | 0.8 |
spring.ai.ollama.embedding.options.repeat-penalty | 繰り返しをどの程度強くペナルティするかを設定します。値が大きいほど (1.5 など)、繰り返しに対するペナルティがより強くなり、値が小さいほど (0.9 など) ペナルティがより緩やかになります。 | 1.1 |
spring.ai.ollama.embedding.options.presence-penalty | - | 0.0 |
spring.ai.ollama.embedding.options.frequency-penalty | - | 0.0 |
spring.ai.ollama.embedding.options.mirostat | 複雑さを制御するために Mirostat サンプリングを有効にします。(default: 0, 0 = 無効、1 = ミロスタット、2 = ミロスタット 2.0) | 0 |
spring.ai.ollama.embedding.options.mirostat-tau | 出力の一貫性と多様性の間のバランスを制御します。値を低くすると、より焦点が絞られた一貫したテキストになります。 | 5.0 |
spring.ai.ollama.embedding.options.mirostat-eta | 生成されたテキストからのフィードバックにアルゴリズムがどれだけ早く応答するかに影響します。学習率が低いと調整が遅くなり、学習率が高いとアルゴリズムの応答性が高くなります。 | 0.1 |
spring.ai.ollama.embedding.options.penalize-newline | - | true |
spring.ai.ollama.embedding.options.stop | 使用する停止シーケンスを設定します。このパターンが発生すると、LLM はテキストの生成を停止して戻ります。モデルファイルで複数の個別の停止パラメーターを指定することにより、複数の停止パターンを設定できます。 | - |
spring.ai.ollama.embedding.options.functions | 単一のプロンプトリクエストで関数呼び出しを有効にするために、名前で識別される関数のリスト。これらの名前を持つ関数は、functionCallbacks レジストリに存在する必要があります。 | - |
spring.ai.ollama.embedding.options というプレフィックスが付いたすべてのプロパティは、リクエスト固有のランタイムオプションを EmbeddingRequest 呼び出しに追加することで実行時にオーバーライドできます。 |
ランタイムオプション
OllamaOptions.java [GitHub] (英語) は、使用するモデル、低レベルの GPU および CPU チューニングなどの Ollama 構成を提供します。
デフォルトのオプションは、spring.ai.ollama.embedding.options プロパティを使用して構成することもできます。
開始時に、OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaOptions defaultOptions) を使用して、すべての埋め込みリクエストに使用されるデフォルトのオプションを構成します。実行時に、OllamaOptions インスタンスを EmbeddingRequest の一部として使用して、デフォルトのオプションをオーバーライドできます。
たとえば、特定のリクエストのデフォルトのモデル名をオーバーライドするには、次のようにします。
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OllamaOptions.builder()
.model("Different-Embedding-Model-Deployment-Name"))
.truncates(false)
.build());自動プルモデル
Spring AI Ollama は、Ollama インスタンスでモデルが利用できない場合に自動的にモデルをプルできます。この機能は、開発とテスト、アプリケーションを新しい環境にデプロイする場合に特に便利です。
| また、何千ものフリー GGUF Hugging Face モデル (英語) のいずれかを名前でプルすることもできます。 |
モデルをプルするための戦略は 3 つあります。
always(PullModelStrategy.ALWAYSで定義): モデルがすでに利用可能であっても、常にモデルをプルします。モデルの最新バージョンを使用していることを確認できます。when_missing(PullModelStrategy.WHEN_MISSINGで定義): モデルがまだ利用できない場合にのみモデルをプルします。これにより、モデルの古いバージョンが使用される可能性があります。never(PullModelStrategy.NEVERで定義): モデルを自動的にプルしません。
| モデルのダウンロード中に遅延が発生する可能性があるため、本番環境では自動プルは推奨されません。代わりに、必要なモデルを事前に評価して事前ダウンロードすることを検討してください。 |
構成プロパティとデフォルトオプションで定義されたすべてのモデルは、起動時に自動的にプルできます。構成プロパティを使用して、プル戦略、タイムアウト、再試行の最大回数を構成できます。
spring:
ai:
ollama:
init:
pull-model-strategy: always
timeout: 60s
max-retries: 1| 指定されたすべてのモデルが Ollama で利用可能になるまで、アプリケーションは初期化を完了しません。モデルのサイズとインターネット接続速度によっては、アプリケーションの起動時間が大幅に遅くなる可能性があります。 |
起動時に追加のモデルを初期化できます。これは、実行時に動的に使用されるモデルに便利です。
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
additional-models:
- mxbai-embed-large
- nomic-embed-text特定の種類のモデルにのみプル戦略を適用する場合は、初期化タスクから埋め込みモデルを除外できます。
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
include: falseこの構成では、埋め込みモデルを除くすべてのモデルにプル戦略が適用されます。
HuggingFace モデル
Ollama は、すぐにすべての GGUF Hugging Face (英語) 埋め込みモデルにアクセスできます。これらのモデルのいずれかを名前でプルできます: ollama pull hf.co/<username>/<model-repository> または自動プル戦略を構成できます: 自動プルモデル :
spring.ai.ollama.embedding.options.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=alwaysspring.ai.ollama.embedding.options.model: 使用する Hugging Face GGUF モデル (英語) を指定します。spring.ai.ollama.init.pull-model-strategy=always: (オプション) 起動時に自動的にモデルを取得できるようにします。本番環境では、遅延を避けるためにモデルを事前にダウンロードする必要があります。:ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1.
サンプルコントローラー
これにより、クラスに注入できる EmbeddingModel 実装が作成されます。以下は、EmbeddingModel 実装を使用する単純な @Controller クラスの例です。
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}手動構成
Spring Boot を使用していない場合は、OllamaEmbeddingModel を手動で構成できます。そのためには、プロジェクトの Maven pom.xml または Gradle build.gradle ビルドファイルに spring-ai-ollama 依存関係を追加します。
Maven
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-ollama</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-ollama'
}| Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。 |
spring-ai-ollama 依存関係により、OllamaChatModel へのアクセスも提供されます。OllamaChatModel の詳細については、Ollama チャットクライアントセクションを参照してください。 |
次に、OllamaEmbeddingModel インスタンスを作成し、専用の chroma/all-minilm-l6-v2-f32 埋め込みモデルを使用して 2 つの入力テキストの埋め込みを計算します。
var ollamaApi = new OllamaApi();
var embeddingModel = new OllamaEmbeddingModel(this.ollamaApi,
OllamaOptions.builder()
.model(OllamaModel.MISTRAL.id())
.build());
EmbeddingResponse embeddingResponse = this.embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OllamaOptions.builder()
.model("chroma/all-minilm-l6-v2-f32"))
.truncate(false)
.build());OllamaOptions は、すべての埋め込みリクエストの構成情報を提供します。
