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: 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.
- Para saber mais sobre embeddings, consulte 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.
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.
-
Enable the Vertex AI API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Enable the Vertex AI API.
- Escolha um tipo de tarefa para o job de embeddings.
Modelos compatíveis
Você pode obter embeddings de texto usando os seguintes modelos:
Modelos em inglês | Modelos multilíngues |
---|---|
textembedding-gecko@001 |
textembedding-gecko-multilingual@001 |
textembedding-gecko@003 |
text-multilingual-embedding-002 |
text-embedding-004 |
|
text-embedding-preview-0815 |
Se você não tem familiaridade com esses modelos, recomendamos usar as versões mais recentes.
Para textos em inglês, use text-embedding-004
. Para textos multilíngues, use
text-multilingual-embedding-002
.
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.
A API tem um limite máximo de 20 mil tokens de entrada. Entradas que excedem esse limite
resultam em um erro 500. Cada texto de entrada individual é limitado a
2.048 tokens. Qualquer excesso é truncado silenciosamente. É possível desativar o truncamento
silencioso definindo autoTruncate
como false
.
Todos os modelos produzem uma saída com 768 dimensões por padrão. No entanto, os modelos a seguir dão aos usuários a opção de escolher uma dimensionalidade de saída entre 1 e 768. Ao selecionar uma dimensionalidade de saída menor, os usuários economizam memória e espaço de armazenamento, o que gera cálculos mais eficientes.
text-embedding-004
text-multilingual-embedding-002
text-embedding-preview-0815
Os exemplos a seguir usam o modelo text-embedding-004
.
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 de até 2.048 tokens por texto para todos os modelos, exceto
textembedding-gecko@001
. O comprimento máximo do token de entrada paratextembedding-gecko@001
é 3.072. - 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/text-embedding-004: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/text-embedding-004: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/text-embedding-004: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="text-embedding-004"
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 o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.
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.
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.
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.
Modelo mais recente
Há um modelo de embeddings disponível no pré-lançamento:
text-embedding-preview-0815
Esse modelo dá suporte a um novo tipo de tarefa CODE_RETRIEVAL_QUERY
, que pode ser usado para
recuperar blocos de código relevantes usando consultas de texto simples. Para usar esse recurso, os blocos de
código devem ser incorporados com o tipo de tarefa RETRIEVAL_DOCUMENT
,
enquanto as consultas
de texto devem ser incorporadas com CODE_RETRIEVAL_QUERY
.
Para conferir todos os tipos de tarefas, consulte a referência do modelo.
Veja um exemplo:
REST
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/text-embedding-preview-0815:predict -d \
$'{
"instances": [
{
"task_type": "CODE_RETRIEVAL_QUERY",
"content": "Function to add two numbers"
}
],
}'
Python
Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.
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.
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.
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.
As limitações a seguir se aplicam ao uso desses modelos:
- Não use esses modelos de pré-lançamento em sistemas críticos ou de produção.
- 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.
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 Ver embeddings multimodais.
- Para ajustar um embedding, consulte Ajustar embeddings de texto.
- Para saber mais sobre a pesquisa relacionada a
text-embedding-004
etext-multilingual-embedding-002
, consulte o artigo de pesquisa Gecko: embeddings de texto versáteis extraídos de modelos de linguagem grandes.