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)，则无法设置此值。

示例请求

PythonNode.jsShell
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
 
// 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 对象的字符串。

端点

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

路径参数

model string

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

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

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

请求正文

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

字段
requests[] object (EmbedContentRequest)

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

示例请求

PythonNode.jsShell
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
 
// 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 将用作模型的 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 指定给定文本将用于代码检索。