获取文本嵌入

借助 Vertex AI 文本嵌入 API，您可以使用 Vertex AI 上的生成式 AI 创建文本嵌入。文本嵌入是文本的数值表示法，可捕获字词和短语之间的关系。机器学习模型（尤其是生成式 AI 模型）适用于通过识别大型文本数据集中的模式来创建这些嵌入。您的应用可以使用文本嵌入来处理和生成语言，识别特定于内容的复杂含义和语义关系。每次完成 Google 搜索或查看音乐在线播放推荐时，您都会与文本嵌入进行互动。

文本嵌入的一些常见应用场景包括：

  • 语义搜索：按语义相似度排序搜索文本。
  • 分类：返回文本属性与给定文本类似的项的类。
  • 聚类：将文本属性与给定文本类似的项聚类。
  • 离群值检测：返回文本属性与给定文本相关性最低的项。
  • 对话界面：将可能生成类似回复（例如在对话级嵌入空间中）的句子组聚类。

文本嵌入的工作原理是将文本转换为浮点数数组（称为向量）。这些向量旨在捕获文本的含义。嵌入数组的长度称为向量的维度。例如，一个文本段落可能由包含数百个维度的向量表示。然后，通过计算两段文本的向量表示法之间的数值距离，应用可以确定对象之间的相似度。

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

前提条件

成功创建嵌入需要满足特定的前提条件。如需开始使用，请参阅试用文本嵌入快速入门。

使用此 Colab 调用新发布的文本嵌入模型（textembedding-gecko 和 textembedding-gecko-multilingual）。

Jupyter 笔记本：使用 Colab 或 Jupyter 笔记本调用文本嵌入模型。
在 Colab 中运行

示例应用场景：开发图书推荐聊天机器人

如果您想开发图书推荐聊天机器人，首先需使用深度神经网络 (DNN) 将每本图书转换为嵌入向量，其中一个嵌入向量表示一本书。您只需以输入形式向 DNN 提供书名或文本内容即可。或者，您可以将这两项以及描述图书的任何其他元数据（例如类型）结合使用。

此示例中的嵌入可以由数以千计的图书及其摘要和类型组成，这些图书的表示法（例如艾米莉·勃朗特的《呼啸山庄》和简·奥斯汀的《劝导》）彼此很相似（数值表示法之间的距离近）。而弗·斯科特·菲茨杰拉德的《了不起的盖茨比》距离较远，因为时期、类型和摘要不太相似。

输入是影响嵌入空间方向的主要因素。例如，如果我们只有书名输入，则书名相似但摘要却截然不同的两本书的位置靠得很近。但是，如果添加书名和摘要，则这些相同的图书在嵌入空间中不那么相似（距离较远）。

使用生成式 AI 时，此图书推荐聊天机器人可以根据您的查询总结、推荐并向您展示您可能喜欢（或不喜欢）的图书。

支持的模型

如需了解哪些稳定文本嵌入模型版本可用，请参阅可用的稳定模型版本。如需了解哪些最新文本嵌入模型版本可用，请参阅最新模型。

强烈建议您指定稳定模型版本（例如，textembedding-gecko@003）。最新模型版本为预览版，不是正式版 (GA)。由于最新版本为预览版，因此无法保证可在生产环境中使用。

对于需要向后兼容的嵌入的应用，使用稳定模型版本（例如 textembedding-gecko@003）尤为重要。如果您无需考虑向后兼容性，并且您想使用最新的模型版本，则应明确指定 @latest。如果未指定版本，则 textembedding-gecko 默认为 textembedding-gecko@003，textembedding-gecko-multilingual 默认为 textembedding-gecko-multilingual@001。

最新模型

预览版提供两个模型：

  • text-embedding-preview-0409
  • text-multilingual-embedding-preview-0409

这些模型按照所建立的基准（涵盖检索和分类等各种下游任务），相对于以前的模型进行了改进。如需了解详情，请参阅 Gecko：从大语言模型中提炼的多功能文本嵌入。

这些模型可分别提供比 textembedding-gecko@003 和 textembedding-gecko-multilingual@001 模型更好的嵌入质量。这些模型未遵循 model-name@version 命名惯例。指定这些模型时无需带有“@版本”后缀。示例如下：

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/locations/us-central1/publishers/google/models/text-embedding-preview-0409:predict -d $'{
  "instances": [
    { "content": "What is life?"}
  ],
}'

除了更高的质量之外，新模型还支持以下功能：

  • 支持新参数 outputDimensionality。您可以使用此参数减小嵌入大小，例如用于存储优化。

    • QUESTION_ANSWERING
    • FACT_VERIFICATION

    支持两种新的任务类型。如需查看更多任务类型，请参阅模型参考。

以下示例演示了新功能：

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/locations/us-central1/publishers/google/models/text-embedding-preview-0409:predict -d $'{
  "instances": [
    {
      "task_type": "QUESTION_ANSWERING",
      "content": "What is life?"
    }
  ],
"parameters": {
    "outputDimensionality": 256
  }
}'

使用这些模型时，存在以下限制：

  • 请勿在任务关键型系统或生产系统中使用这些预览版模型。
  • 这些模型仅在 us-central1 中提供。
  • 不支持批量预测。
  • 不支持自定义。

获取文本片段的文本嵌入

您可以使用 Vertex AI API 或 Python 版 Vertex AI SDK 获取文本片段的文本嵌入。对于每个请求，us-central1 中的输入文本不得超过 250 个，而在其他区域中，输入文本不得超过 5 个。每个输入文本的词元限制为 3,072。超过此长度的输入会以静默方式截断。您还可以通过将 autoTruncate 设置为 false 来停用静默截断。

这些示例使用 textembedding-gecko@003 模型。

REST

如需获取文本嵌入，请通过指定发布者模型的 ID 来发送 POST 请求。

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

  • PROJECT_ID：您的项目 ID。
  • TEXT：您要为其生成嵌入的文本。限制：五个文本，每个文本最多 3,072 个词元。
  • AUTO_TRUNCATE：如果设置为 false，则超出词元限制的文本会导致请求失败。默认值为 true。

HTTP 方法和网址：

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict

请求 JSON 正文： 

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

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

curl

将请求正文保存在名为 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/textembedding-gecko@003:predict"

PowerShell

将请求正文保存在名为 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/textembedding-gecko@003:predict" | Select-Object -Expand Content

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

示例 curl 命令

MODEL_ID="textembedding-gecko@003"
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?"}
  ],
}'

Python

如需了解如何安装或更新 Python，请参阅安装 Python 版 Vertex AI SDK。如需了解详情，请参阅 Python API 参考文档。 

from typing import List

from vertexai.language_models import TextEmbeddingInput, TextEmbeddingModel

def embed_text(
    texts: List[str] = ["banana muffins? ", "banana bread? banana muffins?"],
    task: str = "RETRIEVAL_DOCUMENT",
    model_name: str = "textembedding-gecko@003",
) -> List[List[float]]:
    """Embeds texts with a pre-trained, foundational model."""
    model = TextEmbeddingModel.from_pretrained(model_name)
    inputs = [TextEmbeddingInput(text, task) for text in texts]
    embeddings = model.get_embeddings(inputs)
    return [embedding.values for embedding in embeddings]

Go

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Go 设置说明执行操作。如需了解详情，请参阅 Vertex AI Go API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import (
	"context"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1beta1"
	"cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb"
	"google.golang.org/api/option"
	"google.golang.org/protobuf/types/known/structpb"
)

// generateEmbeddings creates embeddings from text provided.
func generateEmbeddings(w io.Writer, prompt, project, location, publisher, model string) error {
	ctx := context.Background()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)

	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		fmt.Fprintf(w, "unable to create prediction client: %v", err)
		return err
	}
	defer client.Close()

	// PredictRequest requires an endpoint, instances, and parameters
	// Endpoint
	base := fmt.Sprintf("projects/%s/locations/%s/publishers/%s/models", project, location, publisher)
	url := fmt.Sprintf("%s/%s", base, model)

	// Instances: the prompt
	promptValue, err := structpb.NewValue(map[string]interface{}{
		"content": prompt,
	})
	if err != nil {
		fmt.Fprintf(w, "unable to convert prompt to Value: %v", err)
		return err
	}

	// PredictRequest: create the model prediction request
	req := &aiplatformpb.PredictRequest{
		Endpoint:  url,
		Instances: []*structpb.Value{promptValue},
	}

	// PredictResponse: receive the response from the model
	resp, err := client.Predict(ctx, req)
	if err != nil {
		fmt.Fprintf(w, "error in prediction: %v", err)
		return err
	}

	fmt.Fprintf(w, "embeddings generated: %v", resp.Predictions[0])
	return nil
}

Java

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Java 设置说明执行操作。如需了解详情，请参阅 Vertex AI Java API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import static java.util.stream.Collectors.toList;

import com.google.cloud.aiplatform.v1beta1.EndpointName;
import com.google.cloud.aiplatform.v1beta1.PredictRequest;
import com.google.cloud.aiplatform.v1beta1.PredictResponse;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceSettings;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class PredictTextEmbeddingsSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Details about text embedding request structure and supported models are available in:
    // https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    String project = "YOUR_PROJECT_ID";
    String model = "textembedding-gecko@003";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "RETRIEVAL_DOCUMENT");
  }

  // Gets text embeddings from a pretrained, foundational model.
  public static List<List<Float>> predictTextEmbeddings(
      String endpoint, String project, String model, List<String> texts, String task)
      throws IOException {
    PredictionServiceSettings settings =
        PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build();
    Matcher matcher = Pattern.compile("^(?<Location>\\w+-\\w+)").matcher(endpoint);
    String location = matcher.matches() ? matcher.group("Location") : "us-central1";
    EndpointName endpointName =
        EndpointName.ofProjectLocationPublisherModelName(project, location, "google", model);

    // You can use this prediction service client for multiple requests.
    try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
      PredictRequest.Builder request =
          PredictRequest.newBuilder().setEndpoint(endpointName.toString());
      for (int i = 0; i < texts.size(); i++) {
        request.addInstances(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("content", valueOf(texts.get(i)))
                        .putFields("taskType", valueOf(task))
                        .build()));
      }
      PredictResponse response = client.predict(request.build());
      List<List<Float>> floats = new ArrayList<>();
      for (Value prediction : response.getPredictionsList()) {
        Value embeddings = prediction.getStructValue().getFieldsOrThrow("embeddings");
        Value values = embeddings.getStructValue().getFieldsOrThrow("values");
        floats.add(
            values.getListValue().getValuesList().stream()
                .map(Value::getNumberValue)
                .map(Double::floatValue)
                .collect(toList()));
      }
      return floats;
    }
  }

  private static Value valueOf(String s) {
    return Value.newBuilder().setStringValue(s).build();
  }
}

Node.js

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Node.js 设置说明执行操作。如需了解详情，请参阅 Vertex AI Node.js API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

async function main(
  project,
  model = 'textembedding-gecko@003',
  texts = 'banana bread?;banana muffins?',
  task = 'RETRIEVAL_DOCUMENT',
  apiEndpoint = 'us-central1-aiplatform.googleapis.com'
) {
  const aiplatform = require('@google-cloud/aiplatform');
  const {PredictionServiceClient} = aiplatform.v1;
  const {helpers} = aiplatform; // helps construct protobuf.Value objects.
  const clientOptions = {apiEndpoint: apiEndpoint};
  const match = apiEndpoint.match(/(?<Location>\w+-\w+)/);
  const location = match ? match.groups.Location : 'us-centra11';
  const endpoint = `projects/${project}/locations/${location}/publishers/google/models/${model}`;

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, taskType: task}));
    const request = {endpoint, instances};
    const client = new PredictionServiceClient(clientOptions);
    const [response] = await client.predict(request);
    console.log('Got predict response');
    const predictions = response.predictions;
    for (const prediction of predictions) {
      const embeddings = prediction.structValue.fields.embeddings;
      const values = embeddings.structValue.fields.values.listValue.values;
      console.log('Got prediction: ' + JSON.stringify(values));
    }
  }

  callPredict();
}

将嵌入添加到向量数据库

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

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

2023 年 8 月或之后发布的模型的 API 更改

使用 2023 年 8 月或之后发布的模型版本（包括 textembedding-gecko@003 和 textembedding-gecko-multilingual@001）时，添加了新的任务类型参数和可选标题（仅在 task_type=RETRIEVAL_DOCUMENT 时有效）。

这些新参数适用于公开预览版模型及之后的所有稳定模型。

{
  "instances": [
    {
      "task_type": "RETRIEVAL_DOCUMENT",
      "title": "document title",
      "content": "I would like embeddings for this text!"
    },
  ]
}

task_type 参数定义为预期的下游应用，可帮助模型生成质量更高的嵌入。它可以是采用以下任一值的字符串：

task_type 说明
RETRIEVAL_QUERY 在搜索或检索设置中指定给定文本是查询。
RETRIEVAL_DOCUMENT 在搜索或检索设置中指定给定文本是文档。
SEMANTIC_SIMILARITY 指定给定文本用于语义文本相似度 (STS)。
CLASSIFICATION 指定嵌入用于分类。
CLUSTERING 指定嵌入用于聚类。
QUESTION_ANSWERING 指定查询嵌入用于回答问题。将 RETRIEVAL_DOCUMENT 用于文本端。
FACT_VERIFICATION 指定查询嵌入用于事实验证。

textembedding-gecko-multilingual 模型的语言覆盖范围。

textembedding-gecko-multilingual@001 模型针对以下语言进行了评估：Arabic (ar)、Bengali (bn)、English (en)、Spanish (es)、German (de)、Persian (fa)、Finnish (fi)、French (fr)、Hindi (hi)、Indonesian (id)、Japanese (ja)、Korean (ko)、Russian (ru)、Swahili (sw)、Telugu (te)、Thai (th)、Yoruba (yo)、Chinese (zh)。

以下是受支持的语言的完整列表：Afrikaans、Albanian、Amharic、Arabic、Armenian、Azerbaijani、Basque、Belarusian、Bengali、Bulgarian、Burmese、Catalan、Cebuano、Chichewa、Chinese、Corsican、Czech、Danish、Dutch、English、Esperanto、Estonian、Filipino、Finnish、French、Galician、Georgian、German、Greek、Gujarati、Haitian Creole、Hausa、Hawaiian、Hebrew、Hindi、Hmong、Hungarian、Icelandic、Igbo、Indonesian、Irish、Italian、Japanese、Javanese、Kannada、Kazakh、Khmer、Korean、Kurdish、Kyrgyz、Lao、Latin、Latvian、Lithuanian、Luxembourgish、Macedonian、Malagasy、Malay、Malayalam、Maltese、Maori、Marathi、Mongolian、Nepali、Norwegian、Pashto、Persian、Polish、Portuguese、Punjabi、Romanian、Russian、Samoan、Scottish Gaelic、Serbian、Shona、Sindhi、Sinhala、Slovak、Slovenian、Somali、Sotho、Spanish、Sundanese、Swahili、Swedish、Tajik、Tamil、Telugu、Thai、Turkish、Ukrainian、Urdu、Uzbek、Vietnamese、Welsh、West Frisian、Xhosa、Yiddish、Yoruba、Zulu。

后续步骤