Embeddings

嵌入是文字輸入的數值表示法，可開啟許多獨特的用途，例如分群、相似度測量和資訊檢索。如需簡介，請參閱嵌入指南。

與生成新內容的生成式 AI 模型不同，Gemini Embedding 模型只會將輸入資料的格式轉換為數字表示法。Google 負責提供嵌入模型，將輸入資料的格式轉換為要求的數字格式，但使用者仍須對輸入的資料和產生的嵌入內容負全責。使用 Gemini Embedding 模型即代表你確認自己有權使用所上傳一切內容。請勿生成會侵害他人智慧財產或隱私權的內容。使用這項服務時，請務必遵守《使用限制政策》和《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 時才適用。

注意：指定 title 的 RETRIEVAL_DOCUMENT 可提供更優質的擷取內嵌內容。

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)
embed.py

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);
embed.js

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))
embed.go

貝殼

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?"}]}
    }'
embed.sh

回應主體

如果成功，回應主體會包含 EmbedContentResponse 的執行例項。

方法：models.batchEmbedContents

從輸入 Content 產生多個嵌入向量，輸入 Content 包含以 EmbedContentRequest 物件表示的一批字串。

端點

貼文 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)
embed.py

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);
embed.js

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))
embed.go

貝殼

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
embed.sh

回應主體

對 BatchEmbedContentsRequest 的回應。

如果成功，回應主體會含有以下結構的資料：

欄位
embeddings[] object (ContentEmbedding)

僅供輸出。每個要求的嵌入內容，順序與批次要求中提供的順序相同。

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

方法：models.asyncBatchEmbedContent

將一批 models.embedContent 要求排入佇列，以進行批次處理。我們在 GenerativeService 中有一個 models.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 時才適用。

注意：指定 title 的 RETRIEVAL_DOCUMENT 可提供更優質的擷取內嵌內容。

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。這個檔案會是 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
}