Embeddings

嵌入是文本输入的数值表示法，可用于多种独特的用例，例如聚类、相似性衡量和信息检索。有关介绍，请查看嵌入指南。

方法：models.embedContent

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

端点

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

路径参数

model string

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

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

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

请求正文

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

<ph type="x-smartling-placeholder">
</ph> 田野
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

import google.generativeai as genai

text = "Hello World!"
result = genai.embed_content(
    model="models/text-embedding-004", content=text, output_dimensionality=10
)
print(result["embedding"])
embed.py

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 对象的字符串。

端点

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

路径参数

model string

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

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

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

请求正文

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

<ph type="x-smartling-placeholder">
</ph> 田野
requests[] object (EmbedContentRequest)

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

示例请求

Python

import google.generativeai as genai

texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = genai.embed_content(
    model="models/text-embedding-004", content=texts, output_dimensionality=10
)
print(result)
embed.py

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。

此名称应与 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 指定给定文本将用于事实验证。