Gere incorporações de imagens através da 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 da Vertex AI. Em seguida, usa esse modelo com a função ML.GENERATE_EMBEDDING para criar incorporações de imagens através de dados de uma tabela de objetos do BigQuery.

Funções necessárias

Para criar um modelo remoto e gerar incorporações, 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.

    Se usar o modelo remoto para analisar dados não estruturados de uma tabela de objetos e o contentor do Cloud Storage que usa na tabela de objetos estiver num projeto diferente do seu ponto final do Vertex AI, também tem de ter a função de administrador de armazenamento (roles/storage.admin) no contentor do Cloud Storage usado pela tabela de objetos.

  • 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 uma tabela de objetos: bigquery.tables.create e bigquery.tables.update
  • Crie um modelo e execute a inferência:
    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.models.updateMetadata

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

Antes de começar

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

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery, BigQuery Connection, Cloud Storage, 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

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

    Aceda à página do BigQuery

  2. No painel Explorador, clique no nome do projeto.

  3. Clique em Ver ações > Criar conjunto de dados.

  4. Na página Criar conjunto de dados, faça o seguinte:

    • Para ID do conjunto de dados, escreva um nome para o conjunto de dados.

    • Para Tipo de localização, selecione uma localização para o conjunto de dados.

    • Clique em Criar conjunto de dados.

bq

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

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

  1. Aceda à página do BigQuery.

    Aceda ao BigQuery

  2. No painel Explorador, clique em Adicionar dados:

    O elemento da IU Adicionar dados.

    É apresentada a caixa de diálogo Adicionar dados.

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

  4. Na secção Origens de dados em destaque, clique em Vertex AI.

  5. Clique no cartão da solução Modelos da Vertex AI: federação do BigQuery.

  6. Na lista Tipo de ligação, selecione Modelos remotos, funções remotas e BigLake (recurso da nuvem) da Vertex AI.

  7. No campo ID da associação, introduza um nome para a associação.

  8. Clique em Criar associação.

  9. Clique em Aceder à associação.

  10. No painel Informações de associação, copie o ID da conta de serviço para utilização num passo posterior.

bq

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

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

  1. Inicie o Cloud Shell.

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

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

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

  3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
  4. Guarde as alterações.
  5. 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

  1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas: 
    terraform plan

    Faça as correções necessárias à configuração.

  2. 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!).

  3. 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 acesso à conta de serviço

Conceda à conta de serviço da ligação as funções de utilizador do Vertex AI e visualizador de objetos do Storage.

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/gemini-2.0-flash', conceda estas funções no mesmo projeto que especificar no URL.

Se planeia especificar o ponto final através do nome do modelo quando criar o modelo remoto, por exemplo, endpoint = 'gemini-2.0-flash', conceda estas funções 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 estas funções, siga estes passos:

Consola

  1. Aceda à página IAM e administrador.

    Aceda a IAM e administração

  2. Clique em Adicionar.

    É apresentada a caixa de diálogo Adicionar responsáveis.

  3. No campo Novos membros, introduza o ID da conta de serviço que copiou anteriormente.

  4. No campo Selecionar uma função, selecione Vertex AI e, de seguida, selecione Utilizador da Vertex AI.

  5. Clique em Adicionar outra função.

  6. No campo Selecionar uma função, escolha Cloud Storage e, de seguida, selecione Visualizador de objetos de armazenamento.

  7. 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
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

Substitua o seguinte:

  • PROJECT_NUMBER: o número do projeto do projeto no qual conceder a função.
  • MEMBER: o ID da conta de serviço que copiou anteriormente.

Crie uma tabela de objetos

Para analisar imagens sem as mover do Cloud Storage, crie uma tabela de objetos.

Para criar uma tabela de objetos:

SQL

Use a declaração CREATE EXTERNAL TABLE.

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

    Aceda ao BigQuery

  2. No editor de consultas, introduza a seguinte declaração:

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu projeto.
    • DATASET_ID: o ID do conjunto de dados que criou.
    • TABLE_NAME: o nome da tabela de objetos.
    • REGION: a região ou região múltipla que contém a ligação.
    • CONNECTION_ID: o ID da associação que criou.

      Quando vê os detalhes da associação na Google Cloud consola, este é o valor na última secção do ID da associação totalmente qualificado apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

      Para usar uma associação predefinida, especifique DEFAULT em vez da string de associação que contém PROJECT_ID.REGION.CONNECTION_ID.

    • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém as imagens, no formato ['gs://bucket_name/[folder_name/]*'].

      O contentor do Cloud Storage que usa deve estar no mesmo projeto onde planeia criar o modelo e chamar a função ML.GENERATE_EMBEDDING. Se quiser chamar a função ML.GENERATE_EMBEDDING num projeto diferente do que contém o contentor do Cloud Storage usado pela tabela de objetos, tem de conceder a função de administrador de armazenamento ao nível do contentor à conta de serviço service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.

    • STALENESS_INTERVAL: especifica se as operações na tabela de objetos usam metadados em cache e a antiguidade máxima dos metadados em cache para que a operação os use. Para mais informações sobre considerações relativas à colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

      Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefinição.

      Para ativar o armazenamento em cache de metadados, especifique um valor literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Cloud Storage.

    • CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Para mais informações sobre considerações de colocação em cache de metadados, consulte Colocação em cache de metadados para desempenho.

      Definido como AUTOMATIC para que a cache de metadados seja atualizada a um intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

      Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache.

      Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

  3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Use o comando bq mk.

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

Substitua o seguinte:

  • BUCKET_PATH: o caminho para o contentor do Cloud Storage que contém as imagens, no formato ['gs://bucket_name/[folder_name/]*'].

    O contentor do Cloud Storage que usa deve estar no mesmo projeto onde planeia criar o modelo e chamar a função ML.GENERATE_EMBEDDING. Se quiser chamar a função ML.GENERATE_EMBEDDING num projeto diferente do que contém o contentor do Cloud Storage usado pela tabela de objetos, tem de conceder a função de administrador de armazenamento ao nível do contentor à conta de serviço service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.

  • REGION: a região ou região múltipla que contém a ligação.
  • CONNECTION_ID: o ID da associação que criou.

    Quando vê os detalhes da associação na Google Cloud consola, este é o valor na última secção do ID da associação totalmente qualificado apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

  • STALENESS_INTERVAL: especifica se as operações na tabela de objetos usam metadados em cache e a antiguidade máxima dos metadados em cache para que a operação os use. Para mais informações sobre considerações relativas à colocação em cache de metadados, consulte o artigo Colocação em cache de metadados para desempenho.

    Para desativar a colocação em cache de metadados, especifique 0. Esta é a predefinição.

    Para ativar o armazenamento em cache de metadados, especifique um valor literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de desatualização de 4 horas. Com este valor, as operações na tabela usam metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem mais antigos, a operação obtém metadados do Cloud Storage.

  • CACHE_MODE: especifica se a cache de metadados é atualizada automaticamente ou manualmente. Para mais informações sobre considerações de colocação em cache de metadados, consulte Colocação em cache de metadados para desempenho.

    Definido como AUTOMATIC para que a cache de metadados seja atualizada a um intervalo definido pelo sistema, normalmente entre 30 e 60 minutos.

    Defina como MANUAL se quiser atualizar a cache de metadados de acordo com uma programação que determinar. Neste caso, pode chamar o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar a cache.

    Tem de definir CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor superior a 0.

  • PROJECT_ID: o ID do seu projeto.
  • DATASET_ID: o ID do conjunto de dados que criou.
  • TABLE_NAME: o nome da tabela de objetos.

Criar um modelo

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

    Aceda ao BigQuery

  2. 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 criou anteriormente.
    • MODEL_NAME: o nome do modelo.
    • REGION: a região ou região múltipla que contém a ligação.
    • CONNECTION_ID: o ID da associação que criou.

      Quando vê os detalhes da associação na Google Cloud consola, este é o valor na última secção do ID da associação totalmente qualificado apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection.

    • ENDPOINT: o modelo de incorporação a usar, neste caso, multimodalembedding@001.

      Se especificar um URL como o ponto final quando criar o modelo remoto, por exemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/multimodalembedding@001', certifique-se de que o projeto que especificar no URL é o projeto no qual concedeu a função de utilizador do Vertex AI à ligação. conta de serviço.

      O modelo multimodalembedding@001 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 imagens

Gere incorporações de imagens com a função ML.GENERATE_EMBEDDING usando dados de imagens de uma tabela de objetos:

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

Substitua o seguinte:

  • PROJECT_ID: o projeto que contém o modelo ou a tabela.
  • DATASET_ID: o conjunto de dados que contém o modelo ou a tabela.
  • MODEL_NAME: o nome do modelo remoto sobre um modelo multimodalembedding@001.
  • TABLE_NAME: o nome da tabela de objetos que contém as imagens a incorporar.
  • FLATTEN_JSON: um valor BOOL que indica se deve analisar a incorporação 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

O exemplo seguinte mostra como criar incorporações para as imagens na tabela de objetos images:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE `mydataset.images`,
    STRUCT(TRUE AS flatten_json_output, 512 AS output_dimensionality)
  );

O que se segue?