Text Embeddings API

テキスト エンベディング API は、テキストデータを数値ベクトルに変換します。これらのベクトル表現は、対象となる単語の意味論的意味とコンテキストを取り込むように設計されています。

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

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

モデル名	説明	出力の次元	シーケンスの最大長	サポートされているテキスト言語
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 を使用します。

構文

curl

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

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

Python

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

import vertexai
from vertexai.language_models import TextEmbeddingModel

vertexai.init(project=PROJECT_ID, location=REGION)

model = TextEmbeddingModel.from_pretrained(MODEL_ID)
embeddings = model.get_embeddings(...)

パラメータ リスト

最上位のフィールド
instances	次のフィールドを含むオブジェクトのリスト。 content title（省略可） task_type（省略可）
parameters	次のフィールドを含むオブジェクト。 autoTruncate（省略可） outputDimensionality（省略可）

instance フィールド
content	string エンベディングを生成するテキスト。
task_type	省略可: string モデルがより優れたエンベディングを生成できるように、予定されているダウンストリームの用途を伝えるために使用されます。空白のままにすると、デフォルトの RETRIEVAL_QUERY が使用されます。 RETRIEVAL_QUERY RETRIEVAL_DOCUMENT SEMANTIC_SIMILARITY CLASSIFICATION CLUSTERING QUESTION_ANSWERING FACT_VERIFICATION CODE_RETRIEVAL_QUERY タスクタイプの詳細については、エンベディングのタスクタイプを選択するをご覧ください。
title	省略可: string モデルがより優れたエンベディングを生成できるようにするために使用されます。task_type=RETRIEVAL_DOCUMENT でのみ有効です。

task_type

次の表に、task_type パラメータ値とそのユースケースを示します。

task_type	説明
RETRIEVAL_QUERY	指定したテキストが検索または取得設定のクエリであることを指定します。ドキュメント側には RETRIEVAL_DOCUMENT を使用します。
RETRIEVAL_DOCUMENT	指定したテキストが検索または取得設定のドキュメントであることを指定します。
SEMANTIC_SIMILARITY	指定したテキストが意味的テキスト類似性（STS）で使用されることを指定します。
CLASSIFICATION	エンベディングが分類に使用されることを指定します。
CLUSTERING	エンベディングがクラスタリングに使用されることを指定します。
QUESTION_ANSWERING	クエリ エンベディングが質問への回答に使用されることを指定します。ドキュメント側には RETRIEVAL_DOCUMENT を使用します。
FACT_VERIFICATION	クエリ エンベディングが事実確認に使用されることを指定します。ドキュメント側には RETRIEVAL_DOCUMENT を使用します。
CODE_RETRIEVAL_QUERY	クエリ エンベディングが Java と Python のコード取得に使用されることを指定します。ドキュメント側には RETRIEVAL_DOCUMENT を使用します。

取得タスク:

クエリ: 入力テキストが検索クエリであることを示すには、task_type=RETRIEVAL_QUERY を使用します。コーパス: 入力テキストが検索対象のドキュメント コレクションの一部であることを示すには、task_type=RETRIEVAL_DOCUMENT を使用します。

類似タスク:

意味的類似性: 全体的な意味の類似性を評価するには、両方の入力テキストに task_type= SEMANTIC_SIMILARITY を使用します。

注: SEMANTIC_SIMILARITY では、ドキュメント検索や情報検索などの取得ユースケースを想定していません。このようなユースケースでは、RETRIEVAL_DOCUMENT、RETRIEVAL_QUERY、QUESTION_ANSWERING、FACT_VERIFICATION を使用します。

parameters フィールド
autoTruncate	省略可: bool true に設定すると、入力テキストが切り捨てられます。false に設定すると、入力テキストがモデルでサポートされている最大長を超えている場合、エラーが返されます。デフォルトは true です。
outputDimensionality	省略可: int 出力エンベディングのサイズを指定するために使用します。設定すると、指定されたサイズを超えた分の出力エンベディングが切り捨てられます。

リクエストの本文

{
  "instances": [
    {
      "task_type": "RETRIEVAL_DOCUMENT",
      "title": "document title",
      "content": "I would like embeddings for this text!"
    },
  ]
}

レスポンスの本文

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": boolean,
          "token_count": integer
        },
        "values": [ number ]
      }
    }
  ]
}

レスポンスの要素
predictions	次のフィールドを含むオブジェクトのリスト。 embeddings: 入力テキストから生成された結果。次のフィールドを含めます。 values statistics

embeddings フィールド
values	float のリスト。values フィールドには、指定された入力テキストに含まれるセマンティック コンテンツの数値エンコード（エンベディング ベクトル）が含まれます。
statistics	入力テキストから計算された統計値。以下が含まれます: truncated: 入力テキストがモデルで許可されているトークンの最大数を超えたために切り捨てられたかどうかを示します。 token_count: 入力テキストのトークンの数。

レスポンスの例

{
  "predictions": [
    {
      "embeddings": {
        "values": [
          0.0058424929156899452,
          0.011848051100969315,
          0.032247550785541534,
          -0.031829461455345154,
          -0.055369812995195389,
          ...
        ],
        "statistics": {
          "token_count": 4,
          "truncated": false
        }
      }
    }
  ]
}

例

テキスト文字列を埋め込む

次の例は、テキスト文字列のエンベディングを取得する方法を示しています。

REST

環境をセットアップしたら、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": [ ... ]
      }
    }
  ]
}

このサンプルの URL にある次の点に注意してください。

• generateContent メソッドを使用して、レスポンスが完全に生成された後に返されるようにリクエストします。ユーザーが認識するレイテンシを短縮するには、streamGenerateContent メソッドを使用して、生成時にレスポンスをストリーミングします。
• マルチモーダル モデル ID は、URL の末尾のメソッドの前に配置されます（例: gemini-2.0-flash）。このサンプルでは、他のモデルもサポートされている場合があります。

Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。

from __future__ import annotations

from vertexai.language_models import TextEmbeddingInput, TextEmbeddingModel


def embed_text() -> list[list[float]]:
    """Embeds texts with a pre-trained, foundational model.

    Returns:
        A list of lists containing the embedding vectors for each input text
    """

    # A list of texts to be embedded.
    texts = ["banana muffins? ", "banana bread? banana muffins?"]
    # The dimensionality of the output embeddings.
    dimensionality = 3072
    # The task type for embedding. Check the available tasks in the model's documentation.
    task = "RETRIEVAL_DOCUMENT"

    model = TextEmbeddingModel.from_pretrained("gemini-embedding-001")
    kwargs = dict(output_dimensionality=dimensionality) if dimensionality else {}

    embeddings = []
    # gemini-embedding-001 takes one input at a time
    for text in texts:
        text_input = TextEmbeddingInput(text, task)
        embedding = model.get_embeddings([text_input], **kwargs)
        print(embedding)
        # Example response:
        # [[0.006135190837085247, -0.01462465338408947, 0.004978656303137541, ...]]
        embeddings.append(embedding[0].values)

    return embeddings

Go

このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Go の設定手順を完了してください。詳細については、Vertex AI Go API のリファレンス ドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

import (
	"context"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1"
	"cloud.google.com/go/aiplatform/apiv1/aiplatformpb"

	"google.golang.org/api/option"
	"google.golang.org/protobuf/types/known/structpb"
)

// embedTexts shows how embeddings are set for gemini-embedding-001 model
func embedTexts(w io.Writer, project, location string) error {
	// location := "us-central1"
	ctx := context.Background()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	dimensionality := 3072
	model := "gemini-embedding-001"
	texts := []string{"banana muffins? ", "banana bread? banana muffins?"}

	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return err
	}
	defer client.Close()

	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)
	allEmbeddings := make([][]float32, 0, len(texts))
	// gemini-embedding-001 takes 1 input at a time
	for _, text := range texts {
		instances := make([]*structpb.Value, 1)
		instances[0] = structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"content":   structpb.NewStringValue(text),
				"task_type": structpb.NewStringValue("QUESTION_ANSWERING"),
			},
		})

		params := structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"outputDimensionality": structpb.NewNumberValue(float64(dimensionality)),
			},
		})

		req := &aiplatformpb.PredictRequest{
			Endpoint:   endpoint,
			Instances:  instances,
			Parameters: params,
		}
		resp, err := client.Predict(ctx, req)
		if err != nil {
			return err
		}

		// Process the prediction for the single text
		// The response will contain one prediction because we sent one instance.
		if len(resp.Predictions) == 0 {
			return fmt.Errorf("no predictions returned for text \"%s\"", text)
		}

		prediction := resp.Predictions[0]
		embeddingValues := prediction.GetStructValue().Fields["embeddings"].GetStructValue().Fields["values"].GetListValue().Values

		currentEmbedding := make([]float32, len(embeddingValues))
		for j, value := range embeddingValues {
			currentEmbedding[j] = float32(value.GetNumberValue())
		}
		allEmbeddings = append(allEmbeddings, currentEmbedding)
	}

	if len(allEmbeddings) > 0 {
		fmt.Fprintf(w, "Dimensionality: %d. Embeddings length: %d", len(allEmbeddings[0]), len(allEmbeddings))
	} else {
		fmt.Fprintln(w, "No texts were processed.")
	}
	return nil
}

Java

このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

import static java.util.stream.Collectors.toList;

import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.OptionalInt;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class PredictTextEmbeddingsSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Details about text embedding request structure and supported models are available in:
    // https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    String project = "YOUR_PROJECT_ID";
    String model = "gemini-embedding-001";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "QUESTION_ANSWERING",
        OptionalInt.of(3072));
  }

  // Gets text embeddings from a pretrained, foundational model.
  public static List<List<Float>> predictTextEmbeddings(
      String endpoint,
      String project,
      String model,
      List<String> texts,
      String task,
      OptionalInt outputDimensionality)
      throws IOException {
    PredictionServiceSettings settings =
        PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build();
    Matcher matcher = Pattern.compile("^(?<Location>\\w+-\\w+)").matcher(endpoint);
    String location = matcher.matches() ? matcher.group("Location") : "us-central1";
    EndpointName endpointName =
        EndpointName.ofProjectLocationPublisherModelName(project, location, "google", model);

    List<List<Float>> floats = new ArrayList<>();
    // You can use this prediction service client for multiple requests.
    try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
      // gemini-embedding-001 takes one input at a time.
      for (int i = 0; i < texts.size(); i++) {
        PredictRequest.Builder request = 
            PredictRequest.newBuilder().setEndpoint(endpointName.toString());
        if (outputDimensionality.isPresent()) {
          request.setParameters(
              Value.newBuilder()
                  .setStructValue(
                      Struct.newBuilder()
                          .putFields(
                              "outputDimensionality", valueOf(outputDimensionality.getAsInt()))
                          .build()));
        }
        request.addInstances(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("content", valueOf(texts.get(i)))
                        .putFields("task_type", valueOf(task))
                        .build()));
        PredictResponse response = client.predict(request.build());

        for (Value prediction : response.getPredictionsList()) {
          Value embeddings = prediction.getStructValue().getFieldsOrThrow("embeddings");
          Value values = embeddings.getStructValue().getFieldsOrThrow("values");
          floats.add(
              values.getListValue().getValuesList().stream()
                  .map(Value::getNumberValue)
                  .map(Double::floatValue)
                  .collect(toList()));
        }
      }
      return floats;
    }
  }

  private static Value valueOf(String s) {
    return Value.newBuilder().setStringValue(s).build();
  }

  private static Value valueOf(int n) {
    return Value.newBuilder().setNumberValue(n).build();
  }
}

Node.js

このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンス ドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

async function main(
  project,
  model = 'gemini-embedding-001',
  texts = 'banana bread?;banana muffins?',
  task = 'QUESTION_ANSWERING',
  dimensionality = 0,
  apiEndpoint = 'us-central1-aiplatform.googleapis.com'
) {
  const aiplatform = require('@google-cloud/aiplatform');
  const {PredictionServiceClient} = aiplatform.v1;
  const {helpers} = aiplatform; // helps construct protobuf.Value objects.
  const clientOptions = {apiEndpoint: apiEndpoint};
  const location = 'us-central1';
  const endpoint = `projects/${project}/locations/${location}/publishers/google/models/${model}`;

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, task_type: task}));

    const client = new PredictionServiceClient(clientOptions);
    const parameters = helpers.toValue(
      dimensionality > 0 ? {outputDimensionality: parseInt(dimensionality)} : {}
    );
    const allEmbeddings = []
    // gemini-embedding-001 takes one input at a time.
    for (const instance of instances) {
      const request = {endpoint, instances: [instance], parameters};
      const [response] = await client.predict(request);
      const predictions = response.predictions;

      const embeddings = predictions.map(p => {
        const embeddingsProto = p.structValue.fields.embeddings;
        const valuesProto = embeddingsProto.structValue.fields.values;
        return valuesProto.listValue.values.map(v => v.numberValue);
      });

      allEmbeddings.push(embeddings[0])
    }


    console.log('Got embeddings: \n' + JSON.stringify(allEmbeddings));
  }

  callPredict();
}

サポートされているテキスト言語

すべてのテキスト エンベディング モデルは英語テキストをサポートし、同テキストで評価されています。text-multilingual-embedding-002 モデルは、さらに次の言語をサポートし、それらの言語で評価されています。

• 評価対象の言語: Arabic (ar)、Bengali (bn)、English (en)、Spanish (es)、German (de)、Persian (fa)、Finnish (fi)、French (fr)、Hindi (hi)、Indonesian (id)、Japanese (ja)、Korean (ko)、Russian (ru)、Swahili (sw)、Telugu (te)、Thai (th)、Yoruba (yo)、Chinese (zh)
• 対応している言語: Afrikaans、Albanian、Amharic、Arabic、Armenian、Azerbaijani、Basque、Belarusiasn、Bengali、Bulgarian、Burmese、Catalan、Cebuano、Chichewa、Chinese、Corsican、Czech、Danish、Dutch、English、Esperanto、Estonian、Filipino、Finnish、French、Galician、Georgian、German、Greek、Gujarati、Haitian Creole、Hausa、Hawaiian、Hebrew、Hindi、Hmong、Hungarian、Icelandic、Igbo、Indonesian、Irish、Italian、Japanese、Javanese、Kannada、Kazakh、Khmer、Korean、Kurdish、Kyrgyz、Lao、Latin、Latvian、Lithuanian、Luxembourgish、Macedonian、Malagasy、Malay、Malayalam、Maltese、Maori、Marathi、Mongolian、Nepali、Norwegian、Pashto、Persian、Polish、Portuguese、Punjabi、Romanian、Russian、Samoan、Scottish Gaelic、Serbian、Shona、Sindhi、Sinhala、Slovak、Slovenian、Somali、Sotho、Spanish、Sundanese、Swahili、Swedish、Tajik、Tamil、Telugu、Thai、Turkish、Ukrainian、Urdu、Uzbek、Vietnamese、Welsh、West Frisian、Xhosa、Yiddish、Yoruba、Zulu。

gemini-embedding-001 モデルは次の言語をサポートしています。

Arabic、Bengali、Bulgarian、Chinese (Simplified and Traditional)、Croatian、Czech、Danish、Dutch、English、Estonian、Finnish、French、German、Greek、Hebrew、Hindi、Hungarian、Indonesian、Italian、Japanese、Korean、Latvian、Lithuanian、Norwegian、Polish、Portuguese、Romanian、Russian、Serbian、Slovak、Slovenian、Spanish、Swahili、Swedish、Thai、Turkish、Ukrainian、Vietnamese、Afrikaans、Amharic、Assamese、Azerbaijani、Belarusian、Bosnian、Catalan、Cebuano、Corsican、Welsh、Dhivehi、Esperanto、Basque、Persian、Filipino (Tagalog)、Frisian、Irish、Scots Gaelic、Galician、Gujarati、Hausa、Hawaiian、Hmong、Haitian Creole、Armenian、Igbo、Icelandic、Javanese、Georgian、Kazakh、Khmer、Kannada、Krio、Kurdish、Kyrgyz、Latin、Luxembourgish、Lao、Malagasy、Maori、Macedonian、Malayalam、Mongolian、Meiteilon (Manipuri)、Marathi、Malay、Maltese、Myanmar (Burmese)、Nepali、Nyanja (Chichewa)、Odia (Oriya)、Punjabi、Pashto、Sindhi、Sinhala (Sinhalese)、Samoan、Shona、Somali、Albanian、Sesotho、Sundanese、Tamil、Telugu、Tajik、Uyghur、Urdu、Uzbek、Xhosa、Yiddish、Yoruba、Zulu。

モデル バージョン

現在の安定版モデルを使用するには、モデルのバージョン番号（gemini-embedding-001 など）を指定します。バージョン番号のないモデルを指定することはおすすめしません。これは、別のモデルへの以前のポインタにすぎず、安定していないためです。

詳細については、モデルのバージョンとライフサイクルをご覧ください。

次のステップ

詳細なドキュメントについては、以下をご覧ください。

• テキスト エンベディング