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

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

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

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

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

始める前に

アカウントにログインします。 Google Cloud を初めて使用する場合は、アカウントを作成して、 Google Cloud実際のシナリオでプロダクトがどのように機能するかを評価します。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

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

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: genai.RoleUser,
		},
	}

	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
}

Node.js

インストール

npm install @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

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;

async function generateEmbeddingsForRetrieval(
  projectId = GOOGLE_CLOUD_PROJECT
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
  });

  const prompt = [
    "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",
  ];

  const response = await client.models.embedContent({
    model: 'gemini-embedding-001',
    contents: prompt,
    config: {
      taskType: 'RETRIEVAL_DOCUMENT', // Optional
      outputDimensionality: 3072, // Optional
      title: "Driver's License", // Optional
    },
  });

  console.log(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)

  return response;
}

Java

Java をインストールまたは更新します。

詳しくは、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 com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

public class EmbeddingsDocRetrievalWithTxt {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-embedding-001";
    embedContent(modelId);
  }

  // Shows how to embed content with text.
  public static EmbedContentResponse embedContent(String modelId) {
    // Client Initialization. Once created, it can be reused for multiple requests.
    try (Client client = Client.builder().location("global").vertexAI(true).build()) {

      EmbedContentResponse response =
          client.models.embedContent(
              modelId,
              List.of(
                  "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"),
              EmbedContentConfig.builder()
                  .taskType("RETRIEVAL_DOCUMENT")
                  .outputDimensionality(3072)
                  .title("Driver's License")
                  .build());

      System.out.println(response);
      // Example response:
      // embeddings=Optional[[ContentEmbedding{values=Optional[[-0.035855383, 0.008127963, ... ]]
      // statistics=Optional[ContentEmbeddingStatistics{truncated=Optional[false],
      // tokenCount=Optional[11.0]}]}]],
      // metadata=Optional[EmbedContentMetadata{billableCharacterCount=Optional[153]}]}
      return response;
    }
  }
}

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 を使用します。

オープンモデル

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

モデル名	説明	出力のサイズ	シーケンスの最大長	サポートされているテキスト言語
`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」をご覧ください。

テキスト エンベディングを取得する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

API の上限

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

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

Python

インストール

Go

Node.js

インストール

Java

REST

curl

PowerShell

レスポンス

curl コマンドの例

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

Google モデル

オープンモデル

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

次のステップ

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

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

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

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