Obtener incorporaciones de texto

En este documento, se describe cómo crear un embedding de texto con la API de embeddings de texto de Vertex AI.

La API de embeddings de texto de Vertex AI usa representaciones vectoriales densas: gemini-embedding-001, por ejemplo, usa vectores de 3,072 dimensiones. Los modelos de embedding de vectores densos usan métodos de aprendizaje profundo similares a los que usan los modelos de lenguaje grandes. A diferencia de los vectores dispersos, que tienden a asignar palabras directamente a números, los vectores densos están diseñados para representar mejor el significado de un fragmento de texto. La ventaja de usar embeddings de vectores densos en la IA generativa es que, en lugar de buscar coincidencias de palabras o sintaxis directas, puedes buscar mejor pasajes que se alineen con el significado de la consulta, incluso si los fragmentos no usan el mismo idioma.

Los vectores están normalizados, por lo que puedes usar la similitud de coseno, el producto punto o la distancia euclidiana para proporcionar las mismas clasificaciones de similitud.

Para obtener más información sobre embeddings, consulta la descripción general de las APIs de embeddings.
Para obtener más información sobre los modelos de incorporación de texto, consulta Embeddings de texto.
Para obtener información sobre qué idiomas admite cada modelo de embeddings, consulta Idiomas de texto compatibles.

Antes de comenzar

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Elige un tipo de tarea para tu trabajo de embeddings.

Límites de API

Para cada solicitud, tienes un límite de 250 textos de entrada. La API tiene un límite máximo de tokens de entrada de 20,000. Si se superan estos límites, se genera un error 400. Cada texto de entrada individual también está limitado a 2,048 tokens; cualquier exceso se trunca de forma automática. También puedes inhabilitar el truncamiento automático si configuras autoTruncate como false.

Para obtener más información, consulta Límites de embeddings de texto.

Obtén incorporaciones de texto para un fragmento de texto

Puedes obtener incorporaciones de texto para un fragmento de texto mediante la API de Vertex AI o el SDK de Vertex AI para Python.

Elige una dimensión de embedding

De forma predeterminada, todos los modelos producen un vector de embedding de longitud completa. Para gemini-embedding-001, este vector tiene 3,072 dimensiones, y otros modelos producen vectores de 768 dimensiones. Sin embargo, con el parámetro output_dimensionality, los usuarios pueden controlar el tamaño del vector de embedding de salida. Seleccionar una dimensionalidad de salida más pequeña puede ahorrar espacio de almacenamiento y aumentar la eficiencia de procesamiento para las aplicaciones downstream, sin sacrificar mucho en términos de calidad.

En los siguientes ejemplos, se usa el modelo gemini-embedding-001.

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de Gen AI con 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

Obtén información para instalar o actualizar Go.

Para obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de Gen AI con 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: genai.RoleUser,
		},
	}

	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
}

Node.js

Instalar

npm install @google/genai

Para obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de Gen AI con 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

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;

async function generateEmbeddingsForRetrieval(
  projectId = GOOGLE_CLOUD_PROJECT
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
  });

  const prompt = [
    "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",
  ];

  const response = await client.models.embedContent({
    model: 'gemini-embedding-001',
    contents: prompt,
    config: {
      taskType: 'RETRIEVAL_DOCUMENT', // Optional
      outputDimensionality: 3072, // Optional
      title: "Driver's License", // Optional
    },
  });

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

  return response;
}

Java

Obtén información para instalar o actualizar Java.

Para obtener más información, consulta la documentación de referencia del SDK.

Configura las variables de entorno para usar el SDK de Gen AI con 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 com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

public class EmbeddingsDocRetrievalWithTxt {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-embedding-001";
    embedContent(modelId);
  }

  // Shows how to embed content with text.
  public static EmbedContentResponse embedContent(String modelId) {
    // Client Initialization. Once created, it can be reused for multiple requests.
    try (Client client = Client.builder().location("global").vertexAI(true).build()) {

      EmbedContentResponse response =
          client.models.embedContent(
              modelId,
              List.of(
                  "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"),
              EmbedContentConfig.builder()
                  .taskType("RETRIEVAL_DOCUMENT")
                  .outputDimensionality(3072)
                  .title("Driver's License")
                  .build());

      System.out.println(response);
      // Example response:
      // embeddings=Optional[[ContentEmbedding{values=Optional[[-0.035855383, 0.008127963, ... ]]
      // statistics=Optional[ContentEmbeddingStatistics{truncated=Optional[false],
      // tokenCount=Optional[11.0]}]}]],
      // metadata=Optional[EmbedContentMetadata{billableCharacterCount=Optional[153]}]}
      return response;
    }
  }
}

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: El ID del proyecto.
TEXT: El texto para el que deseas generar incorporaciones. Límite: cinco textos de hasta 2,048 tokens por texto para todos los modelos, excepto textembedding-gecko@001. La longitud máxima del token de entrada para textembedding-gecko@001 es 3,072. Para gemini-embedding-001, cada solicitud solo puede incluir un texto de entrada. Para obtener más información, consulta Límites de embeddings de texto.
AUTO_TRUNCATE: Si se establece en false, el texto que excede el límite del token hace que la solicitud falle. El valor predeterminado es true.

HTTP method and 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

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

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

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

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 que se muestra a continuación: Ten en cuenta que values se truncó para ahorrar espacio.

Respuesta

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

Ejemplo del comando curl

MODEL_ID="gemini-embedding-001"
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?"}
  ],
}'

Modelos compatibles

En las siguientes tablas, se muestran los modelos de embeddings de texto abiertos y de Google disponibles.

Modelos de Google

Puedes obtener incorporaciones de texto con los siguientes modelos:

Nombre del modelo	Descripción	Dimensiones de la salida	Longitud máxima de la secuencia	Idiomas de texto compatibles
`gemini-embedding-001`	Rendimiento de vanguardia en tareas en inglés, multilingües y de código Unifica los modelos especializados anteriores, como `text-embedding-005` y `text-multilingual-embedding-002`, y logra un mejor rendimiento en sus respectivos dominios. Lee nuestro Informe técnico para obtener más detalles.	Hasta 3,072	2,048 tokens	Idiomas de texto compatibles
`text-embedding-005`	Se especializa en tareas en inglés y de código.	Hasta 768	2,048 tokens	Inglés
`text-multilingual-embedding-002`	Se especializa en tareas multilingües.	Hasta 768	2,048 tokens	Idiomas de texto compatibles

Para obtener una calidad de embedding superior, gemini-embedding-001 es nuestro modelo grande diseñado para proporcionar el mayor rendimiento.

Modelos abiertos

Puedes obtener incorporaciones de texto con los siguientes modelos:

Nombre del modelo	Descripción	Dimensiones de salida	Longitud máxima de la secuencia	Idiomas de texto compatibles
`multilingual-e5-small`	Forma parte de la familia de modelos de embeddings de texto E5. La variante pequeña contiene 12 capas.	Hasta 384	512 tokens	Idiomas compatibles
`multilingual-e5-large`	Forma parte de la familia de modelos de embeddings de texto E5. La variante grande contiene 24 capas.	Hasta 1,024	512 tokens	Idiomas compatibles

Para comenzar, consulta la tarjeta del modelo de la familia E5 model card. Para obtener más información sobre los modelos abiertos, consulta Modelos abiertos para MaaS

Agrega una incorporación a una base de datos vectorial

Después de generar tu incorporación, puedes agregar incorporaciones a una base de datos vectorial, como Vector Search. Esto permite una recuperación de latencia baja y es fundamental a medida que aumenta el tamaño de los datos.

Para obtener más información sobre Vector Search, consulta Descripción general de Vector Search.

¿Qué sigue?

Para obtener más información sobre los límites de frecuencia, consulta Límites de frecuencia de IA generativa en Vertex AI.
Con el fin de obtener predicciones por lotes para embeddings, consulta Obtén predicciones de embeddings de texto por lotes
- Para obtener más información sobre las embeddings multimodales, consulta Obtén embeddings multimodales
Para ajustar un embedding, consulta Ajusta embeddings de texto
Para obtener más información sobre la investigación detrás de text-embedding-005 y text-multilingual-embedding-002, consulta el artículo de investigación Gecko: Versatile Embeddings de texto versátiles extraídas de modelos de lenguaje grandes.

Obtener incorporaciones de texto Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Límites de API

Obtén incorporaciones de texto para un fragmento de texto

Elige una dimensión de embedding

Python

Instalar

Go

Node.js

Instalar

Java

REST

curl

PowerShell

Respuesta

Ejemplo del comando curl

Modelos compatibles

Modelos de Google

Modelos abiertos

Agrega una incorporación a una base de datos vectorial

¿Qué sigue?

Obtener incorporaciones de texto