Obtenha incorporações de texto

Este documento descreve como criar uma incorporação de texto através da API Text embeddingsda Vertex AI.

A API Vertex AI Text Embeddings usa representações vetoriais densas: gemini-embedding-001, por exemplo, usa vetores de 3072 dimensões. Os modelos de incorporação de vetores densos usam métodos de aprendizagem profunda semelhantes aos usados pelos modelos de linguagem (conteúdo extenso). Ao contrário dos vetores esparsos, que tendem a mapear diretamente palavras para números, os vetores densos são concebidos para representar melhor o significado de um fragmento de texto. A vantagem de usar incorporações de vetores densos na IA generativa é que, em vez de pesquisar correspondências diretas de palavras ou sintaxe, pode pesquisar melhor passagens que se alinham com o significado da consulta, mesmo que as passagens não usem o mesmo idioma.

Os vetores são normalizados, pelo que pode usar a semelhança de cossenos, o produto escalar ou a distância euclidiana para fornecer as mesmas classificações de semelhança.

• Para saber mais sobre as incorporações, consulte a vista geral das APIs de incorporações.
• Para saber mais sobre os modelos de incorporação de texto, consulte o artigo Incorporações de texto.
• Para informações sobre os idiomas que cada modelo de incorporações suporta, consulte os idiomas de texto suportados.

Para ver um exemplo de como obter incorporações de texto, execute o bloco de notas "Introdução às incorporações de texto + pesquisa vetorial do Vertex AI" num 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 a sua tarefa de incorporações.

Limites da API

Para cada pedido, está limitado a 250 textos de entrada. A API tem um limite máximo de tokens de entrada de 20 000. As entradas que excedem este limite resultam num erro 400. Cada texto de entrada individual está ainda limitado a 2048 tokens. Qualquer excesso é truncado de forma silenciosa. Também pode desativar a truncagem silenciosa definindo autoTruncate como false.

Para mais informações, consulte os limites de incorporação de texto.

Obtenha incorporações de texto para um fragmento de texto

Pode obter incorporações de texto para um fragmento de texto através da API Vertex AI ou do SDK Vertex AI para Python.

Escolha uma dimensão de incorporação

Por predefinição, todos os modelos produzem um vetor de incorporação de comprimento total. Para gemini-embedding-001, este vetor tem 3072 dimensões e outros modelos produzem vetores de 768 dimensões. No entanto, através do parâmetro output_dimensionality, os utilizadores podem controlar o tamanho do vetor de incorporação de saída. Selecionar uma dimensionalidade de saída mais pequena pode poupar espaço de armazenamento e aumentar a eficiência computacional para aplicações posteriores, sacrificando pouco em termos de qualidade.

Os exemplos seguintes usam o modelo gemini-embedding-001.

Python

Instalação

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 gen com o 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 gen com o 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 qualquer um dos dados do pedido, faça as seguintes substituições:

• PROJECT_ID: o seu ID do projeto.
• TEXT: o texto para o qual quer gerar incorporações. Limite: cinco textos de até 2048 tokens por texto para todos os modelos,exceto o textembedding-gecko@001. O comprimento máximo do token de entrada para textembedding-gecko@001 é de 3072. Para o gemini-embedding-001, cada pedido só pode incluir um único texto de entrada. Para mais informações, consulte os limites de incorporação de texto.
• AUTO_TRUNCATE: se estiver definido como false, o texto que exceda o limite de tokens faz com que o pedido falhe. O valor predefinido é 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 do pedido:

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Deve receber uma resposta JSON semelhante à seguinte. Tenha em atenção que values foi truncado para poupar espaço.

Resposta

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

Comando curl de exemplo

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 suportados

As tabelas seguintes mostram os modelos de incorporação de texto abertos e da Google disponíveis.

Modelos Google

Pode obter incorporações de texto através dos seguintes modelos:

Nome do modelo	Descrição	Dimensões de saída	Duração máxima da sequência	Idiomas de texto suportados
gemini-embedding-001	Desempenho de última geração em tarefas em inglês, multilingues e de código. Unifica os modelos especializados anteriormente, como text-embedding-005 e text-multilingual-embedding-002, e alcança um melhor desempenho nos respetivos domínios. Leia o nosso relatório técnico para ver mais detalhes.	até 3072	2048 tokens	Idiomas de texto suportados
text-embedding-005	Especializado em tarefas de inglês e código.	até 768	2048 tokens	Inglês
text-multilingual-embedding-002	Especializado em tarefas multilingues.	até 768	2048 tokens	Idiomas de texto suportados

Para uma qualidade de incorporação superior, o gemini-embedding-001 é o nosso modelo grande concebido para oferecer o desempenho mais elevado.

Nota: use apenas os modelos indicados na tabela de modelos suportados. Não especifique um modelo sem o sufixo @version ou @latest. Estes nomes de modelos não são considerados válidos.

Abrir modelos

Pode obter incorporações de texto através dos seguintes modelos:

Nome do modelo	Descrição	Dimensões de saída	Duração máxima da sequência	Idiomas de texto suportados
multilingual-e5-small	Parte da família de modelos de incorporação de texto E5. A variante pequena contém 12 camadas.	Até 384	512 tokens	Idiomas suportados
multilingual-e5-large	Parte da família de modelos de incorporação de texto E5. A variante grande contém 24 camadas.	Até 1024	512 tokens	Idiomas suportados

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

Adicione uma incorporação a uma base de dados vetorial

Depois de gerar a incorporação, pode adicioná-las a uma base de dados vetorial, como a pesquisa vetorial. Isto permite uma obtenção de baixa latência e é fundamental à medida que o tamanho dos seus dados aumenta.

Para saber mais sobre a Vector Search, consulte a Vista geral da Vector Search.

O que se segue?

• Para saber mais sobre os limites de taxa, consulte os limites de taxa da IA generativa no Vertex AI.
• Para obter previsões em lote para incorporações, consulte o artigo Obtenha previsões de incorporações de texto em lote
  • Para saber mais sobre as incorporações multimodais, consulte o artigo Obtenha incorporações multimodais
• Para ajustar uma incorporação, consulte o artigo Ajuste as incorporações de texto
• Para saber mais sobre a investigação por detrás do text-embedding-005 e do text-multilingual-embedding-002, consulte o artigo de investigação Gecko: Versatile Text Embeddings Distilled from Large Language Models.