获取文本嵌入

本文档介绍如何使用 Vertex AI 文本嵌入 API 创建文本嵌入。

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

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

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

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

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Vertex AI Workbench 中打开 | 在 GitHub 上查看

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 (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 Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 (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 Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

支持的模型

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

模型名称	说明	输出维度	最大序列长度	支持的文本语言
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，这是我们旨在提供最高性能的大型模型。

注意：请仅使用支持的模型表中列出的模型。请勿指定不带 @version 后缀或 @latest的模型。这些模型名称被视为无效。

获取文本片段的文本嵌入

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

API 限额

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

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

选择嵌入维度

默认情况下，所有模型都会生成全长嵌入向量。对于 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_VERTEXAI=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_VERTEXAI=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: "user",
		},
	}

	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
}

将嵌入添加到向量数据库

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

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

后续步骤

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