API Text Embeddings

A API Text Embeddings converte dados textuais em vetores numéricos. Essas representações vetoriais são projetadas para capturar o significado semântico e o contexto das palavras que representam.

Modelos com suporte:

Você pode obter embeddings de texto usando os seguintes modelos:

Nome do modelo	Descrição	Dimensões de saída	Comprimento máximo da sequência	Idiomas de texto compatíveis
gemini-embedding-001	Desempenho de ponta em tarefas de inglês, multilíngues e de código. Ele unifica os modelos especializados anteriores, como text-embedding-005 e text-multilingual-embedding-002, e alcança um desempenho melhor nos respectivos domínios. Leia nosso Relatório técnico para mais detalhes.	até 3072	2.048 tokens	Idiomas de texto compatíveis
text-embedding-005	Especializado em tarefas de inglês e programação.	até 768	2.048 tokens	Inglês
text-multilingual-embedding-002	Especializado em tarefas multilíngues.	até 768	2.048 tokens	Idiomas de texto compatíveis

Para uma qualidade de incorporação superior, o gemini-embedding-001 é nosso modelo grande projetado para oferecer a melhor performance. O gemini-embedding-001 aceita uma instância por solicitação.

Sintaxe

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(...)

Lista de parâmetros

Campos de nível superior
instances	Uma lista de objetos que contêm os seguintes campos: content title (opcional) task_type (opcional)
parameters	Um objeto que contém os seguintes campos: autoTruncate (opcional) outputDimensionality (opcional)

instance campos
content	string O texto para o qual você quer gerar embeddings.
task_type	Opcional: string Usado para transmitir o aplicativo downstream pretendido que ajuda o modelo a produzir embeddings melhores. Se ficar em branco, o padrão usado será RETRIEVAL_QUERY. RETRIEVAL_QUERY RETRIEVAL_DOCUMENT SEMANTIC_SIMILARITY CLASSIFICATION CLUSTERING QUESTION_ANSWERING FACT_VERIFICATION CODE_RETRIEVAL_QUERY Para mais informações sobre tipos de tarefas, consulte Escolher um tipo de tarefa de embeddings.
title	Opcional: string Usado para ajudar o modelo a produzir embeddings melhores. Válido apenas com task_type=RETRIEVAL_DOCUMENT.

task_type

A tabela a seguir descreve os valores do parâmetro task_type e os casos de uso deles:

task_type	Descrição
RETRIEVAL_QUERY	Especifica que o texto é uma consulta em uma configuração de pesquisa ou recuperação. Use RETRIEVAL_DOCUMENT para o documento.
RETRIEVAL_DOCUMENT	Especifica que o texto é um documento em uma configuração de pesquisa ou recuperação.
SEMANTIC_SIMILARITY	Especifica que o texto fornecido é usado para Similaridade Textual Semântica (STS).
CLASSIFICATION	Especifica que o embedding é usado para classificação.
CLUSTERING	Especifica que o embedding é usado para clustering.
QUESTION_ANSWERING	Especifica que o embedding de consulta é usado para responder a perguntas. Use RETRIEVAL_DOCUMENT para o documento.
FACT_VERIFICATION	Especifica que o embedding de consulta é usado para a verificação de fatos. Use RETRIEVAL_DOCUMENT para o documento.
CODE_RETRIEVAL_QUERY	Especifica que o embedding de consulta é usado para recuperação de código em Java e Python. Use RETRIEVAL_DOCUMENT para o documento.

Tarefas de recuperação:

Consulta: use task_type=RETRIEVAL_QUERY para indicar que o texto de entrada é uma consulta de pesquisa. Corpus: use task_type=RETRIEVAL_DOCUMENT para indicar que o texto de entrada faz parte da coleção de documentos pesquisada.

Tarefas de similaridade:

Similaridade semântica: use task_type= SEMANTIC_SIMILARITY para os dois textos de entrada e avalie a similaridade geral de significado.

Observação: o SEMANTIC_SIMILARITY não foi criado para casos de uso de recuperação, como pesquisa de documentos e recuperação de informações. Para esses casos de uso, use RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, QUESTION_ANSWERING e FACT_VERIFICATION.

parameters campos
autoTruncate	Opcional: bool Quando definido como verdadeiro, o texto de entrada será truncado. Quando definido como falso, um erro será retornado se o texto de entrada for maior que o tamanho máximo aceito pelo modelo. O padrão é "true".
outputDimensionality	Opcional: int Usado para especificar o tamanho do embedding de saída. Se definido, os embeddings de saída serão truncados no tamanho especificado.

Corpo da solicitação

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

Corpo da resposta

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

Elementos de resposta
predictions	Uma lista de objetos com os seguintes campos: embeddings: o resultado gerado a partir do texto de entrada. Contém os seguintes campos: values statistics

embeddings campos
values	Uma lista de floats. O campo values contém uma codificação numérica (vetor de embedding) do conteúdo semântico presente no texto de entrada.
statistics	As estatísticas calculadas a partir do texto de entrada. Contém: truncated: indica se o texto de entrada foi truncado por ser maior que o número máximo de tokens permitido pelo modelo. token_count: número de tokens do texto de entrada.

Exemplo de resposta

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

Exemplos

Incorporar uma string de texto

O exemplo abaixo mostra como receber o embedding de uma string de texto.

REST

Depois de configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: o ID do projeto.
• TEXT: o texto ao qual você quer gerar embeddings. Limite: cinco textos de até 2.048 tokens por texto para todos os modelos, exceto textembedding-gecko@001. O comprimento máximo do token de entrada para textembedding-gecko@001 é 3.072. Para gemini-embedding-001, cada solicitação só pode incluir um texto de entrada. Para mais informações, consulte Limites de embeddings de texto.
• AUTO_TRUNCATE: se definido como false, o texto que exceder o limite de tokens fará com que a solicitação falhe. O valor padrão é true.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a seguinte. Observe que values foi truncado para economizar espaço.

Resposta

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

Observe o seguinte no URL deste exemplo:

• Use o generateContent para solicitar que a resposta seja retornada depois de ser totalmente gerada. Para reduzir a percepção de latência ao público humano, transmita a resposta à medida que geradas usando o streamGenerateContent .
• O ID do modelo multimodal está localizado no final do URL, antes do método Por exemplo, gemini-2.0-flash). Este exemplo pode oferecer suporte a outros modelos de classificação.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

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

Antes de testar esse exemplo, siga as instruções de configuração para Go no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Go.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Idiomas de texto compatíveis

Todos os modelos de embedding de texto são compatíveis e foram avaliados em inglês de texto. O modelo text-multilingual-embedding-002 também oferece suporte e foi avaliado nos seguintes idiomas:

• Idiomas avaliados: 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)
• Idiomas disponíveis: 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.

O modelo gemini-embedding-001 é compatível com os seguintes idiomas:

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, , , , , , , , , , , , , , , , , 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.DhivehiEsperantoBasquePersianFilipino (Tagalog)FrisianIrishScots GaelicGalicianGujaratiHausaHawaiianHmongHaitian CreoleArmenianIgboIcelandicJavaneseGeorgianKazakhKhmerKannadaKrioKurdishKyrgyzLatinLuxembourgishLaoMalagasyMaoriMacedonianMalayalamMongolianMeiteilon (Manipuri)MarathiMalayMalteseMyanmar (Burmese)NepaliNyanja (Chichewa)Odia (Oriya)PunjabiPashtoSindhiSinhala (Sinhalese)SamoanShonaSomaliAlbanianSesothoSundaneseTamilTeluguTajikUyghurUrduUzbekXhosaYiddishYorubaZulu

Versões do modelo

Para usar um modelo estável atual, especifique o número da versão do modelo, por exemplo, gemini-embedding-001. Não é recomendável especificar um modelo sem um número de versão, já que ele é apenas um ponteiro legado para outro modelo e não é estável.

Para mais informações, consulte Versões e ciclo de vida do modelo.

A seguir

Para consultar a documentação detalhada, acesse:

• Embeddings de texto