Esta página foi traduzida pela API Cloud Translation.

Gere incorporações de texto com a função ML.GENERATE_EMBEDDING

Este documento mostra como criar um modelo remoto do BigQuery ML que faz referência a um modelo de incorporação. Em seguida, usa esse modelo com a função ML.GENERATE_EMBEDDING para criar incorporações de texto com dados de uma tabela padrão do BigQuery.

São suportados os seguintes tipos de modelos remotos:

Modelos remotos sobre modelos de incorporação do Vertex AI.
Modelos remotos sobre modelos abertos suportados (Pré-visualização).

Funções necessárias

Para criar um modelo remoto e usar a função ML.GENERATE_EMBEDDING, precisa das seguintes funções de gestão de identidade e de acesso (IAM):

Criar e usar conjuntos de dados, tabelas e modelos do BigQuery: Editor de dados do BigQuery (roles/bigquery.dataEditor) no seu projeto.
Criar, delegar e usar associações do BigQuery: administrador de associações do BigQuery (roles/bigquery.connectionsAdmin) no seu projeto.

Se não tiver uma associação predefinida configurada, pode criar e definir uma como parte da execução da declaração CREATE MODEL. Para tal, tem de ter a função de administrador do BigQuery (roles/bigquery.admin) no seu projeto. Para mais informações, consulte o artigo Configure a ligação predefinida.
Conceda autorizações à conta de serviço da ligação: administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto que contém o ponto final do Vertex AI. Este é o projeto atual para modelos remotos que cria especificando o nome do modelo como um ponto final. Este é o projeto identificado no URL para modelos remotos que cria especificando um URL como ponto final.
Criar tarefas do BigQuery: utilizador de tarefas do BigQuery (roles/bigquery.jobUser) no seu projeto.

Estas funções predefinidas contêm as autorizações necessárias para realizar as tarefas descritas neste documento. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

Crie um conjunto de dados: bigquery.datasets.create
Crie, delegue e use uma associação: bigquery.connections.*
Defina as autorizações da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
Crie um modelo e execute a inferência:
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata
Consultar dados de tabelas: bigquery.tables.getData

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Antes de começar

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
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
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 APIs

Crie um conjunto de dados

Crie um conjunto de dados do BigQuery para conter os seus recursos:

Consola

Na Google Cloud consola, aceda à página BigQuery.

Aceda ao BigQuery
No painel esquerdo, clique em Explorador:

Se não vir o painel do lado esquerdo, clique em Expandir painel do lado esquerdo para o abrir.
No painel Explorador, clique no nome do projeto.
Clique em Ver ações > Criar conjunto de dados.
Na página Criar conjunto de dados, faça o seguinte:
1. Para ID do conjunto de dados, escreva um nome para o conjunto de dados.
2. Para Tipo de localização, selecione Região ou Várias regiões.
  - Se selecionou Região, selecione uma localização na lista Região.
  - Se selecionou Multirregional, selecione EUA ou Europa na lista Multirregional.
3. Clique em Criar conjunto de dados.

bq

Para criar um novo conjunto de dados, use o comando bq mk com a flag --location:
```
bq --location=LOCATION mk -d DATASET_ID
```
Substitua o seguinte:
- LOCATION: a localização do conjunto de dados.
- DATASET_ID é o ID do conjunto de dados que está a criar.
Confirme que o conjunto de dados foi criado:
```
bq ls
```

Crie uma associação

Pode ignorar este passo se tiver uma associação predefinida configurada ou tiver a função de administrador do BigQuery.

Crie uma ligação de recursos da nuvem para o modelo remoto usar e obtenha a conta de serviço da ligação. Crie a associação na mesma localização que o conjunto de dados que criou no passo anterior.

Selecione uma das seguintes opções:

Consola

Aceda à página do BigQuery.

Aceda ao BigQuery
No painel Explorador, clique em Adicionar dados:

É apresentada a caixa de diálogo Adicionar dados.
No painel Filtrar por, na secção Tipo de origem de dados, selecione Aplicações empresariais.

Em alternativa, no campo Pesquisar origens de dados, pode introduzir Vertex AI.
Na secção Origens de dados em destaque, clique em Vertex AI.
Clique no cartão da solução Modelos da Vertex AI: federação do BigQuery.
Na lista Tipo de ligação, selecione Modelos remotos, funções remotas, BigLake e Spanner (recurso da nuvem) da Vertex AI.
No campo ID da associação, introduza um nome para a associação.
Clique em Criar associação.
Clique em Aceder à associação.
No painel Informações de associação, copie o ID da conta de serviço para utilização num passo posterior.

bq

Num ambiente de linha de comandos, crie uma associação:
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
O parâmetro --project_id substitui o projeto predefinido.

Substitua o seguinte:
- REGION: a sua região de ligação
- PROJECT_ID: o ID do seu Google Cloud projeto
- CONNECTION_ID: um ID para a sua ligação
Quando cria um recurso de ligação, o BigQuery cria uma conta de serviço do sistema única e associa-a à ligação.

Resolução de problemas: se receber o seguinte erro de ligação, atualize o SDK do Google Cloud:
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

Recupere e copie o ID da conta de serviço para utilização num passo posterior:

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

O resultado é semelhante ao seguinte:

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Use o recurso google_bigquery_connection.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

O exemplo seguinte cria uma associação de recursos da nuvem com o nome my_cloud_resource_connection na região US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar a configuração do Terraform num Google Cloud projeto, conclua os passos nas secções seguintes.

Prepare o Cloud Shell

Inicie o Cloud Shell.
Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

Prepare o diretório

Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

Copie o exemplo de código para o ficheiro main.tf criado recentemente.

Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.
Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
Guarde as alterações.
Inicialize o Terraform. Só tem de fazer isto uma vez por diretório.
```
terraform init
```
Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade:
```
terraform init -upgrade
```

Aplique as alterações

Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas:
```
terraform plan
```
Faça correções à configuração conforme necessário.
Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando:
```
terraform apply
```
Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).
Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

Conceda uma função à conta de serviço da ligação do modelo remoto

Tem de conceder à conta de serviço da ligação a função de utilizador do Vertex AI.

Se planeia especificar o ponto final como um URL quando criar o modelo remoto, por exemplo endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-005', conceda esta função no mesmo projeto que especificar no URL.

Se planear especificar o ponto final através do nome do modelo quando criar o modelo remoto, por exemplo, endpoint = 'text-embedding-005', conceda esta função no mesmo projeto onde planeia criar o modelo remoto.

A concessão da função num projeto diferente resulta no erro bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Para conceder a função, siga estes passos:

Consola

Aceda à página IAM e administrador.

Aceda a IAM e administração
Clique em Conceder acesso.

É apresentada a caixa de diálogo Adicionar responsáveis.
No campo Novos membros, introduza o ID da conta de serviço que copiou anteriormente.
No campo Selecionar uma função, selecione Vertex AI e, de seguida, selecione Utilizador da Vertex AI.
Clique em Guardar.

gcloud

Use o comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Substitua o seguinte:

PROJECT_NUMBER: o número do seu projeto
MEMBER: o ID da conta de serviço que copiou anteriormente

Escolha um método de implementação de modelo aberto

Se estiver a criar um modelo remoto sobre um modelo aberto suportado, pode implementar automaticamente o modelo aberto ao mesmo tempo que cria o modelo remoto especificando o ID do modelo do Vertex AI Model Garden ou do Hugging Face na declaração CREATE MODEL. Em alternativa, pode implementar manualmente o modelo aberto primeiro e, em seguida, usar esse modelo aberto com o modelo remoto especificando o ponto final do modelo na declaração CREATE MODEL. Para mais informações, consulte o artigo Implemente modelos abertos.

Crie um modelo remoto do BigQuery ML

Crie um modelo remoto:

Novos modelos abertos

Na Google Cloud consola, aceda à página BigQuery.

Aceda ao BigQuery
Usando o editor de SQL, crie um modelo remoto:
```
CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  {HUGGING_FACE_MODEL_ID = 'HUGGING_FACE_MODEL_ID' |
     MODEL_GARDEN_MODEL_NAME = 'MODEL_GARDEN_MODEL_NAME'}
  [, HUGGING_FACE_TOKEN = 'HUGGING_FACE_TOKEN' ]
  [, MACHINE_TYPE = 'MACHINE_TYPE' ]
  [, MIN_REPLICA_COUNT = MIN_REPLICA_COUNT ]
  [, MAX_REPLICA_COUNT = MAX_REPLICA_COUNT ]
  [, RESERVATION_AFFINITY_TYPE = {'NO_RESERVATION' | 'ANY_RESERVATION' | 'SPECIFIC_RESERVATION'} ]
  [, RESERVATION_AFFINITY_KEY = 'compute.googleapis.com/reservation-name' ]
  [, RESERVATION_AFFINITY_VALUES = RESERVATION_AFFINITY_VALUES ]
  [, ENDPOINT_IDLE_TTL = ENDPOINT_IDLE_TTL ]
);
```
Substitua o seguinte:
- PROJECT_ID: o ID do seu projeto.
- DATASET_ID: o ID do conjunto de dados que vai conter o modelo. Este conjunto de dados tem de estar na mesma localização que a ligação que está a usar.
- MODEL_NAME: o nome do modelo.
- REGION: a região usada pela ligação.
- CONNECTION_ID: o ID da sua ligação ao BigQuery.
  Pode obter este valor vendo os detalhes da associação na Google Cloud consola e copiando o valor na última secção do ID de associação totalmente qualificado apresentado em ID de associação. Por exemplo, projects/myproject/locations/connection_location/connections/myconnection.
- HUGGING_FACE_MODEL_ID: um valor STRING que especifica o ID do modelo para um modelo do Hugging Face suportado, no formato provider_name/model_name. Por exemplo, deepseek-ai/DeepSeek-R1. Pode obter o ID do modelo clicando no nome do modelo no Hugging Face Model Hub e, em seguida, copiando o ID do modelo na parte superior do cartão do modelo.
- MODEL_GARDEN_MODEL_NAME: um valor STRING que especifica o ID do modelo e a versão do modelo de um modelo do Model Garden da Vertex AI suportado, no formato publishers/publisher/models/model_name@model_version. Por exemplo, publishers/openai/models/gpt-oss@gpt-oss-120b. Pode obter o ID do modelo clicando no cartão do modelo no Vertex AI Model Garden e, de seguida, copiando o ID do modelo do campo ID do modelo. Pode obter a versão do modelo predefinido copiando-a do campo Versão no cartão do modelo. Para ver outras versões do modelo que pode usar, clique em Implementar modelo e, de seguida, clique no campo ID do recurso.
- HUGGING_FACE_TOKEN: um valor STRING que especifica o token de acesso do utilizador do Hugging Face a usar. Só pode especificar um valor para esta opção se também especificar um valor para a opção HUGGING_FACE_MODEL_ID.
  O token tem de ter, no mínimo, a função read, mas também são aceitáveis tokens com um âmbito mais amplo. Esta opção é obrigatória quando o modelo identificado pelo valor HUGGING_FACE_MODEL_ID é um modelo restrito ou privado da Hugging Face.
  
  Alguns modelos restritos requerem a aceitação explícita dos respetivos termos de serviço antes de ser concedido o acesso. Para aceitar estes termos, siga estes passos:
  1. Navegue para a página do modelo no Website da Hugging Face.
  2. Localize e reveja os termos de utilização do modelo. Normalmente, encontra um link para o contrato de serviço no cartão do modelo.
  3. Aceite os termos conforme indicado na página.
- MACHINE_TYPE: um valor STRING que especifica o tipo de máquina a usar quando implementar o modelo na Vertex AI. Para obter informações sobre os tipos de máquinas compatíveis, consulte o artigo Tipos de máquinas. Se não especificar um valor para a opção MACHINE_TYPE, é usado o tipo de máquina predefinido do Vertex AI Model Garden para o modelo.
- MIN_REPLICA_COUNT: um valor INT64 que especifica o número mínimo de réplicas de máquinas usadas quando implementa o modelo num ponto final do Vertex AI. O serviço aumenta ou diminui o número de réplicas conforme necessário pela carga de inferência no ponto final. O número de réplicas usadas nunca é inferior ao valor de MIN_REPLICA_COUNT e nunca é superior ao valor de MAX_REPLICA_COUNT. O valor MIN_REPLICA_COUNT tem de estar no intervalo [1, 4096]. O valor predefinido é 1.
- MAX_REPLICA_COUNT: um valor INT64 que especifica o número máximo de réplicas de máquinas usadas quando implementa o modelo num ponto final do Vertex AI. O serviço aumenta ou diminui o número de réplicas conforme necessário pela carga de inferência no ponto final. O número de réplicas usadas nunca é inferior ao valor de MIN_REPLICA_COUNT e nunca é superior ao valor de MAX_REPLICA_COUNT. O valor MAX_REPLICA_COUNT tem de estar no intervalo [1, 4096]. O valor predefinido é o valor MIN_REPLICA_COUNT.
- RESERVATION_AFFINITY_TYPE: determina se o modelo implementado usa reservas do Compute Engine para fornecer disponibilidade garantida de máquinas virtuais (VMs) quando fornece previsões e especifica se o modelo usa VMs de todas as reservas disponíveis ou apenas de uma reserva específica. Para mais informações, consulte Afinidade de reserva do Compute Engine.
  Só pode usar reservas do Compute Engine partilhadas com o Vertex AI. Para mais informações, consulte o artigo Permita que uma reserva seja consumida.
  
  Os valores suportados são os seguintes:
  - NO_RESERVATION: não é consumida nenhuma reserva quando o seu modelo é implementado num ponto final do Vertex AI. Especificar NO_RESERVATION tem o mesmo efeito que não especificar uma afinidade de reserva.
  - ANY_RESERVATION: a implementação do modelo do Vertex AI consome máquinas virtuais (VMs) de reservas do Compute Engine que estão no projeto atual ou que são partilhadas com o projeto e que estão configuradas para consumo automático. Apenas são usadas VMs que cumprem as seguintes qualificações:
    - Usam o tipo de máquina especificado pelo valor MACHINE_TYPE.
    - Se o conjunto de dados do BigQuery no qual está a criar o modelo remoto for uma única região, a reserva tem de estar na mesma região. Se o conjunto de dados estiver na multirregião US, a reserva tem de estar na região us-central1. Se o conjunto de dados estiver na EU região múltipla, a reserva tem de estar na europe-west4 região.
    Se não existir capacidade suficiente nas reservas disponíveis ou se não forem encontradas reservas adequadas, o sistema aprovisiona VMs do Compute Engine a pedido para satisfazer os requisitos de recursos.
  - SPECIFIC_RESERVATION: a implementação do modelo do Vertex AI consome VMs apenas da reserva que especificar no valor RESERVATION_AFFINITY_VALUES. Esta reserva tem de ser configurada para um consumo especificamente segmentado. A implementação falha se a reserva especificada não tiver capacidade suficiente.
- RESERVATION_AFFINITY_KEY: a string compute.googleapis.com/reservation-name. Tem de especificar esta opção quando o valor de RESERVATION_AFFINITY_TYPE é SPECIFIC_RESERVATION.
- RESERVATION_AFFINITY_VALUES: um valor ARRAY<STRING> que especifica o nome completo do recurso da reserva do Compute Engine no seguinte formato:
  
  projects/myproject/zones/reservation_zone/reservations/reservation_name
  Por exemplo, RESERVATION_AFFINITY_values = ['projects/myProject/zones/us-central1-a/reservations/myReservationName'].
  
  Pode obter o nome e a zona da reserva na página Reservas da Google Cloud consola. Para mais informações, consulte Ver reservas.
  
  Tem de especificar esta opção quando o valor de RESERVATION_AFFINITY_TYPE for SPECIFIC_RESERVATION.
- ENDPOINT_IDLE_TTL: um valor INTERVAL que especifica a duração da inatividade após a qual o modelo aberto é anulado automaticamente a implementação do ponto final do Vertex AI.
  Para ativar a anulação da implementação automática, especifique um valor literal de intervalo entre 390 minutos (6,5 horas) e 7 dias. Por exemplo, especifique INTERVAL 8 HOUR para que o modelo seja anulado após 8 horas de inatividade. O valor predefinido é de 390 minutos (6,5 horas).
  
  A inatividade do modelo é definida como o tempo decorrido desde que qualquer uma das seguintes operações foi realizada no modelo:
  - Executar a declaração CREATE MODEL.
  - Executar a declaração ALTER MODEL com o argumento DEPLOY_MODEL definido como TRUE.
  - Enviar um pedido de inferência para o ponto final do modelo. Por exemplo, executando a função ML.GENERATE_EMBEDDING ou ML.GENERATE_TEXT.
  Cada uma destas operações repõe o temporizador de inatividade para zero. A reposição é acionada no início da tarefa do BigQuery que executa a operação.
  
  Depois de o modelo ser anulado, os pedidos de inferência enviados para o modelo devolvem um erro. O objeto do modelo do BigQuery permanece inalterado, incluindo os metadados do modelo. Para usar novamente o modelo para inferência, tem de o implementar novamente executando a declaração ALTER MODEL no modelo e definindo a opção DEPLOY_MODEL como TRUE.

Modelos abertos implementados

Na Google Cloud consola, aceda à página BigQuery.

Aceda ao BigQuery
Usando o editor de SQL, crie um modelo remoto:
```
CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  ENDPOINT = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID'
);
```
Substitua o seguinte:
- PROJECT_ID: o ID do seu projeto.
- DATASET_ID: o ID do conjunto de dados que vai conter o modelo. Este conjunto de dados tem de estar na mesma localização que a ligação que está a usar.
- MODEL_NAME: o nome do modelo.
- REGION: a região usada pela ligação.
- CONNECTION_ID: o ID da sua ligação ao BigQuery.
  Pode obter este valor vendo os detalhes da associação na Google Cloud consola e copiando o valor na última secção do ID de associação totalmente qualificado apresentado em ID de associação. Por exemplo, projects/myproject/locations/connection_location/connections/myconnection.
- ENDPOINT_REGION: a região na qual o modelo aberto está implementado.
- ENDPOINT_PROJECT_ID: o projeto no qual o modelo aberto está implementado.
- ENDPOINT_ID: o ID do ponto final HTTPS usado pelo modelo aberto. Pode obter o ID do ponto final localizando o modelo aberto na página Previsão online e copiando o valor no campo ID.

Todos os outros modelos

Na Google Cloud consola, aceda à página BigQuery.

Aceda ao BigQuery
Usando o editor de SQL, crie um modelo remoto:
```
CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (ENDPOINT = 'ENDPOINT');
```
Substitua o seguinte:
- PROJECT_ID: o ID do seu projeto.
- DATASET_ID: o ID do conjunto de dados que vai conter o modelo. Este conjunto de dados tem de estar na mesma localização que a ligação que está a usar.
- MODEL_NAME: o nome do modelo.
- REGION: a região usada pela ligação.
- CONNECTION_ID: o ID da sua ligação ao BigQuery.
  Pode obter este valor vendo os detalhes da associação na Google Cloud consola e copiando o valor na última secção do ID de associação totalmente qualificado apresentado em ID de associação. Por exemplo, projects/myproject/locations/connection_location/connections/myconnection.
- ENDPOINT: o nome de um modelo de incorporação a usar. Para mais informações, consulte ENDPOINT.
  O modelo da Vertex AI que especificar tem de estar disponível na localização onde está a criar o modelo remoto. Para mais informações, consulte o artigo Localizações.

Gere incorporações de texto

Gere incorporações de texto com a função ML.GENERATE_EMBEDDING usando dados de texto de uma coluna de tabela ou uma consulta.

Normalmente, usaria um modelo de incorporação de texto para exemplos de utilização apenas de texto e um modelo de incorporação multimodal para exemplos de utilização de pesquisa intermodal, em que as incorporações de texto e conteúdo visual são geradas no mesmo espaço semântico.

Vertex AI text

Gere incorporações de texto usando um modelo remoto através de um modelo de incorporação de texto do Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Substitua o seguinte:

PROJECT_ID: o ID do seu projeto.
DATASET_ID: o ID do conjunto de dados que contém o modelo.
MODEL_NAME: o nome do modelo remoto sobre um modelo de incorporação.
TABLE_NAME: o nome da tabela que contém o texto a incorporar. Esta tabela tem de ter uma coluna com o nome content ou pode usar um alias para usar uma coluna com um nome diferente.
CONTENT_QUERY: uma consulta cujo resultado contém uma coluna STRING denominada content.
FLATTEN_JSON: um valor BOOL que indica se a incorporação deve ser analisada numa coluna separada. O valor predefinido é TRUE.
TASK_TYPE: um literal STRING que especifica a aplicação a jusante pretendida para ajudar o modelo a produzir incorporações de melhor qualidade. TASK_TYPE aceita os seguintes valores:
- RETRIEVAL_QUERY: especifica que o texto fornecido é uma consulta numa definição de pesquisa ou obtenção.
- RETRIEVAL_DOCUMENT: especifica que o texto fornecido é um documento numa definição de pesquisa ou obtenção.
  Quando usar este tipo de tarefa, é útil incluir o título do documento na declaração de consulta para melhorar a qualidade da incorporação. O título do documento tem de estar numa coluna com o nome title ou com o alias title, por exemplo:
```
      SELECT *
      FROM
        ML.GENERATE_EMBEDDING(
          MODEL mydataset.embedding_model,
          (SELECT abstract as content, header as title, publication_number
          FROM mydataset.publications),
          STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
      );
      
```
  A especificação da coluna de título na consulta de entrada preenche o campo title do corpo do pedido enviado para o modelo. Se especificar um valor title quando usar qualquer outro tipo de tarefa, essa entrada é ignorada e não tem qualquer efeito nos resultados da incorporação.
- SEMANTIC_SIMILARITY: especifica que o texto fornecido vai ser usado para a similaridade textual semântica (STS).
- CLASSIFICATION: especifica que as incorporações vão ser usadas para a classificação.
- CLUSTERING: especifica que as incorporações vão ser usadas para o agrupamento.
- QUESTION_ANSWERING: especifica que as incorporações vão ser usadas para responder a perguntas.
- FACT_VERIFICATION: especifica que as incorporações vão ser usadas para a validação de factos.
- CODE_RETRIEVAL_QUERY: especifica que as incorporações vão ser usadas para obtenção de código.
OUTPUT_DIMENSIONALITY: um valor INT64 que especifica o número de dimensões a usar ao gerar incorporações. Por exemplo, se especificar 256 AS output_dimensionality, a coluna de saída ml_generate_embedding_result contém 256 incorporações para cada valor de entrada.
Para modelos remotos com mais de gemini-embedding-001 modelos, o valor OUTPUT_DIMENSIONALITY tem de estar no intervalo [1, 3072]. O valor predefinido é 3072. Para modelos remotos com mais de text-embedding ou text-multilingual-embedding, o valor OUTPUT_DIMENSIONALITY tem de estar no intervalo [1, 768]. O valor predefinido é 768.

Se estiver a usar um modelo remoto num modelo text-embedding, a versão do modelo text-embedding tem de ser text-embedding-004 ou posterior. Se estiver a usar um modelo remoto através de um modelo text-multilingual-embedding, a versão do modelo text-multilingual-embedding tem de ser text-multilingual-embedding-002 ou posterior.

Exemplo: incorporar texto numa tabela

O exemplo seguinte mostra um pedido para incorporar a coluna content da tabela text_data:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT(TRUE AS flatten_json_output, 'CLASSIFICATION' AS task_type)
  );

Texto livre

Gere incorporações de texto usando um modelo remoto através de um modelo de incorporação aberto:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

Substitua o seguinte:

PROJECT_ID: o ID do seu projeto.
DATASET_ID: o ID do conjunto de dados que contém o modelo.
MODEL_NAME: o nome do modelo remoto sobre um modelo de incorporação.
TABLE_NAME: o nome da tabela que contém o texto a incorporar. Esta tabela tem de ter uma coluna com o nome content ou pode usar um alias para usar uma coluna com um nome diferente.
CONTENT_QUERY: uma consulta cujo resultado contém uma coluna STRING denominada content.
FLATTEN_JSON: um valor BOOL que indica se deve analisar a incorporação numa coluna separada. O valor predefinido é TRUE.

Vertex AI multimodal

Gere incorporações de texto usando um modelo remoto através de um modelo de incorporação multimodal do Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Substitua o seguinte:

PROJECT_ID: o ID do seu projeto.
DATASET_ID: o ID do conjunto de dados que contém o modelo.
MODEL_NAME: o nome do modelo remoto sobre um modelo multimodalembedding@001.
TABLE_NAME: o nome da tabela que contém o texto a incorporar. Esta tabela tem de ter uma coluna com o nome content ou pode usar um alias para usar uma coluna com um nome diferente.
CONTENT_QUERY: uma consulta cujo resultado contém uma coluna STRING denominada content.
FLATTEN_JSON: um BOOL que indica se a incorporação deve ser analisada numa coluna separada. O valor predefinido é TRUE.
OUTPUT_DIMENSIONALITY: um valor INT64 que especifica o número de dimensões a usar ao gerar incorporações. Os valores válidos são 128, 256, 512 e 1408. O valor predefinido é 1408. Por exemplo, se especificar 256 AS output_dimensionality, a coluna de saída ml_generate_embedding_result contém 256 incorporações para cada valor de entrada.

Exemplo: use incorporações para classificar a semelhança semântica

O exemplo seguinte incorpora uma coleção de críticas de filmes e ordena-as pela distância de cossenos da crítica "Este filme foi mediano" através da função VECTOR_SEARCH. Uma distância mais pequena indica uma maior semelhança semântica.

Para mais informações sobre a pesquisa vetorial e o índice vetorial, consulte o artigo Introdução à pesquisa vetorial.

CREATE TEMPORARY TABLE movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "This movie was fantastic" AS content
        UNION ALL
        SELECT "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "This movie was just okay..." AS content
        UNION ALL
        SELECT "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
);

WITH average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  base.content AS content,
  distance AS distance_to_average_review
FROM
  VECTOR_SEARCH(
    TABLE movie_review_embeddings,
    "ml_generate_embedding_result",
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    distance_type=>"COSINE",
    top_k=>-1
  )
ORDER BY distance_to_average_review;

O resultado é o seguinte:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+

Gere incorporações de texto com a função ML.GENERATE_EMBEDDING

Funções necessárias

Autorizações necessárias

Antes de começar

Crie um conjunto de dados

Consola

bq

Crie uma associação

Consola

bq

Terraform

Prepare o Cloud Shell

Prepare o diretório

Aplique as alterações

Conceda uma função à conta de serviço da ligação do modelo remoto

Consola

gcloud

Escolha um método de implementação de modelo aberto

Crie um modelo remoto do BigQuery ML

Novos modelos abertos

Modelos abertos implementados

Todos os outros modelos

Gere incorporações de texto

Vertex AI text

Texto livre

Vertex AI multimodal

O que se segue?