Acessar incorporações de texto

Este documento descreve como criar um embedding de texto usando a API Text embeddings da Vertex AI.

A API Text embeddings da Vertex AI usa representações vetoriais densas: gemini-embedding-001, por exemplo, usa vetores de 3.072 dimensões. Os modelos de embedding de vetores densos usam métodos de aprendizado profundo semelhantes aos usados por modelos de linguagem grandes. Ao contrário dos vetores esparsos, que tendem a mapear diretamente as palavras para números, os vetores densos são projetados para representar melhor o significado de um texto. O benefício de usar embeddings de vetores densos na IA generativa é que, em vez de pesquisar correspondências de palavra direta ou sintaxe, é possível pesquisar melhor trechos que se alinhem ao significado da consulta, mesmo que os trechos não usem o mesmo idioma.

Os vetores são normalizados, então você pode usar a similaridade do cosseno, o produto escalar ou a distância euclidiana para fornecer as mesmas classificações de similaridade.

• Para saber mais sobre embeddings, consulte a visão geral das APIs de embeddings.
• Para saber mais sobre os modelos de embedding de texto, consulte Embeddings de texto.
• Para saber quais idiomas são aceitos em cada modelo de embeddings, consulte Idiomas de texto compatíveis.

Para conferir um exemplo de como receber embeddings de texto, execute o notebook "Introdução aos embeddings de texto + Vertex AI Vector Search" em um dos seguintes ambientes:

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

Antes de começar

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. Escolha um tipo de tarefa para o job de embeddings.

Limites da API

Há um limite de 250 textos de entrada em cada solicitação. A API tem um limite máximo de 20 mil tokens de entrada. Entradas que excedem esse limite resultam em um erro 400. Cada texto de entrada individual é limitado a 2.048 tokens. Qualquer excesso é truncado silenciosamente. É possível desativar o truncamento silencioso definindo autoTruncate como false.

Para mais informações, consulte Limites de embeddings de texto.

Obter embeddings de texto para um snippet de texto

É possível receber embeddings de texto para um snippet de texto usando a API Vertex AI ou o SDK da Vertex AI para Python.

Escolher uma dimensão de embedding

Todos os modelos produzem um vetor de embedding de comprimento total por padrão. Para gemini-embedding-001, esse vetor tem 3.072 dimensões, e outros modelos produzem vetores de 768 dimensões. No entanto, usando o parâmetro output_dimensionality, os usuários podem controlar o tamanho do vetor de incorporação de saída. Selecionar uma dimensionalidade de saída menor pode economizar espaço de armazenamento e aumentar a eficiência computacional para aplicativos downstream, com pouca perda em termos de qualidade.

Os exemplos a seguir usam o modelo gemini-embedding-001.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a 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

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a 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 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ê tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

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

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 gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login. Para saber qual é a conta ativa no momento, execute o comando 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": [ ... ]
      }
    }
  ]
}

Exemplo de 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 compatíveis

As tabelas a seguir mostram os modelos de embedding de texto aberto e do Google disponíveis.

Modelos do Google

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é 3.072	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.

Observação: use apenas os modelos listados na tabela de modelos compatíveis. Não especifique um modelo sem o sufixo @version ou @latest. Esses nomes de modelos não são considerados válidos.

Modelos abertos

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
multilingual-e5-small	Faz parte da família E5 de modelos de embedding de texto. A variante pequena contém 12 camadas.	Até 384	512 tokens	Idiomas disponíveis
multilingual-e5-large	Faz parte da família E5 de modelos de embedding de texto. A variante grande tem 24 camadas.	Até 1.024	512 tokens	Idiomas disponíveis

Para começar, consulte o card do modelo da família E5. Para mais informações sobre modelos abertos, consulte Modelos abertos para MaaS.

Adicionar um embedding a um banco de dados de vetores

Depois de gerar o embedding, é possível adicioná-lo a um banco de dados vetorial, como o Vector Search. Isso permite a recuperação de baixa latência e é essencial à medida que o tamanho dos dados aumenta.

Para saber mais sobre a pesquisa de vetor, consulte Visão geral da pesquisa de vetor.

A seguir

• Para saber mais sobre os limites de taxa, consulte Limites de taxa da IA generativa na Vertex AI.
• Para receber previsões em lote para embeddings, consulte Receber previsões de embeddings de texto em lote
  • Para saber mais sobre embeddings multimodais, consulte Acessar embeddings multimodais.
• Para ajustar um embedding, consulte Ajustar embeddings de texto.
• Para saber mais sobre a pesquisa relacionada a text-embedding-005 e text-multilingual-embedding-002, consulte o artigo de pesquisa Gecko: embeddings de texto versáteis extraídos de modelos de linguagem grandes.