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

Google GenAI テキスト埋め込み

Google ジェネラル AI Embeddings API (英語) は、Gemini 開発者 API または Vertex AI を介して、Google の埋め込みモデルを用いたテキスト埋め込み生成機能を提供します。このドキュメントでは、Google GenAI テキスト埋め込み API を用いてテキスト埋め込みを作成する方法について説明します。

Google GenAI テキスト埋め込み API は、密ベクトル表現を使用します。単語を数値に直接マッピングする傾向があるスパースベクトルとは異なり、密ベクトルはテキストの意味をより適切に表現するように設計されています。生成 AI で密ベクトル埋め込みを使用する利点は、単語や構文の直接的な一致を検索する代わりに、たとえ同じ言語を使用していなくても、クエリの意味に一致する文章をより適切に検索できることです。

現在、Google GenAI SDK はテキスト埋め込みのみをサポートしています。マルチモーダル埋め込みのサポートは保留中で、SDK で利用可能になった時点で追加される予定です。

この実装では、次の 2 つの認証モードが提供されます。

  • Gemini 開発者 API : API キーを使用して素早いプロトタイピングと開発を行う

  • Vertex AI : エンタープライズ機能を備えた本番環境の デプロイには Google クラウド認証情報を使用します

前提条件

次のいずれかの認証方法を選択します。

オプション 1: Gemini 開発者 API (API キー)

  • Google AI スタジオ (英語) から API キーを取得する

  • API キーを環境変数またはアプリケーションのプロパティとして設定します

オプション 2: Vertex AI (Google クラウド)

  • OS に適した gcloud CLI をインストールします。

  • 次のコマンドを実行して認証します。PROJECT_ID を Google Cloud プロジェクト ID に置き換え、ACCOUNT を Google Cloud ユーザー名に置き換えます。

gcloud config set project <PROJECT_ID> &&
gcloud auth application-default login <ACCOUNT>

リポジトリと BOM の追加

Spring AI アーティファクトは、Maven Central リポジトリと Spring スナップショットリポジトリに公開されています。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリセクションを参照してください。

依存関係の管理を支援するために、Spring AI は BOM (部品表) を提供し、一貫したバージョンの Spring AI がプロジェクト全体で使用されるようにします。Spring AI BOM をビルドシステムに追加するには、"依存関係管理" セクションを参照してください。

自動構成

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

Spring AI は、Google GenAI 埋め込みモデル用の Spring Boot 自動構成を提供します。これを有効にするには、プロジェクトの Maven pom.xml ファイルに次の依存関係を追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai-embedding</artifactId>
</dependency>

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai-embedding'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。

埋め込みプロパティ

接続プロパティ

プレフィックス spring.ai.google.genai.embedding は、Google GenAI Embedding API に接続できるようにするプロパティプレフィックスとして使用されます。

接続プロパティは Google GenAI チャットモジュールと共有されます。チャットと埋め込みの両方を使用する場合は、spring.ai.google.genai プレフィックス（チャット用）または spring.ai.google.genai.embedding プレフィックス（埋め込み用）のいずれかを使用して接続を一度設定するだけで済みます。

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

spring.ai.google.genai.embedding.api-key

Gemini 開発者 API の API キー。指定すると、クライアントは Vertex AI ではなく Gemini 開発者 API を使用します。

-

spring.ai.google.genai.embedding.project-id

Google クラウドプラットフォームプロジェクト ID (Vertex AI モードに必要)

-

spring.ai.google.genai.embedding.location

Google クラウド領域 (Vertex AI モードに必要)

-

spring.ai.google.genai.embedding.credentials-uri

Google クラウド認証情報への URI。指定すると、認証用の GoogleCredentials インスタンスの作成に使用されます。

-

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

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

無効にするには、spring.ai.model.embedding.text=none (または google-genai と一致しない値)

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

テキスト埋め込みプロパティ

プレフィックス spring.ai.google.genai.embedding.text は、Google GenAI テキスト埋め込みの埋め込みモデルの実装を構成できるプロパティプレフィックスです。

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

spring.ai.model.embedding.text

Google GenAI Embedding API モデルを有効にします。

google-genai

spring.ai.google.genai.embedding.text.options.model

使用する Google GenAI テキスト埋め込みモデル (英語) 。対応モデルは text-embedding-004 と text-multilingual-embedding-002 です

text-embedding-004

spring.ai.google.genai.embedding.text.options.task-type

モデルがより高品質な埋め込みを生成するのを支援するための下流アプリケーションです。利用可能なタスク型 (英語) : RETRIEVAL_QUERY、RETRIEVAL_DOCUMENT、SEMANTIC_SIMILARITY、CLASSIFICATION、CLUSTERING、QUESTION_ANSWERING、FACT_VERIFICATION

RETRIEVAL_DOCUMENT

spring.ai.google.genai.embedding.text.options.title

オプションのタイトル。task_type=RETRIEVAL_DOCUMENT の場合にのみ有効です。

-

spring.ai.google.genai.embedding.text.options.dimensions

結果として得られる出力埋め込みの次元数。モデルバージョン 004 以降でサポートされます。このパラメーターを使用すると、たとえばストレージの最適化のために埋め込みサイズを縮小できます。

-

spring.ai.google.genai.embedding.text.options.auto-truncate

true に設定すると、入力テキストは切り捨てられます。false に設定すると、入力テキストがモデルでサポートされている最大長よりも長い場合にエラーが返されます。

true

サンプルコントローラー

新しい Spring Boot プロジェクトを作成し、spring-ai-starter-model-google-genai-embedding を pom (または gradle) の依存関係に追加します。

src/main/resources ディレクトリに application.properties ファイルを追加して、Google GenAI 埋め込みモデルを有効にして構成します。

Gemini 開発者 API の使用 (API キー)

spring.ai.google.genai.embedding.api-key=YOUR_API_KEY
spring.ai.google.genai.embedding.text.options.model=text-embedding-004

Vertex AI の使用 

spring.ai.google.genai.embedding.project-id=YOUR_PROJECT_ID
spring.ai.google.genai.embedding.location=YOUR_PROJECT_LOCATION
spring.ai.google.genai.embedding.text.options.model=text-embedding-004

これにより、クラスに挿入できる GoogleGenAiTextEmbeddingModel 実装が作成されます。以下は、埋め込み生成に埋め込みモデルを使用する単純な @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);
    }
}

手動構成

GoogleGenAiTextEmbeddingModel [GitHub] (英語) は EmbeddingModel を実装します。

spring-ai-google-genai-embedding 依存関係をプロジェクトの Maven pom.xml ファイルに追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-google-genai-embedding</artifactId>
</dependency>

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-google-genai-embedding'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。

次に、GoogleGenAiTextEmbeddingModel を作成し、テキスト埋め込みに使用します。

API キーの使用 

GoogleGenAiEmbeddingConnectionDetails connectionDetails =
    GoogleGenAiEmbeddingConnectionDetails.builder()
        .apiKey(System.getenv("GOOGLE_API_KEY"))
        .build();

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .build();

var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails, options);

EmbeddingResponse embeddingResponse = embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

Vertex AI の使用 

GoogleGenAiEmbeddingConnectionDetails connectionDetails =
    GoogleGenAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv("GOOGLE_CLOUD_PROJECT"))
        .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
        .build();

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .build();

var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails, options);

EmbeddingResponse embeddingResponse = embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

タスクの種類

Google GenAI 埋め込み API は、特定のユースケースに合わせて埋め込みを最適化するために、さまざまなタスク型をサポートしています。

  • RETRIEVAL_QUERY: 検索システムの検索クエリに最適化

  • RETRIEVAL_DOCUMENT: 検索システム内のドキュメントに最適化

  • SEMANTIC_SIMILARITY: テキスト間の意味的類似性を測定するために最適化されています

  • CLASSIFICATION: テキスト分類タスクに最適化

  • CLUSTERING: 類似テキストのクラスタリングに最適化

  • QUESTION_ANSWERING: 質問応答システムに最適化

  • FACT_VERIFICATION: 事実検証タスクに最適化

さまざまなタスク型の使用例:

// For indexing documents
GoogleGenAiTextEmbeddingOptions docOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .title("Product Documentation")  // Optional title for documents
    .build();

// For search queries
GoogleGenAiTextEmbeddingOptions queryOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_QUERY)
    .build();

次元削減

モデルバージョン 004 以降では、ストレージの最適化のために埋め込み次元を削減できます。

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .dimensions(256)  // Reduce from default 768 to 256 dimensions
    .build();

Vertex AI テキスト埋め込みからの移行

現在、Vertex AI テキスト埋め込み実装 (spring-ai-vertex-ai-embedding) を使用している場合は、最小限の変更で Google GenAI に移行できます。

主な違い

  1. SDK : Google GenAI は Vertex AI SDK の代わりに新しい com.google.genai.Client を使用します

  2. 認証 : API キーと Google クラウド認証情報の両方をサポート

  3. パッケージ名 : クラスは org.springframework.ai.vertexai.embedding ではなく org.springframework.ai.google.genai.text にあります

  4. プロパティ接頭辞 : spring.ai.vertex.ai.embedding の代わりに spring.ai.google.genai.embedding を使用する

  5. 接続詳細 : VertexAiEmbeddingConnectionDetails の代わりに GoogleGenAiEmbeddingConnectionDetails を使用する

Google GenAI と Vertex AI テキスト埋め込みの使い分け

Google GenAI 埋め込みを使用する場合 : - API キーを使って素早くプロトタイピングしたい - 開発者 API の最新の埋め込み機能が必要 - API キーと Vertex AI モードを柔軟に切り替えたい - チャットに Google GenAI をすでに使用している場合

Vertex AI テキスト埋め込みを使用するの: - 既存の Vertex AI インフラストラクチャがある - マルチモーダル埋め込みが必要（現在は Vertex AI でのみ利用可能） - 組織で Google クラウドのみのデプロイが必要