テキスト エンベディングを取得する

このドキュメントでは、Vertex AI の Text embeddings API を使用してテキスト エンベディングを作成する方法について説明します。

Vertex AI Text Embeddings API は、密なベクトル表現を使用します。たとえば、gemini-embedding-001 は 3,072 次元のベクトルを使用します。密なベクトル エンベディング モデルは、大規模言語モデルで使用されるものと同様のディープ ラーニング手法を使用します。単語を直接数値にマッピングする傾向があるスパース ベクトルとは異なり、密なベクトルは、テキストの意味をより適切に表現するように設計されています。生成 AI で密なベクトル エンベディングを使用するメリットは、単語や構文が一致する箇所を直接検索するのではなく、同じ言語を使用していなくても、クエリの意味に一致する文章をより適切に検索できることです。

ベクトルは正規化されているため、コサイン類似度、ドット積、ユークリッド距離を使用して同じ類似性ランキングを提供できます。

• エンベディングの詳細については、エンベディング API の概要をご覧ください。
• テキスト エンベディング モデルの詳細については、テキスト エンベディングをご覧ください。
• 各エンベディング モデルでサポートされている言語については、サポートされているテキスト言語をご覧ください。

テキスト エンベディングを取得する例を確認するには、次のいずれかの環境で「テキスト エンベディングと Vertex AI ベクトル検索を使ってみる」ノートブックを実行します。

Colab で開く | Colab Enterprise で開く | Vertex AI Workbench で開く | GitHub で表示する

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. エンベディング ジョブのタスクタイプを選択します。

API の上限

入力テキストは、1 つのリクエストにつき 250 個までに制限されています。API の最大入力トークンの上限は 20,000 です。この上限を超える入力は、400 エラーになります。個々の入力テキストはさらに 2,048 トークンに制限されており、超過分は通知なく切り捨てられます。autoTruncate を false に設定して、暗黙的な切り捨てを無効にすることもできます。

詳細については、テキスト エンベディングの上限をご覧ください。

テキストのスニペットに対するテキスト エンベディングを取得する

テキストのスニペットのテキスト エンベディングを取得するには、Vertex AI API または Vertex AI SDK for Python を使用します。

エンベディング ディメンションを選択する

どのモデルも、デフォルトで最大長のエンベディング ベクトルを生成します。gemini-embedding-001 の場合、このベクトルは 3,072 次元を持ち、他のモデルは 768 次元のベクトルを生成します。ただし、output_dimensionality パラメータを使用すると、出力エンベディング ベクトルのサイズを制御できます。出力の次元数を小さくすると、ストレージ スペースを節約し、ダウンストリーム アプリケーションの計算効率を高めることができます。品質の低下はわずかです。

次の例では、gemini-embedding-001 モデルを使用します。

Python

インストール

pip install --upgrade google-genai

詳しくは、SDK リファレンス ドキュメントをご覧ください。

Vertex AI で Gen AI SDK を使用するための環境変数を設定します。

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import EmbedContentConfig

client = genai.Client()
response = client.models.embed_content(
    model="gemini-embedding-001",
    contents=[
        "How do I get a driver's license/learner's permit?",
        "How long is my driver's license valid for?",
        "Driver's knowledge test study guide",
    ],
    config=EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",  # Optional
        output_dimensionality=3072,  # Optional
        title="Driver's License",  # Optional
    ),
)
print(response)
# Example response:
# embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
# statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
# metadata=EmbedContentMetadata(billable_character_count=112)

Go

Go をインストールまたは更新する方法について学びます。

詳しくは、SDK リファレンス ドキュメントをご覧ください。

Vertex AI で Gen AI SDK を使用するための環境変数を設定します。

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/genai"
)

// generateEmbedContentWithText shows how to embed content with text.
func generateEmbedContentWithText(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	outputDimensionality := int32(3072)
	config := &genai.EmbedContentConfig{
		TaskType:             "RETRIEVAL_DOCUMENT",  //optional
		Title:                "Driver's License",    //optional
		OutputDimensionality: &outputDimensionality, //optional
	}

	contents := []*genai.Content{
		{
			Parts: []*genai.Part{
				{
					Text: "How do I get a driver's license/learner's permit?",
				},
				{
					Text: "How long is my driver's license valid for?",
				},
				{
					Text: "Driver's knowledge test study guide",
				},
			},
			Role: "user",
		},
	}

	modelName := "gemini-embedding-001"
	resp, err := client.Models.EmbedContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	fmt.Fprintln(w, resp)

	// Example response:
	// embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
	// statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
	// metadata=EmbedContentMetadata(billable_character_count=112)

	return nil
}

REST

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: 実際のプロジェクト ID。
• TEXT: エンベディングを生成するテキスト。上限: textembedding-gecko@001 を除くすべてのモデルで、5 テキスト（1 テキストあたり最大 2,048 トークン）。textembedding-gecko@001 の最大入力トークン長は 3,072 です。gemini-embedding-001 の場合、各リクエストに含めることができる入力テキストは 1 つだけです。詳細については、テキスト エンベディングの上限をご覧ください。
• AUTO_TRUNCATE: false に設定した場合、テキストがトークンの上限を超えると、リクエストが失敗します。デフォルト値は true です。

HTTP メソッドと URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict

リクエストの本文（JSON）:

{
  "instances": [
    { "content": "TEXT"}
  ],
  "parameters": { 
    "autoTruncate": AUTO_TRUNCATE 
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。容量を節約するために、values は切り捨てられています。

レスポンス

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": false,
          "token_count": 6
        },
        "values": [ ... ]
      }
    }
  ]
}

curl コマンドの例

MODEL_ID="gemini-embedding-001"
PROJECT_ID=PROJECT_ID

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/${MODEL_ID}:predict -d \
$'{
  "instances": [
    { "content": "What is life?"}
  ],
}'

サポートされているモデル

次の表に、利用可能な Google テキスト エンベディング モデルとオープン テキスト エンベディング モデルを示します。

Google モデル

テキスト エンベディングは、次のモデルを使用して取得できます。

モデル名	説明	出力の次元	シーケンスの最大長	サポートされているテキスト言語
gemini-embedding-001	英語、多言語、コードタスクで最先端のパフォーマンスを実現します。text-embedding-005 や text-multilingual-embedding-002 などの以前の専門モデルを統合し、それぞれのドメインでより優れたパフォーマンスを実現します。詳しくは、技術レポートをご覧ください。	最大 3,072	2,048 トークン	サポートされているテキスト言語
text-embedding-005	英語とコードのタスクに特化しています。	最大 768	2,048 トークン	英語
text-multilingual-embedding-002	多言語タスクに特化しています。	最大 768	2,048 トークン	サポートされているテキスト言語

エンベディングの品質を高めるには、最高レベルのパフォーマンスを提供するように設計された大規模モデルの gemini-embedding-001 を使用します。

注: サポートされているモデルの表に記載されているモデルのみを使用してください。@version サフィックスまたは @latest のないモデルを指定しないでください。これらのモデル名は無効と見なされます。

オープンモデル

テキスト エンベディングは、次のモデルを使用して取得できます。

モデル名	説明	出力のディメンション	シーケンスの最大長	サポートされているテキスト言語
multilingual-e5-small	E5 ファミリーのテキスト エンベディング モデルの一部。Small バリアントには 12 個のレイヤが含まれています。	最大 384	512 トークン	サポートされている言語
multilingual-e5-large	E5 ファミリーのテキスト エンベディング モデルの一部。Large バリアントには 24 レイヤが含まれています。	最大 1,024	512 トークン	サポートされている言語

開始するには、E5 ファミリーのモデルカードをご覧ください。オープンモデルの詳細については、MaaS 用オープンモデルをご覧ください。

ベクトル データベースにエンベディングを追加する

エンベディングを生成すると、Vector Search のようなベクトル データベースにエンベディングを追加できます。これにより低レイテンシでの検索が可能になり、データサイズが大きくなるほどそれが重要になります。

ベクトル検索の詳細については、ベクトル検索の概要をご覧ください。

次のステップ

• レート制限の詳細を確認する。Vertex AI の生成 AI のレート制限をご覧ください。
• エンベディングのバッチ予測を取得する。バッチ テキスト エンベディング予測を取得するをご覧ください。
  • マルチモーダル エンベディングの詳細を確認する。マルチモーダル エンベディングを取得するをご覧ください。
• エンベディングをチューニングする。テキスト エンベディングをチューニングするをご覧ください。
• text-embedding-005 と text-multilingual-embedding-002 の背後にある研究の詳細を確認する。研究論文「Gecko: Versatile Text Embeddings Distilled from Large Language Models」をご覧ください。