Veo 3 现已在 Gemini API 中提供！了解详情

此页面由 Cloud Translation API 翻译。

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

响应正文

对 EmbedContentRequest 的响应。

如果成功，响应正文将包含结构如下的数据：

字段

embedding object (ContentEmbedding)

仅限输出。根据输入内容生成的嵌入。

JSON 表示法
{ "embedding": { object (`ContentEmbedding`) } }

方法：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 valuesembed.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

JSON 表示法
{ "model": string, "content": { object (`Content`) }, "taskType": enum (`TaskType`), "title": string, "outputDimensionality": integer }

ContentEmbedding

JSON 表示法

表示嵌入的浮点数列表。

字段

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`	指定给定文本将用于代码检索。