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 incorporación 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 pasajes no usan el mismo idioma.

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

• Para obtener más información sobre los 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.

Para ver un ejemplo de cómo obtener embeddings de texto, ejecuta el notebook “Comienza a usar embeddings de texto y la búsqueda de vectores de Vertex AI” en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Vertex AI Workbench | Ver en GitHub

Antes de comenzar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

1. 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 20,000 tokens de entrada. Si se superan estos límites, se genera un error 400. Cada texto de entrada individual tiene un límite de 2,048 tokens. Cualquier exceso se trunca de forma silenciosa. También puedes inhabilitar el truncamiento silencioso configurando autoTruncate como false.

Para obtener más información, consulta Límites de incorporaciones 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 computacional para las aplicaciones posteriores, 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.

Establece variables de entorno para usar el SDK de IA generativa 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 más información para instalar o actualizar Go.

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

Establece variables de entorno para usar el SDK de IA generativa 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: "user",
		},
	}

	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
}

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. En el caso de gemini-embedding-001, cada solicitud solo puede incluir un texto de entrada. Para obtener más información, consulta Límites de los 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 incorporación 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 de código y en inglés.	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.

Nota: Usa solo los modelos que se indican en la tabla de modelos compatibles. No especifiques un modelo sin el sufijo @version o @latest. Estos nombres de modelo no se consideran válidos.

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	Lenguajes de texto admitidos
multilingual-e5-small	Es parte de la familia de modelos de embedding de texto E5. La variante pequeña contiene 12 capas.	Hasta 384	512 tokens	Idiomas admitidos
multilingual-e5-large	Es parte de la familia de modelos de embedding de texto E5. La variante grande contiene 24 capas.	Hasta 1,024	512 tokens	Idiomas admitidos

Para comenzar, consulta la tarjeta del modelo de la familia E5. Para obtener más información sobre los modelos abiertos, consulta Modelos abiertos para el 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 la IA generativa en Vertex AI.
• Para obtener predicciones por lotes para embeddings, consulta Obtén predicciones de embeddings de texto por lotes.
  • Para obtener más información sobre las incorporaciones multimodales, consulta Obtén incorporaciones 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: Embeddings de texto versátiles extraídas de modelos de lenguaje grandes.