API Text embeddings

La API Text embeddings convierte datos de texto en vectores numéricos. Estas representaciones vectoriales se han diseñado para captar el significado semántico y el contexto de las palabras que representan.

Modelos admitidos:

Puedes obtener inserciones de texto con los siguientes modelos:

Nombre del modelo Descripción Dimensiones de salida Longitud máxima de la secuencia Idiomas de texto admitidos
gemini-embedding-001 Rendimiento de última generación en tareas de inglés, multilingües y de código. Unifica los modelos especializados anteriores, como text-embedding-005 y text-multilingual-embedding-002, y consigue un mejor rendimiento en sus respectivos dominios. Consulta más información en nuestro informe técnico. hasta 3072 2048 tokens Idiomas de texto admitidos
text-embedding-005 Especializada en tareas de inglés y código. hasta 768 2048 tokens Inglés
text-multilingual-embedding-002 Especializada en tareas multilingües. hasta 768 2048 tokens Idiomas de texto admitidos

Para obtener una calidad de inserción superior, gemini-embedding-001 es nuestro modelo grande diseñado para ofrecer el máximo rendimiento.

Sintaxis

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 nivel superior

instances

Una lista de objetos que contiene los siguientes campos:

  • content

  • title (opcional)

  • task_type (opcional)

parameters

Un objeto que contiene los siguientes campos:

  • autoTruncate (opcional)

  • outputDimensionality (opcional)

instance campos

content

string

El texto del que quieres generar las inserciones.

task_type

Opcional: string

Se usa para transmitir la aplicación posterior prevista y ayudar al modelo a producir mejores inserciones. Si se deja en blanco, se usará el valor predeterminado RETRIEVAL_QUERY.

  • RETRIEVAL_QUERY
  • RETRIEVAL_DOCUMENT
  • SEMANTIC_SIMILARITY
  • CLASSIFICATION
  • CLUSTERING
  • QUESTION_ANSWERING
  • FACT_VERIFICATION
  • CODE_RETRIEVAL_QUERY

Para obtener más información sobre los tipos de tareas, consulta Elegir un tipo de tarea de inserciones.

title

Opcional: string

Se usa para ayudar al modelo a generar mejores inserciones. Solo es válido con task_type=RETRIEVAL_DOCUMENT.

task_type

En la siguiente tabla se describen los valores del parámetro task_type y sus casos prácticos:

task_type Descripción
RETRIEVAL_QUERY Especifica que el texto proporcionado es una consulta en un entorno de búsqueda o recuperación. Usa RETRIEVAL_DOCUMENT para el lado del documento.
RETRIEVAL_DOCUMENT Especifica que el texto proporcionado es un documento en un contexto de búsqueda o recuperación.
SEMANTIC_SIMILARITY Especifica que el texto proporcionado se utiliza para la similitud textual semántica (STS).
CLASSIFICATION Especifica que la inserción se usa para la clasificación.
CLUSTERING Especifica que la inserción se usa para la creación de clústeres.
QUESTION_ANSWERING Especifica que la inserción de la consulta se usa para responder a preguntas. Usa RETRIEVAL_DOCUMENT para el lado del documento.
FACT_VERIFICATION Especifica que la inserción de la consulta se usa para verificar datos. Usa RETRIEVAL_DOCUMENT para el lado del documento.
CODE_RETRIEVAL_QUERY Especifica que la inserción de consulta se usa para recuperar código de Java y Python. Usa RETRIEVAL_DOCUMENT para el lado del documento.

Tareas de recuperación:

Consulta: usa task_type=RETRIEVAL_QUERY para indicar que el texto de entrada es una consulta de búsqueda. Corpus: usa task_type=RETRIEVAL_DOCUMENT para indicar que el texto de entrada forma parte de la colección de documentos en la que se está buscando.

Tareas de similitud:

Similitud semántica: usa task_type= SEMANTIC_SIMILARITY para ambos textos de entrada y evalúa la similitud de su significado general.

parameters campos

autoTruncate

Opcional: bool

Si se le asigna el valor true, el texto introducido se truncará. Si se define como falso, se devuelve un error si el texto de entrada es más largo que la longitud máxima admitida por el modelo. El valor predeterminado es true.

outputDimensionality

Opcional: int

Se usa para especificar el tamaño de la inserción de salida. Si se define, las inserciones de salida se truncarán al tamaño especificado.

Cuerpo de la solicitud

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

Cuerpo de la respuesta

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

predictions

Lista de objetos con los siguientes campos:

  • embeddings: el resultado generado a partir del texto de entrada. Contiene los siguientes campos:

    • values

    • statistics

embeddings campos

values

Una lista de floats. El campo values contiene una codificación numérica (vector de incrustación) del contenido semántico presente en el texto de entrada proporcionado.

statistics

Las estadísticas calculadas a partir del texto de entrada. Contiene:

  • truncated: indica si el texto de entrada se ha truncado porque superaba el número máximo de tokens permitido por el modelo.

  • token_count: número de tokens del texto de entrada.

Respuesta de ejemplo

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

Ejemplos

Insertar una cadena de texto

En el siguiente ejemplo se muestra cómo obtener la inserción de una cadena de texto.

REST

Después de configurar tu entorno, puedes usar REST para probar una petición de texto. En el siguiente ejemplo se envía una solicitud al endpoint del modelo del editor.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto.
  • TEXT: el texto del que quieres generar las inserciones. Límite: cinco textos de hasta 2048 tokens por texto para todos los modelos,excepto textembedding-gecko@001. La longitud máxima de los tokens de entrada de textembedding-gecko@001 es de 3072. En gemini-embedding-001, cada solicitud solo puede incluir un texto de entrada. Para obtener más información, consulta Límites de inserción de texto.
  • AUTO_TRUNCATE: si se define como false, el texto que supere el límite de tokens provocará que la solicitud falle. El valor predeterminado es true.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la siguiente. Ten en cuenta que values se ha truncado para ahorrar espacio.

Fíjate en lo siguiente de la URL de este ejemplo:
  • Usa el método generateContent para solicitar que la respuesta se devuelva una vez que se haya generado por completo. Para reducir la percepción de latencia de los usuarios, transmite la respuesta a medida que se genera mediante el método streamGenerateContent.
  • El ID del modelo multimodal se encuentra al final de la URL, antes del método (por ejemplo, gemini-2.0-flash). Es posible que esta muestra también admita otros modelos.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la 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 probar este ejemplo, sigue las Go instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 probar este ejemplo, sigue las Java instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 probar este ejemplo, sigue las Node.js instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 admitidos

Todos los modelos de inserciones de texto admiten texto en inglés y se han evaluado con este idioma. El modelo text-multilingual-embedding-002 también admite los siguientes idiomas y se ha evaluado en ellos:

  • Idiomas evaluados: 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) y Chinese (zh).
  • Idiomas disponibles: 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 y Zulu.

El modelo gemini-embedding-001 admite los siguientes 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, 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 y Zulu.

Versiones del modelo

Para usar un modelo estable actual, especifica el número de versión del modelo. Por ejemplo, gemini-embedding-001. No se recomienda especificar un modelo sin un número de versión, ya que se trata de un puntero antiguo a otro modelo y no es estable.

Para obtener más información, consulta Versiones y ciclo de vida de los modelos.

Siguientes pasos

Para obtener documentación detallada, consulta lo siguiente: