Embeddings

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

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

方法：models.embedContent

使用指定的 Gemini 嵌入模型，從輸入的 Content 生成文字嵌入向量。

端點

post 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 物件表示的一批字串。

端點

post 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，以免混淆。

端點

post 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 的執行例項。

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
}