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 实例。

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
}

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
}