Text Embeddings API

Text embeddings API 可将文本数据转换为数值向量。这些向量表示旨在捕获它们所表示字词的语义含义和上下文。

支持的模型：

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

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

语法

curl

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

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

Python

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

import vertexai
from vertexai.language_models import TextEmbeddingModel

vertexai.init(project=PROJECT_ID, location=REGION)

model = TextEmbeddingModel.from_pretrained(MODEL_ID)
embeddings = model.get_embeddings(...)

参数列表

顶级字段
instances	包含以下字段的对象列表： content title（可选） task_type（可选）
parameters	包含以下字段的对象： autoTruncate（可选） outputDimensionality（可选）

instance 个字段
content	string 您要为其生成嵌入的文本。
task_type	可选：string。 用于传达预期的下游应用，以帮助模型生成更好的嵌入。如果留空，则使用默认值 RETRIEVAL_QUERY。 RETRIEVAL_QUERY RETRIEVAL_DOCUMENT SEMANTIC_SIMILARITY CLASSIFICATION CLUSTERING QUESTION_ANSWERING FACT_VERIFICATION CODE_RETRIEVAL_QUERY 如需详细了解任务类型，请参阅选择嵌入任务类型。
title	可选：string。 用于帮助模型生成质量更高的嵌入。 此参数必须与 task_type=RETRIEVAL_DOCUMENT 共同使用才能生效。

task_type

下表列出了 task_type 参数值及其应用场景：

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

检索任务：

查询：使用 task_type=RETRIEVAL_QUERY 指示输入文本是搜索查询。语料库：使用 task_type=RETRIEVAL_DOCUMENT 表示输入文本属于要搜索的文档集合的一部分。

相似度任务：

语义相似度：对两段输入文本使用 task_type=SEMANTIC_SIMILARITY，以评估它们的整体含义相似度。

注意：SEMANTIC_SIMILARITY 不适用于检索用例，例如文档搜索和信息检索。对于这些应用场景，请使用 RETRIEVAL_DOCUMENT、RETRIEVAL_QUERY、QUESTION_ANSWERING 和 FACT_VERIFICATION。

parameters 个字段
autoTruncate	可选：bool。 如果设置为 true，输入文本将被截断。如果设置为 false，当输入文本的长度超过模型支持的最大长度时，系统会返回错误。默认值为 true。
outputDimensionality	可选：int。 用于指定输出嵌入大小。如果设置此参数，则输出嵌入将被截断为指定的大小。

请求正文

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

响应正文

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": boolean,
          "token_count": integer
        },
        "values": [ number ]
      }
    }
  ]
}

响应元素
predictions	包含以下字段的对象列表： embeddings：根据输入文本生成的结果。包含以下字段： values statistics

embeddings 个字段
values	float 的列表。values 字段包含给定输入文本中语义内容的数值编码（嵌入向量）。
statistics	根据输入文本计算的统计信息。 包含： truncated：表示输入文本是否因超过模型允许的 token 数量上限而被截断。 token_count：输入文本的 token 数。

示例响应

{
  "predictions": [
    {
      "embeddings": {
        "values": [
          0.0058424929156899452,
          0.011848051100969315,
          0.032247550785541534,
          -0.031829461455345154,
          -0.055369812995195389,
          ...
        ],
        "statistics": {
          "token_count": 4,
          "truncated": false
        }
      }
    }
  ]
}

示例

嵌入文本字符串

以下示例展示了如何获取文本字符串的嵌入。

REST

设置您的环境后，您可以使用 REST 测试文本提示。以下示例会向发布方模型端点发送请求。

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

• PROJECT_ID：您的项目 ID。
• 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": [ ... ]
      }
    }
  ]
}

请注意此示例网址中的以下内容：

• 使用 generateContent 方法请求在回答完全生成后返回回答。 为了降低真人观众对于延迟的感知度，请使用 streamGenerateContent 方法在生成回答时流式传输回答。
• 多模态模型 ID 位于网址末尾且位于方法之前（例如 gemini-2.0-flash）。此示例可能还支持其他模型。

Python

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

from __future__ import annotations

from vertexai.language_models import TextEmbeddingInput, TextEmbeddingModel


def embed_text() -> list[list[float]]:
    """Embeds texts with a pre-trained, foundational model.

    Returns:
        A list of lists containing the embedding vectors for each input text
    """

    # A list of texts to be embedded.
    texts = ["banana muffins? ", "banana bread? banana muffins?"]
    # The dimensionality of the output embeddings.
    dimensionality = 3072
    # The task type for embedding. Check the available tasks in the model's documentation.
    task = "RETRIEVAL_DOCUMENT"

    model = TextEmbeddingModel.from_pretrained("gemini-embedding-001")
    kwargs = dict(output_dimensionality=dimensionality) if dimensionality else {}

    embeddings = []
    # gemini-embedding-001 takes one input at a time
    for text in texts:
        text_input = TextEmbeddingInput(text, task)
        embedding = model.get_embeddings([text_input], **kwargs)
        print(embedding)
        # Example response:
        # [[0.006135190837085247, -0.01462465338408947, 0.004978656303137541, ...]]
        embeddings.append(embedding[0].values)

    return embeddings

Go

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

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

import (
	"context"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1"
	"cloud.google.com/go/aiplatform/apiv1/aiplatformpb"

	"google.golang.org/api/option"
	"google.golang.org/protobuf/types/known/structpb"
)

// embedTexts shows how embeddings are set for gemini-embedding-001 model
func embedTexts(w io.Writer, project, location string) error {
	// location := "us-central1"
	ctx := context.Background()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	dimensionality := 3072
	model := "gemini-embedding-001"
	texts := []string{"banana muffins? ", "banana bread? banana muffins?"}

	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return err
	}
	defer client.Close()

	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)
	allEmbeddings := make([][]float32, 0, len(texts))
	// gemini-embedding-001 takes 1 input at a time
	for _, text := range texts {
		instances := make([]*structpb.Value, 1)
		instances[0] = structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"content":   structpb.NewStringValue(text),
				"task_type": structpb.NewStringValue("QUESTION_ANSWERING"),
			},
		})

		params := structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"outputDimensionality": structpb.NewNumberValue(float64(dimensionality)),
			},
		})

		req := &aiplatformpb.PredictRequest{
			Endpoint:   endpoint,
			Instances:  instances,
			Parameters: params,
		}
		resp, err := client.Predict(ctx, req)
		if err != nil {
			return err
		}

		// Process the prediction for the single text
		// The response will contain one prediction because we sent one instance.
		if len(resp.Predictions) == 0 {
			return fmt.Errorf("no predictions returned for text \"%s\"", text)
		}

		prediction := resp.Predictions[0]
		embeddingValues := prediction.GetStructValue().Fields["embeddings"].GetStructValue().Fields["values"].GetListValue().Values

		currentEmbedding := make([]float32, len(embeddingValues))
		for j, value := range embeddingValues {
			currentEmbedding[j] = float32(value.GetNumberValue())
		}
		allEmbeddings = append(allEmbeddings, currentEmbedding)
	}

	if len(allEmbeddings) > 0 {
		fmt.Fprintf(w, "Dimensionality: %d. Embeddings length: %d", len(allEmbeddings[0]), len(allEmbeddings))
	} else {
		fmt.Fprintln(w, "No texts were processed.")
	}
	return nil
}

Java

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

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

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

import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.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.OptionalInt;
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 = "gemini-embedding-001";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "QUESTION_ANSWERING",
        OptionalInt.of(3072));
  }

  // 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,
      OptionalInt outputDimensionality)
      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);

    List<List<Float>> floats = new ArrayList<>();
    // You can use this prediction service client for multiple requests.
    try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
      // gemini-embedding-001 takes one input at a time.
      for (int i = 0; i < texts.size(); i++) {
        PredictRequest.Builder request = 
            PredictRequest.newBuilder().setEndpoint(endpointName.toString());
        if (outputDimensionality.isPresent()) {
          request.setParameters(
              Value.newBuilder()
                  .setStructValue(
                      Struct.newBuilder()
                          .putFields(
                              "outputDimensionality", valueOf(outputDimensionality.getAsInt()))
                          .build()));
        }
        request.addInstances(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("content", valueOf(texts.get(i)))
                        .putFields("task_type", valueOf(task))
                        .build()));
        PredictResponse response = client.predict(request.build());

        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();
  }

  private static Value valueOf(int n) {
    return Value.newBuilder().setNumberValue(n).build();
  }
}

Node.js

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

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

async function main(
  project,
  model = 'gemini-embedding-001',
  texts = 'banana bread?;banana muffins?',
  task = 'QUESTION_ANSWERING',
  dimensionality = 0,
  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 location = 'us-central1';
  const endpoint = `projects/${project}/locations/${location}/publishers/google/models/${model}`;

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, task_type: task}));

    const client = new PredictionServiceClient(clientOptions);
    const parameters = helpers.toValue(
      dimensionality > 0 ? {outputDimensionality: parseInt(dimensionality)} : {}
    );
    const allEmbeddings = []
    // gemini-embedding-001 takes one input at a time.
    for (const instance of instances) {
      const request = {endpoint, instances: [instance], parameters};
      const [response] = await client.predict(request);
      const predictions = response.predictions;

      const embeddings = predictions.map(p => {
        const embeddingsProto = p.structValue.fields.embeddings;
        const valuesProto = embeddingsProto.structValue.fields.values;
        return valuesProto.listValue.values.map(v => v.numberValue);
      });

      allEmbeddings.push(embeddings[0])
    }


    console.log('Got embeddings: \n' + JSON.stringify(allEmbeddings));
  }

  callPredict();
}

支持的文本语言

所有文本嵌入模型都支持英语文本，并已针对英语文本进行评估。text-multilingual-embedding-002 模型还支持以下语言，并已针对这些语言进行评估：

• 已经过评估的语言：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, Belarusiasn, 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。

gemini-embedding-001 模型支持以下语言：

Arabic、Bengali、Bulgarian、Chinese (Simplified and Traditional)、Croatian、Czech、Danish、Dutch、English、Estonian、Finnish、French、German、Greek、Hebrew、Hindi、Hungarian、Indonesian、Italian、Japanese、Korean、Latvian、Lithuanian、Norwegian、Polish、Portuguese、Romanian、Russian、Serbian、Slovak、Slovenian、Spanish、Swahili、Swedish、Thai、Turkish、Ukrainian、Vietnamese、Afrikaans、Amharic、Assamese、Azerbaijani、Belarusian、Bosnian、Catalan、Cebuano、Corsican、Welsh、Dhivehi、Esperanto、Basque、Persian、Filipino (Tagalog)、Frisian、Irish、Scots Gaelic、Galician、Gujarati、Hausa、Hawaiian、Hmong、Haitian Creole、Armenian、Igbo、Icelandic、Javanese、Georgian、Kazakh、Khmer、Kannada、Krio、Kurdish、Kyrgyz、Latin、Luxembourgish、Lao、Malagasy、Maori、Macedonian、Malayalam、Mongolian、Meiteilon (Manipuri)、Marathi、Malay、Maltese、Myanmar (Burmese)、Nepali、Nyanja (Chichewa)、Odia (Oriya)、Punjabi、Pashto、Sindhi、Sinhala (Sinhalese)、Samoan、Shona、Somali、Albanian、Sesotho、Sundanese、Tamil、Telugu、Tajik、Uyghur、Urdu、Uzbek、Xhosa、Yiddish、Yoruba、Zulu。

模型版本

如需使用当前稳定版模型，请指定模型版本号，例如 gemini-embedding-001。不推荐指定不含版本号的模型，因为其仅仅是一个指向另一个模型的旧版指针，并且不稳定。

如需了解详情，请参阅模型版本和生命周期。

后续步骤

如需查看详细文档，请参阅以下内容：

• 文本嵌入