Acessar incorporações de texto

Este documento descreve como criar um embedding de texto usando a Gemini Enterprise Agent Platform API Text embeddings.

A API Text embeddings da Gemini Enterprise Agent Platform 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 usam o mesmo idioma.

Os vetores são normalizados, então você pode usar a similaridade de 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 conseguir embeddings de texto, execute o "Introdução aos embeddings de texto + busca vetorial da Agent Platform" notebook em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Agent Platform Workbench | Conferir no GitHub

Antes de começar

Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

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.

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 Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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.

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 Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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. Também é possível desativar o truncamento silencioso definindo autoTruncate como false.

Para mais informações, consulte Limites de embedding 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 da Agent Platform ou o SDK da Agent Platform 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, ao usar o parâmetro output_dimensionality, os usuários podem controlar o tamanho do vetor de embedding 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, sacrificando pouco em termos de qualidade.

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

Python

Instalar

pip install --upgrade google-genai

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

Defina variáveis de ambiente para usar o SDK de IA Generativa do Google 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_ENTERPRISE=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 mais informações, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA Generativa do Google 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_ENTERPRISE=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 mais informações, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA Generativa do Google 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_ENTERPRISE=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

Saiba como instalar ou atualizar o Java.

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

Defina variáveis de ambiente para usar o SDK de IA Generativa do Google 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_ENTERPRISE=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 os dados da solicitação abaixo, faça estas substituições:

• PROJECT_ID: seu [ID do projeto](/resource-manager/docs/creating-managing-projects#identifiers). .
• TEXT: o texto ao qual você quer gerar embeddings para. 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 único texto de entrada. Para mais informações, consulte Limites de embedding 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ê fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

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

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 CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando 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 abertos 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 última geração 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 código.	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 embedding superior, gemini-embedding-001 é nosso modelo grande projetado para oferecer o maior desempenho.

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	Parte da família de modelos de embedding de texto E5. A variante pequena contém 12 camadas.	Até 384	512 tokens	Idiomas com suporte
multilingual-e5-large	Parte da família de modelos de embedding de texto E5. A variante grande contém 24 camadas.	Até 1024	512 tokens	Idiomas com suporte

Para começar, consulte o card do modelo da família E5 model card. 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 busca vetorial, consulte Visão geral da busca vetorial.

A seguir

• Para saber mais sobre os limites de taxa, consulte Agent Platform cotas e limites do sistema.
• 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 Ver 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.