获取文本嵌入

本文档介绍如何使用 Gemini Enterprise Agent Platform 文本嵌入 API创建文本嵌入。

Gemini Enterprise Agent Platform 文本嵌入 API 使用密集向量表示法： 例如，gemini-embedding-001 使用 3072 维 向量。密集向量嵌入模型使用与大语言模型所用方法类似的深度学习方法。与倾向于将字词直接映射到数字的稀疏向量不同，密集向量旨在更好地表示一段文本的含义。在生成式 AI 中使用密集向量嵌入的优势在于，您可以更好地搜索与查询含义相符的段落，而不是搜索直接的字词或语法匹配项，即使段落不使用相同的语言也是如此。

这些向量已进行标准化处理，因此您可以使用余弦相似度、点积或欧几里得距离来提供相同的相似度排名。

• 如需详细了解嵌入，请参阅嵌入 API 概览。
• 如需了解文本嵌入模型，请参阅文本嵌入。
• 如需了解每个嵌入模型支持的语言，请参阅 支持的文本 语言。

如需查看获取文本嵌入的示例， 请在以下任一环境中运行“文本嵌入 + Agent Platform Vector Search 使用入门”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Agent Platform Workbench 中打开 | 在 GitHub 上查看

准备工作

登录您的 Google Cloud 账号。如果您是新手 Google Cloud， 请创建一个账号来评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. 为嵌入作业选择任务类型。

API 限额

对于每个请求，不能超过250个输入文本。 API 的输入token数量上限为 20,000。超出此限制的输入将导致 400 错误。每个输入文本进一步限制为 2048 个token；任何多余的内容都会以静默方式截断。您还可以通过将 autoTruncate 设置为 false 来停用静默截断。

如需了解详情，请参阅文本嵌入限制。

获取文本片段的文本嵌入

您可以使用 Agent Platform API 或 Python 版 Agent Platform SDK 获取文本片段的文本嵌入。

选择嵌入维度

默认情况下，所有模型都会生成完整长度的嵌入向量。对于 gemini-embedding-001，此向量具有 3072 个维度，其他模型则生成 768 维向量。不过，用户可以使用 output_dimensionality 参数来控制输出嵌入向量的大小。选择较小的输出维度可以节省存储空间，并提高下游应用的计算效率，同时在质量方面几乎没有损失。

以下示例使用 gemini-embedding-001 模型。

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import EmbedContentConfig

client = genai.Client()
response = client.models.embed_content(
    model="gemini-embedding-001",
    contents=[
        "How do I get a driver's license/learner's permit?",
        "How long is my driver's license valid for?",
        "Driver's knowledge test study guide",
    ],
    config=EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",  # Optional
        output_dimensionality=3072,  # Optional
        title="Driver's License",  # Optional
    ),
)
print(response)
# Example response:
# embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
# statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
# metadata=EmbedContentMetadata(billable_character_count=112)

Go

了解如何安装或更新 Go。

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/genai"
)

// generateEmbedContentWithText shows how to embed content with text.
func generateEmbedContentWithText(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	outputDimensionality := int32(3072)
	config := &genai.EmbedContentConfig{
		TaskType:             "RETRIEVAL_DOCUMENT",  //optional
		Title:                "Driver's License",    //optional
		OutputDimensionality: &outputDimensionality, //optional
	}

	contents := []*genai.Content{
		{
			Parts: []*genai.Part{
				{
					Text: "How do I get a driver's license/learner's permit?",
				},
				{
					Text: "How long is my driver's license valid for?",
				},
				{
					Text: "Driver's knowledge test study guide",
				},
			},
			Role: genai.RoleUser,
		},
	}

	modelName := "gemini-embedding-001"
	resp, err := client.Models.EmbedContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	fmt.Fprintln(w, resp)

	// Example response:
	// embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
	// statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
	// metadata=EmbedContentMetadata(billable_character_count=112)

	return nil
}

Node.js

安装

npm install @google/genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;

async function generateEmbeddingsForRetrieval(
  projectId = GOOGLE_CLOUD_PROJECT
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
  });

  const prompt = [
    "How do I get a driver's license/learner's permit?",
    "How long is my driver's license valid for?",
    "Driver's knowledge test study guide",
  ];

  const response = await client.models.embedContent({
    model: 'gemini-embedding-001',
    contents: prompt,
    config: {
      taskType: 'RETRIEVAL_DOCUMENT', // Optional
      outputDimensionality: 3072, // Optional
      title: "Driver's License", // Optional
    },
  });

  console.log(response);

  // Example response:
  //  embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
  //  statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
  //  metadata=EmbedContentMetadata(billable_character_count=112)

  return response;
}

Java

了解如何安装或更新 Java。

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用：

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

public class EmbeddingsDocRetrievalWithTxt {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-embedding-001";
    embedContent(modelId);
  }

  // Shows how to embed content with text.
  public static EmbedContentResponse embedContent(String modelId) {
    // Client Initialization. Once created, it can be reused for multiple requests.
    try (Client client = Client.builder().location("global").vertexAI(true).build()) {

      EmbedContentResponse response =
          client.models.embedContent(
              modelId,
              List.of(
                  "How do I get a driver's license/learner's permit?",
                  "How long is my driver's license valid for?",
                  "Driver's knowledge test study guide"),
              EmbedContentConfig.builder()
                  .taskType("RETRIEVAL_DOCUMENT")
                  .outputDimensionality(3072)
                  .title("Driver's License")
                  .build());

      System.out.println(response);
      // Example response:
      // embeddings=Optional[[ContentEmbedding{values=Optional[[-0.035855383, 0.008127963, ... ]]
      // statistics=Optional[ContentEmbeddingStatistics{truncated=Optional[false],
      // tokenCount=Optional[11.0]}]}]],
      // metadata=Optional[EmbedContentMetadata{billableCharacterCount=Optional[153]}]}
      return response;
    }
  }
}

REST

在使用任何请求数据之前， 请先进行以下替换：

• PROJECT_ID： 您的 [项目 ID](/resource-manager/docs/creating-managing-projects#identifiers)。 。
• TEXT：您要为其生成嵌入 的文本。限制：五个文本，除 textembedding-gecko@001 之外的所有模型的每个文本最多 2,048 个词元。textembedding-gecko@001 的输入词元长度上限为 3072。 对于 gemini-embedding-001，每个请求只能包含一个输入文本。如需了解详情，请参阅文本嵌入限制。
• AUTO_TRUNCATE：如果设置为 false，则超出词元限制的文本会导致请求失败。默认值为 true。

HTTP 方法和网址：

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict

请求 JSON 正文：

{
  "instances": [
    { "content": "TEXT"}
  ],
  "parameters": { 
    "autoTruncate": AUTO_TRUNCATE 
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应。请注意，为节省空间，系统截断了 values。

响应

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": false,
          "token_count": 6
        },
        "values": [ ... ]
      }
    }
  ]
}

示例 curl 命令

MODEL_ID="gemini-embedding-001"
PROJECT_ID=PROJECT_ID

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/${MODEL_ID}:predict -d \
$'{
  "instances": [
    { "content": "What is life?"}
  ],
}'

支持的模型

下表显示了可用的 Google 和开放文本嵌入模型。

Google 模型

您可以使用以下模型获取文本嵌入：

模型名称	说明	输出维度	最大序列长度	支持的文本语言
gemini-embedding-001	在英语、多语言和代码任务方面均表现出卓越性能。它整合了 text-embedding-005 和 text-multilingual-embedding-002 等先前的专用模型，并使它们在各自的领域中实现了更佳性能。如需了解详情，请参阅我们的技术报告。	高达 3072	2048 个 token	支持的文本语言
text-embedding-005	擅长处理英语和代码任务。	高达 768	2048 个 token	英语
text-multilingual-embedding-002	擅长处理多语言任务。	高达 768	2048 个 token	支持的文本语言

如要获得出色的嵌入质量，请使用 gemini-embedding-001，这是我们专为提供最高性能而设计的大型模型。

开放模型

您可以使用以下模型获取文本嵌入：

模型名称	说明	输出维度	最大序列长度	支持的文本语言
multilingual-e5-small	E5 系列文本嵌入模型的一部分。小型变体包含 12 层。	最高 384	512 个词元	支持的语言
multilingual-e5-large	E5 系列文本嵌入模型的一部分。大型变体包含 24 层。	高达 1024	512 个词元	支持的语言

如需开始使用，请参阅 E5 系列模型卡片。 如需详细了解开放模型，请参阅 MaaS 的开放模型

将嵌入添加到向量数据库

生成嵌入后，您可以将嵌入添加到向量数据库，例如 Vector Search。这样可以实现低延迟检索，并且随着数据规模扩大，这一点至关重要。

如需详细了解 Vector Search，请参阅 Vector Search 概览。

后续步骤

• 如需详细了解速率限制，请参阅 Agent Platform 速率限制。
• 如需获取嵌入的批量预测结果，请参阅获取批量文本嵌入 推理结果
  • 如需详细了解多模态嵌入，请参阅获取多模态 嵌入
• 如需调优嵌入，请参阅调优文本嵌入
• 如需详细了解 text-embedding-005 和 text-multilingual-embedding-002 背后的研究，请参阅研究论文 Gecko：从大语言模型中蒸馏的多功能文本嵌入。