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.

Antes de começar

  1. 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.
  2. 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.

    Go to project selector

  3. 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

  4. 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.

    Go to project selector

  5. 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

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

    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

    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.

    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.

    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