Embeddings

嵌入是文本输入的数值表示法，可用于多种独特的用例，例如聚类、相似性衡量和信息检索。如需了解简介，请参阅嵌入指南。

方法：models.embedContent

使用指定的 Gemini 嵌入模型从输入 Content 生成文本嵌入向量。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent

路径参数

model string

必需。模型的资源名称。此 ID 将用作模型的 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

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate
README.md

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({
  model: "text-embedding-004",
});

const result = await model.embedContent("Hello world!");

console.log(result.embedding);
embed.js

Shell

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=$GOOGLE_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 对象的字符串。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

路径参数

model string

必需。模型的资源名称。此 ID 将用作模型的 ID。

此名称应与 models.list 方法返回的模型名称一致。

格式：models/{model} 格式为 models/{model}。

请求正文

请求正文中包含结构如下的数据：

字段
requests[] object (EmbedContentRequest)

必需。嵌入批处理请求。每个请求中的模型都必须与指定的模型 BatchEmbedContentsRequest.model 匹配。

示例请求

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate
README.md

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({
  model: "text-embedding-004",
});

function textToRequest(text) {
  return { content: { role: "user", parts: [{ text }] } };
}

const result = await model.batchEmbedContents({
  requests: [
    textToRequest("What is the meaning of life?"),
    textToRequest("How much wood would a woodchuck chuck?"),
    textToRequest("How does the brain work?"),
  ],
});

console.log(result.embeddings);
embed.js

Shell

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:batchEmbedContents?key=$GOOGLE_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 将用作模型的 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 指定给定文本将用于事实核查。