Embeddings

嵌入是文字輸入的數值表示法，可用於多種特殊用途，例如分群、相似度評估和資訊擷取。如需簡介，請參閱嵌入指南。

方法：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 時才適用。

注意：為 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="text-embedding-004",
    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: "text-embedding-004",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
embed.js

貝殼

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/text-embedding-004",
    "content": {
    "parts":[{
      "text": "Hello world"}]}, }' 2> /dev/null | head
embed.sh

回應主體

對 EmbedContentRequest 的回應。

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

欄位
embedding object (ContentEmbedding)

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

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

方法：models.batchEmbedContents

從輸入的 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="text-embedding-004",
    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: "text-embedding-004",
  contents: texts,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);
embed.js

貝殼

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:batchEmbedContents?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/text-embedding-004",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/text-embedding-004",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/text-embedding-004",
      "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)
    }
  ]
}

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 指定要使用指定文字來擷取程式碼。