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 时适用。

注意：为 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)
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

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

响应正文

如果成功，则响应正文包含一个 EmbedContentResponse 实例。

方法：models.batchEmbedContents

根据输入 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

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

仅限输出。标识符。批次的资源名称。

格式：batches/{batchId}。

batch.displayName string

必需。相应批次的用户定义名称。

batch.inputConfig object (InputEmbedContentConfig)

必需。执行批处理的实例的输入配置。

batch.output object (EmbedContentBatchOutput)

仅限输出。批量请求的输出。

batch.createTime string (Timestamp format)

仅限输出。批次的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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

仅限输出。标识符。批次的资源名称。

格式：batches/{batchId}。

displayName string

必需。相应批次的用户定义名称。

inputConfig object (InputEmbedContentConfig)

必需。执行批处理的实例的输入配置。

output object (EmbedContentBatchOutput)

仅限输出。批量请求的输出。

createTime string (Timestamp format)

仅限输出。批次的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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
}