Acessar incorporações de texto

A API Text-embeddings da Vertex AI permite criar um embedding de texto usando a IA generativa na Vertex AI. Os embeddings de texto são representações numéricas de texto que capturam as relações entre palavras e frases. Os modelos de machine learning, especialmente os de IA generativa, são adequados para criar esses embeddings identificando padrões em grandes conjuntos de dados de texto. O aplicativo pode usar embeddings de texto para processar e produzir linguagem, reconhecendo significados complexos e relações semânticas específicas do conteúdo. Você interage com embeddings de texto sempre que faz uma pesquisa no Google ou recebe recomendações de streaming de música.

Alguns casos de uso comuns para incorporações de texto incluem:

  • Pesquisa semântica: texto de pesquisa classificado por semelhança semântica.
  • Classificação: retorna a classe de itens com atributos de texto semelhantes ao texto fornecido.
  • Clustering: itens de cluster com atributos de texto semelhantes ao texto fornecido.
  • Detecção de outlier: retorna itens em que os atributos de texto estão menos relacionados ao texto fornecido.
  • Interface de conversa: agrupa grupos de frases que podem levar a respostas semelhantes, como em um espaço de incorporação no nível da conversa.

Os embeddings de texto funcionam convertendo texto em matrizes de números de ponto flutuante, chamadas de vetores. Esses vetores são projetados para capturar o significado do texto. O comprimento da matriz de embedding é chamado de dimensionalidade do vetor. Por exemplo, uma passagem de texto pode ser representada por um vetor com centenas de dimensões. Em seguida, ao calcular a distância numérica entre as representações vetoriais de duas partes de texto, um aplicativo pode determinar a semelhança entre os objetos.

A API Text embeddings da Vertex AI usa representações vetoriais densas: text-embedding-gecko, por exemplo, usa vetores de 768 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.

Pré-requisitos

Há pré-requisitos específicos para criar uma incorporação. Para começar, consulte o guia de início rápido: Testar embeddings de texto.

Use o Colab para chamar os modelos de incorporação de texto recém-lançados (textembedding-gecko e textembedding-gecko-multilingual).

Notebook Jupyter: chame os modelos de embedding de texto usando o Colab ou um notebook Jupyter.
Executar no Colab

Exemplo de caso de uso: desenvolver um chatbot de recomendação de livros

Se você quiser desenvolver um chatbot de recomendação de livros, a primeira coisa a fazer é usar uma rede neural profunda (DNN, na sigla em inglês) para converter cada livro em um vetor de embedding, em que um vetor de embedding representa um livro. É possível alimentar, como entrada da DNN, apenas o título do livro ou apenas o conteúdo do texto. Ou podemos usar ambos juntos, junto com outros metadados que descrevem o livro, como o gênero.

Os embeddings neste exemplo podem ser compostos por milhares de títulos de livros com resumos e gênero, e podem ter representações de livros como Wuthering Heights de Emily Brontë e Persuasion por Jane Austen que são semelhantes entre si (pequena distância entre a representação numérica). Já a representação numérica do livro Os Grandes Gatsby, de F. Scott Fitzgerald seria mais, porque o período, o gênero e o resumo são menos semelhantes.

As entradas são a principal influência na orientação do espaço de embedding. Por exemplo, se tivéssemos apenas entradas de título de livro, dois livros com títulos semelhantes, mas resumos muito diferentes, poderiam estar próximos. No entanto, se incluirmos o título e o resumo, esses mesmos livros serão menos semelhantes (mais distantes) no espaço de embedding.

Trabalhando com a IA generativa, esse bot de sugestão de livros pode resumir, sugerir e mostrar livros de que você pode gostar (ou não gostar), com base na sua consulta.

Modelos compatíveis

Para saber quais versões de modelos estáveis de embedding de texto estão disponíveis, consulte Versões de modelos estáveis disponíveis. Para saber quais versões de modelos mais recentes de embedding de texto estão disponíveis, consulte Modelos mais recentes.

É altamente recomendável especificar uma versão de modelo estável (por exemplo, textembedding-gecko@003). A versão mais recente de um modelo está em Pré-lançamento e não em disponibilidade geral (GA). Como a versão mais recente está em Pré-lançamento, não há garantia de que ela estará pronta para produção.

É especialmente importante usar uma versão de modelo estável (por exemplo, textembedding-gecko@003) para aplicativos que exigem embeddings compatíveis com versões anteriores. Se a compatibilidade com versões anteriores não for uma preocupação e você quiser usar a versão mais recente do modelo, especifique explicitamente @latest. Se nenhuma versão for especificada, o padrão de textembedding-gecko será textembedding-gecko@003 e o padrão de textembedding-gecko-multilingual será textembedding-gecko-multilingual@001.

Modelos mais recentes

Dois modelos estão disponíveis para visualização:

  • text-embedding-preview-0409
  • text-multilingual-embedding-preview-0409

Esses modelos são aprimorados em relação aos modelos anteriores em comparativos de mercado estabelecidos, abrangendo várias tarefas downstream, como recuperação e classificação. Para saber mais, consulte Gecko: embeddings de texto versáteis extraídos de modelos de linguagem grandes.

Esses modelos oferecem melhor qualidade de embedding do que os modelos textembedding-gecko@003 e textembedding-gecko-multilingual@001, respectivamente. Esses modelos não seguem a convenção de nomenclatura model-name@version. Especifique esses modelos sem o sufixo "@version". Veja um exemplo:

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/locations/us-central1/publishers/google/models/text-embedding-preview-0409:predict -d $'{
  "instances": [
    { "content": "What is life?"}
  ],
}'

Além da qualidade aprimorada, os novos modelos oferecem suporte aos seguintes recursos:

  • Há suporte para um novo parâmetro outputDimensionality. É possível usar esse parâmetro para reduzir o tamanho da incorporação, por exemplo, para otimizar o armazenamento.

    • QUESTION_ANSWERING
    • FACT_VERIFICATION

    Dois novos tipos de tarefa são compatíveis. Para conferir mais tipos de tarefas, consulte a referência de modelo.

O exemplo a seguir demonstra os novos recursos:

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/locations/us-central1/publishers/google/models/text-embedding-preview-0409:predict -d $'{
  "instances": [
    {
      "task_type": "QUESTION_ANSWERING",
      "content": "What is life?"
    }
  ],
"parameters": {
    "outputDimensionality": 256
  }
}'

As limitações a seguir se aplicam ao uso desses modelos:

  • Não use esses modelos de visualização em sistemas de produção ou de missão crítica.
  • Esses modelos estão disponíveis apenas em us-central1.
  • As previsões em lote não são compatíveis.
  • Não é possível personalizar.

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. Para cada solicitação, há um limite de 250 textos de entrada em us-central1. Em outras regiões, o texto de entrada máximo é 5. Cada texto de entrada tem um limite de tokens de 3.072. As entradas mais longas que esse comprimento são silenciosamente truncadas. É possível desativar o truncamento silencioso definindo autoTruncate como false.

Estes exemplos usam o modelo textembedding-gecko@003.

REST

Para receber embeddings de texto, envie uma solicitação POST especificando o ID do modelo do editor.

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 com até 3.072 tokens por 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/textembedding-gecko@003: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 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/textembedding-gecko@003: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/textembedding-gecko@003: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="textembedding-gecko@003"
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?"}
  ],
}'

Python

Para saber como instalar ou atualizar o Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 

from typing import List

from vertexai.language_models import TextEmbeddingInput, TextEmbeddingModel

def embed_text(
    texts: List[str] = ["banana muffins? ", "banana bread? banana muffins?"],
    task: str = "RETRIEVAL_DOCUMENT",
    model_name: str = "textembedding-gecko@003",
) -> List[List[float]]:
    """Embeds texts with a pre-trained, foundational model."""
    model = TextEmbeddingModel.from_pretrained(model_name)
    inputs = [TextEmbeddingInput(text, task) for text in texts]
    embeddings = model.get_embeddings(inputs)
    return [embedding.values for embedding in embeddings]

Go

Antes de testar essa amostra, siga as instruções de configuração para Go Guia de início rápido da Vertex AI: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Go.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

import (
	"context"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1beta1"
	"cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb"
	"google.golang.org/api/option"
	"google.golang.org/protobuf/types/known/structpb"
)

// generateEmbeddings creates embeddings from text provided.
func generateEmbeddings(w io.Writer, prompt, project, location, publisher, model string) error {
	ctx := context.Background()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)

	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		fmt.Fprintf(w, "unable to create prediction client: %v", err)
		return err
	}
	defer client.Close()

	// PredictRequest requires an endpoint, instances, and parameters
	// Endpoint
	base := fmt.Sprintf("projects/%s/locations/%s/publishers/%s/models", project, location, publisher)
	url := fmt.Sprintf("%s/%s", base, model)

	// Instances: the prompt
	promptValue, err := structpb.NewValue(map[string]interface{}{
		"content": prompt,
	})
	if err != nil {
		fmt.Fprintf(w, "unable to convert prompt to Value: %v", err)
		return err
	}

	// PredictRequest: create the model prediction request
	req := &aiplatformpb.PredictRequest{
		Endpoint:  url,
		Instances: []*structpb.Value{promptValue},
	}

	// PredictResponse: receive the response from the model
	resp, err := client.Predict(ctx, req)
	if err != nil {
		fmt.Fprintf(w, "error in prediction: %v", err)
		return err
	}

	fmt.Fprintf(w, "embeddings generated: %v", resp.Predictions[0])
	return nil
}

Java

Antes de testar essa amostra, siga as instruções de configuração para Java Guia de início rápido da Vertex AI: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

import static java.util.stream.Collectors.toList;

import com.google.cloud.aiplatform.v1beta1.EndpointName;
import com.google.cloud.aiplatform.v1beta1.PredictRequest;
import com.google.cloud.aiplatform.v1beta1.PredictResponse;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1beta1.PredictionServiceSettings;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class PredictTextEmbeddingsSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Details about text embedding request structure and supported models are available in:
    // https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    String project = "YOUR_PROJECT_ID";
    String model = "textembedding-gecko@003";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "RETRIEVAL_DOCUMENT");
  }

  // Gets text embeddings from a pretrained, foundational model.
  public static List<List<Float>> predictTextEmbeddings(
      String endpoint, String project, String model, List<String> texts, String task)
      throws IOException {
    PredictionServiceSettings settings =
        PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build();
    Matcher matcher = Pattern.compile("^(?<Location>\\w+-\\w+)").matcher(endpoint);
    String location = matcher.matches() ? matcher.group("Location") : "us-central1";
    EndpointName endpointName =
        EndpointName.ofProjectLocationPublisherModelName(project, location, "google", model);

    // You can use this prediction service client for multiple requests.
    try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
      PredictRequest.Builder request =
          PredictRequest.newBuilder().setEndpoint(endpointName.toString());
      for (int i = 0; i < texts.size(); i++) {
        request.addInstances(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("content", valueOf(texts.get(i)))
                        .putFields("taskType", valueOf(task))
                        .build()));
      }
      PredictResponse response = client.predict(request.build());
      List<List<Float>> floats = new ArrayList<>();
      for (Value prediction : response.getPredictionsList()) {
        Value embeddings = prediction.getStructValue().getFieldsOrThrow("embeddings");
        Value values = embeddings.getStructValue().getFieldsOrThrow("values");
        floats.add(
            values.getListValue().getValuesList().stream()
                .map(Value::getNumberValue)
                .map(Double::floatValue)
                .collect(toList()));
      }
      return floats;
    }
  }

  private static Value valueOf(String s) {
    return Value.newBuilder().setStringValue(s).build();
  }
}

Node.js

Antes de testar essa amostra, siga as instruções de configuração para Node.js Guia de início rápido da Vertex AI: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

async function main(
  project,
  model = 'textembedding-gecko@003',
  texts = 'banana bread?;banana muffins?',
  task = 'RETRIEVAL_DOCUMENT',
  apiEndpoint = 'us-central1-aiplatform.googleapis.com'
) {
  const aiplatform = require('@google-cloud/aiplatform');
  const {PredictionServiceClient} = aiplatform.v1;
  const {helpers} = aiplatform; // helps construct protobuf.Value objects.
  const clientOptions = {apiEndpoint: apiEndpoint};
  const match = apiEndpoint.match(/(?<Location>\w+-\w+)/);
  const location = match ? match.groups.Location : 'us-centra11';
  const endpoint = `projects/${project}/locations/${location}/publishers/google/models/${model}`;

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, taskType: task}));
    const request = {endpoint, instances};
    const client = new PredictionServiceClient(clientOptions);
    const [response] = await client.predict(request);
    console.log('Got predict response');
    const predictions = response.predictions;
    for (const prediction of predictions) {
      const embeddings = prediction.structValue.fields.embeddings;
      const values = embeddings.structValue.fields.values.listValue.values;
      console.log('Got prediction: ' + JSON.stringify(values));
    }
  }

  callPredict();
}

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.

Mudanças da API nos modelos lançados a partir de agosto de 2023

Ao usar versões de modelo lançadas a partir de agosto de 2023, incluindo textembedding-gecko@003 e textembedding-gecko-multilingual@001, há um novo parâmetro de tipo de tarefa e o título opcional (válido somente com task_type=RETRIEVAL_DOCUMENT).

Esses novos parâmetros serão aplicados a esses modelos de pré-lançamento público e a todos os modelos estáveis a partir de agora.

{
  "instances": [
    {
      "task_type": "RETRIEVAL_DOCUMENT",
      "title": "document title",
      "content": "I would like embeddings for this text!"
    },
  ]
}

O parâmetro task_type é definido como o aplicativo downstream pretendido para ajudar o modelo a produzir embeddings de melhor qualidade. É uma string que pode assumir um dos seguintes valores:

task_type Descrição
RETRIEVAL_QUERY Especifica que o texto é uma consulta em uma configuração de pesquisa ou recuperação.
RETRIEVAL_DOCUMENT Especifica que o texto é um documento em uma configuração de pesquisa ou recuperação.
SEMANTIC_SIMILARITY Especifica que o texto fornecido é usado para Similaridade Textual Semântica (STS).
CLASSIFICATION Especifica que o embedding é usado para classificação.
CLUSTERING Especifica que o embedding é usado para clustering.
QUESTION_ANSWERING Especifica que o embedding de consulta é usado para responder a perguntas. Use RETRIEVAL_DOCUMENT para o documento.
FACT_VERIFICATION Especifica que o embedding de consulta é usado para a verificação de fatos.

Cobertura de idiomas para modelos textembedding-gecko-multilingual.

O modelo textembedding-gecko-multilingual@001 foi avaliado nas seguintes linguagens: Arabic (ar), Bengali (bn), English (en), Spanish (es), German (de), Persian (fa), Finnish (fi), French (fr), Hindi (hi), Indonesian (id), Japanese (ja), Korean (ko), Russian (ru), Swahili (sw), Telugu (te), Thai (th), Yoruba (yo), Chinese (zh).

Esta é a lista completa de idiomas compatíveis: Afrikaans, Albanian, Amharic, Arabic, Armenian, Azerbaijani, Basque e Belarusian, Bengali, Bulgarian, Burmese, Catalan, Cebuano, Chichewa, Chinese, Corsican, Czech e Danish, Dutch, English, Esperanto, Estonian, Filipino, Finnish, French, Galician, Georgian e German, Greek, Gujarati, Haitian Creole, Hausa, Hawaiian, Hebrew, Hindi, Hmong, Hungarian e Icelandic, Igbo, Indonesian, Irish, Italian, Japanese, Javanese, Kannada, Kazakh, Khmer e Korean, Kurdish, Kyrgyz, Lao, Latin, Latvian, Lithuanian, Luxembourgish, Macedonian, Malagasy e Malay, Malayalam, Maltese, Maori, Marathi, Mongolian, Nepali, Norwegian, Pashto, Persian e Polish, Portuguese, Punjabi, Romanian, Russian, Samoan, Scottish Gaelic, Serbian, Shona, Sindhi e Sinhala, Slovak, Slovenian, Somali, Sotho, Spanish, Sundanese, Swahili, Swedish, Tajik e Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Uzbek, Vietnamese, Welsh, West Frisian e Xhosa, Yiddish, Yoruba e Zulu.

A seguir