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}

要求主體

要求主體的資料會採用以下結構:

Fields
content object (Content)

必要欄位。要嵌入的內容。系統只會計算 parts.text 欄位。

taskType enum (TaskType)

(選用步驟) 要使用嵌入內容的選用工作類型。舊款機型 (models/embedding-001) 不支援這項功能。

title string

(選用步驟) 文字的選用標題。只有在 TaskType 為 RETRIEVAL_DOCUMENT 時才適用。

注意:為 RETRIEVAL_DOCUMENT 指定 title,可提供品質較佳的嵌入內容以供擷取。

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))

貝殼

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

回應主體

EmbedContentRequest 的回應。

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

欄位
embedding object (ContentEmbedding)

僅供輸出。從輸入內容生成的嵌入。

JSON 表示法
{
  "embedding": {
    object (ContentEmbedding)
  }
}

方法:models.batchEmbedContents

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

端點

貼文 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

路徑參數

model string

必要欄位。模型的資源名稱。這是模型使用的 ID。

這個名稱應與 models.list 方法傳回的模型名稱相符。

格式:models/{model},形式為 models/{model}

要求主體

要求主體的資料會採用以下結構:

Fields
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))

貝殼

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)
    }
  ]
}

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_DOCUMENT 指定 title,可提供品質較佳的嵌入內容以供擷取。

outputDimensionality integer

(選用步驟) 輸出嵌入的選用縮減維度。如果設定此值,輸出嵌入中的過多值會從結尾截斷。僅支援 2024 年以後的新型號。如果使用舊版模型 (models/embedding-001),則無法設定這個值。

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

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 指定要使用提供的文字擷取驗證碼。