Embeddings

エンベディングは、テキスト入力の数値表現であり、クラスタリング、類似性測定、情報検索など、多くの独自のユースケースを実現します。概要については、エンベディング ガイドをご覧ください。

新しいコンテンツを作成する生成 AI モデルとは異なり、Gemini エンベディング モデルは、入力データの形式を数値表現に変換することのみを目的としています。Google は、入力データの形式をリクエストされた数値形式に変換するエンベディング モデルを提供する責任を負いますが、ユーザーは入力したデータと結果のエンベディングに対して全責任を負います。Gemini エンベディング モデルを使用することにより、アップロードするコンテンツに対して必要な権利を有することを確認したと見なされます。他者の知的財産やプライバシーの権利を侵害するコンテンツを生成することはできません。このサービスのご利用には、Google の使用禁止に関するポリシー利用規約が適用されます。

メソッド: models.embedContent

指定された Gemini エンベディング モデルを使用して、入力 Content からテキスト エンベディング ベクトルを生成します。

エンドポイント

投稿 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent

パスパラメータ

model string

必須。モデルのリソース名。これは、使用するモデルの ID として機能します。

この名前は、models.list メソッドから返されるモデル名と一致する必要があります。

形式: models/{model} 形式は models/{model} です。

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

フィールド
content object (Content)

必須。埋め込むコンテンツ。parts.text フィールドのみがカウントされます。

taskType enum (TaskType)

省略可。エンベディングが使用されるオプションのタスクタイプ。以前のモデル(models/embedding-001)ではサポートされていません。

title string

省略可。テキストのタイトル(省略可)。TaskType が RETRIEVAL_DOCUMENT の場合にのみ適用されます。

注: RETRIEVAL_DOCUMENTtitle を指定すると、検索用のエンベディングの品質が向上します。

outputDimensionality integer

省略可。出力エンベディングのオプションの削減ディメンション。設定すると、出力エンベディングの過剰な値が末尾から切り捨てられます。2024 年以降の新しいモデルでのみサポートされます。以前のモデル(models/embedding-001)を使用している場合は、この値を設定できません。

リクエスト例

Python

from google import genai
from google.genai import types

client = genai.Client()
text = "Hello World!"
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=text,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const text = "Hello World!";
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

text := "Hello World!"
outputDim := int32(10)
contents := []*genai.Content{
	genai.NewContentFromText(text, genai.RoleUser),
}
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", 
	contents, &genai.EmbedContentConfig{
		OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

Shell

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": {
     "parts":[{
     "text": "What is the meaning of life?"}]}
    }'

レスポンスの本文

成功した場合、レスポンスの本文には EmbedContentResponse のインスタンスが含まれます。

メソッド: models.batchEmbedContents

EmbedContentRequest オブジェクトとして表される文字列のバッチで構成される入力 Content から複数のエンベディング ベクトルを生成します。

エンドポイント

投稿 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

パスパラメータ

model string

必須。モデルのリソース名。これは、使用するモデルの ID として機能します。

この名前は、models.list メソッドから返されるモデル名と一致する必要があります。

形式: models/{model} 形式は models/{model} です。

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

フィールド
requests[] object (EmbedContentRequest)

必須。バッチのエンベディング リクエスト。これらの各リクエストのモデルは、指定されたモデル BatchEmbedContentsRequest.model と一致する必要があります。

リクエスト例

Python

from google import genai
from google.genai import types

client = genai.Client()
texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const texts = [
  "What is the meaning of life?",
  "How much wood would a woodchuck chuck?",
  "How does the brain work?",
];
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: texts,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

contents := []*genai.Content{
	genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
	genai.NewContentFromText("How much wood would a woodchuck chuck?", genai.RoleUser),
	genai.NewContentFromText("How does the brain work?", genai.RoleUser),
}

outputDim := int32(10)
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", contents, &genai.EmbedContentConfig{
	OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

Shell

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values

レスポンスの本文

BatchEmbedContentsRequest に対するレスポンス。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

フィールド
embeddings[] object (ContentEmbedding)

出力専用。各リクエストのエンベディング(バッチ リクエストで指定された順序と同じ)。

JSON 表現
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

メソッド: models.asyncBatchEmbedContent

バッチ処理用に models.embedContent 件のリクエストのバッチをキューに追加します。GenerativeServicemodels.batchEmbedContents ハンドラがありますが、同期されていました。混乱を避けるため、この名前を Async にします。

エンドポイント

投稿 https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:asyncBatchEmbedContent

パスパラメータ

batch.model string

必須。補完の生成に使用する Model の名前。

形式: models/{model}。形式は models/{model} です。

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

フィールド
batch.name string

出力専用。ID。バッチのリソース名。

形式: batches/{batchId}

batch.displayName string

必須。このバッチのユーザー定義名。

batch.inputConfig object (InputEmbedContentConfig)

必須。バッチ処理が実行されるインスタンスの入力構成。

batch.output object (EmbedContentBatchOutput)

出力専用。バッチ リクエストの出力。

batch.createTime string (Timestamp format)

出力専用。バッチが作成された時刻。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z""2014-10-02T15:01:23+05:30"

batch.endTime string (Timestamp format)

出力専用。バッチ処理が完了した時刻。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z""2014-10-02T15:01:23+05:30"

batch.updateTime string (Timestamp format)

出力専用。バッチが最後に更新された時刻。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z""2014-10-02T15:01:23+05:30"

batch.batchStats object (EmbedContentBatchStats)

出力専用。バッチに関する統計情報。

batch.state enum (BatchState)

出力専用。バッチの状態。

batch.priority string (int64 format)

省略可。バッチの優先度。優先度の高い値を持つバッチは、優先度の低い値を持つバッチよりも先に処理されます。負の値を使用できます。デフォルトは 0 です。

レスポンスの本文

成功した場合、レスポンスの本文には Operation のインスタンスが含まれます。

EmbedContentRequest

エンベディングするモデルの Content を含むリクエスト。

フィールド
model string

必須。モデルのリソース名。これは、使用するモデルの ID として機能します。

この名前は、models.list メソッドから返されるモデル名と一致する必要があります。

形式: models/{model}

content object (Content)

必須。埋め込むコンテンツ。parts.text フィールドのみがカウントされます。

taskType enum (TaskType)

省略可。エンベディングが使用されるオプションのタスクタイプ。以前のモデル(models/embedding-001)ではサポートされていません。

title string

省略可。テキストのタイトル(省略可)。TaskType が RETRIEVAL_DOCUMENT の場合にのみ適用されます。

注: RETRIEVAL_DOCUMENTtitle を指定すると、検索用のエンベディングの品質が向上します。

outputDimensionality integer

省略可。出力エンベディングのオプションの削減ディメンション。設定すると、出力エンベディングの過剰な値が末尾から切り捨てられます。2024 年以降の新しいモデルでのみサポートされます。以前のモデル(models/embedding-001)を使用している場合は、この値を設定できません。

JSON 表現
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

EmbedContentRequest へのレスポンス。

フィールド
embedding object (ContentEmbedding)

出力専用。入力コンテンツから生成されたエンベディング。

JSON 表現
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

エンベディングを表す浮動小数点数のリスト。

フィールド
values[] number

エンベディング値。

JSON 表現
{
  "values": [
    number
  ]
}

TaskType

エンベディングが使用されるタスクのタイプ。

列挙型
TASK_TYPE_UNSPECIFIED 設定されていない値。デフォルトでは、他の列挙値のいずれかになります。
RETRIEVAL_QUERY 指定したテキストが検索 / 取得設定のクエリであることを指定します。
RETRIEVAL_DOCUMENT 指定したテキストが検索対象のコーパスのドキュメントであることを指定します。
SEMANTIC_SIMILARITY 指定したテキストが STS で使用されることを指定します。
CLASSIFICATION 指定されたテキストが分類されることを指定します。
CLUSTERING エンベディングをクラスタリングに使用することを指定します。
QUESTION_ANSWERING 指定したテキストが質問応答に使用されることを指定します。
FACT_VERIFICATION 指定したテキストが事実確認に使用されることを指定します。
CODE_RETRIEVAL_QUERY 指定したテキストがコード取得に使用されることを指定します。

EmbedContentBatch

EmbedContent リクエストのバッチを表すリソース。

フィールド
model string

必須。補完の生成に使用する Model の名前。

形式: models/{model}

name string

出力専用。ID。バッチのリソース名。

形式: batches/{batchId}

displayName string

必須。このバッチのユーザー定義名。

inputConfig object (InputEmbedContentConfig)

必須。バッチ処理が実行されるインスタンスの入力構成。

output object (EmbedContentBatchOutput)

出力専用。バッチ リクエストの出力。

createTime string (Timestamp format)

出力専用。バッチが作成された時刻。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z""2014-10-02T15:01:23+05:30"

endTime string (Timestamp format)

出力専用。バッチ処理が完了した時刻。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z""2014-10-02T15:01:23+05:30"

updateTime string (Timestamp format)

出力専用。バッチが最後に更新された時刻。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z""2014-10-02T15:01:23+05:30"

batchStats object (EmbedContentBatchStats)

出力専用。バッチに関する統計情報。

state enum (BatchState)

出力専用。バッチの状態。

priority string (int64 format)

省略可。バッチの優先度。優先度の高い値を持つバッチは、優先度の低い値を持つバッチよりも先に処理されます。負の値を使用できます。デフォルトは 0 です。

JSON 表現
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputEmbedContentConfig)
  },
  "output": {
    object (EmbedContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (EmbedContentBatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputEmbedContentConfig

バッチ リクエストの入力を構成します。

フィールド
source Union type
必須。入力のソース。source は次のいずれかになります。
fileName string

入力リクエストを含む File の名前。

requests object (InlinedEmbedContentRequests)

バッチで処理されるリクエスト。

JSON 表現
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedEmbedContentRequests)
  }
  // Union type
}

InlinedEmbedContentRequests

バッチ作成リクエストの一部として指定された場合、バッチで処理されるリクエスト。

フィールド
requests[] object (InlinedEmbedContentRequest)

必須。バッチで処理されるリクエスト。

JSON 表現
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

バッチで処理されるリクエスト。

フィールド
request object (EmbedContentRequest)

必須。バッチで処理されるリクエスト。

metadata object (Struct format)

省略可。リクエストに関連付けるメタデータ。

JSON 表現
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

バッチ リクエストの出力。これは、AsyncBatchEmbedContentResponse フィールドまたは EmbedContentBatch.output フィールドで返されます。

フィールド
output Union type
バッチ リクエストの出力。output は次のいずれかになります。
responsesFile string

出力専用。回答を含むファイルのファイル ID。ファイルは、1 行に 1 つのレスポンスを含む JSONL ファイルになります。レスポンスは JSON 形式の EmbedContentResponse メッセージになります。レスポンスは、入力リクエストと同じ順序で書き込まれます。

inlinedResponses object (InlinedEmbedContentResponses)

出力専用。バッチ内のリクエストに対するレスポンス。バッチがインライン リクエストを使用して作成された場合に返されます。レスポンスは、入力リクエストと同じ順序で返されます。

JSON 表現
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedEmbedContentResponses)
  }
  // Union type
}

InlinedEmbedContentResponses

バッチ内のリクエストに対するレスポンス。

フィールド
inlinedResponses[] object (InlinedEmbedContentResponse)

出力専用。バッチ内のリクエストに対するレスポンス。

JSON 表現
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

バッチ内の単一のリクエストに対するレスポンス。

フィールド
metadata object (Struct format)

出力専用。リクエストに関連付けられたメタデータ。

output Union type
リクエストの出力。output は次のいずれかになります。
error object (Status)

出力専用。リクエストの処理中に発生したエラー。

response object (EmbedContentResponse)

出力専用。リクエストに対するレスポンス。

JSON 表現
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (EmbedContentResponse)
  }
  // Union type
}

EmbedContentBatchStats

バッチに関する統計情報。

フィールド
requestCount string (int64 format)

出力専用。バッチ内のリクエストの数。

successfulRequestCount string (int64 format)

出力専用。正常に処理されたリクエストの数。

failedRequestCount string (int64 format)

出力専用。処理に失敗したリクエストの数。

pendingRequestCount string (int64 format)

出力専用。処理が保留中のリクエストの数。

JSON 表現
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}