Text Embeddings API

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

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

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

モデル名 説明 出力の次元 シーケンスの最大長 サポートされているテキスト言語
gemini-embedding-001 英語、多言語、コードタスクで最先端のパフォーマンスを実現します。text-embedding-005text-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 を使用します。

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

リクエスト本文を 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

リクエスト本文を 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 は切り捨てられています。

このサンプルの 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)
  • 対応している言語: AfrikaansAlbanianAmharicArabicArmenianAzerbaijaniBasqueBelarusiasnBengaliBulgarianBurmeseCatalanCebuanoChichewaChineseCorsicanCzechDanishDutchEnglishEsperantoEstonianFilipinoFinnishFrenchGalicianGeorgianGermanGreekGujaratiHaitian CreoleHausaHawaiianHebrewHindiHmongHungarianIcelandicIgboIndonesianIrishItalianJapaneseJavaneseKannadaKazakhKhmerKoreanKurdishKyrgyzLaoLatinLatvianLithuanianLuxembourgishMacedonianMalagasyMalayMalayalamMalteseMaoriMarathiMongolianNepaliNorwegianPashtoPersianPolishPortuguesePunjabiRomanianRussianSamoanScottish GaelicSerbianShonaSindhiSinhalaSlovakSlovenianSomaliSothoSpanishSundaneseSwahiliSwedishTajikTamilTeluguThaiTurkishUkrainianUrduUzbekVietnameseWelshWest FrisianXhosaYiddishYorubaZulu

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

ArabicBengaliBulgarianChinese (Simplified and Traditional)CroatianCzechDanishDutchEnglishEstonianFinnishFrenchGermanGreekHebrewHindiHungarianIndonesianItalianJapaneseKoreanLatvianLithuanianNorwegianPolishPortugueseRomanianRussianSerbianSlovakSlovenianSpanishSwahiliSwedishThaiTurkishUkrainianVietnameseAfrikaansAmharicAssameseAzerbaijaniBelarusianBosnianCatalanCebuanoCorsicanWelshDhivehiEsperantoBasquePersianFilipino (Tagalog)FrisianIrishScots GaelicGalicianGujaratiHausaHawaiianHmongHaitian CreoleArmenianIgboIcelandicJavaneseGeorgianKazakhKhmerKannadaKrioKurdishKyrgyzLatinLuxembourgishLaoMalagasyMaoriMacedonianMalayalamMongolianMeiteilon (Manipuri)MarathiMalayMalteseMyanmar (Burmese)NepaliNyanja (Chichewa)Odia (Oriya)PunjabiPashtoSindhiSinhala (Sinhalese)SamoanShonaSomaliAlbanianSesothoSundaneseTamilTeluguTajikUyghurUrduUzbekXhosaYiddishYorubaZulu

モデル バージョン

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

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

次のステップ

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