Anotar imagens com a função ML.ANNOTATE_IMAGE

Neste documento, descrevemos como usar a função ML.ANNOTATE_IMAGE com um modelo remoto para anotar imagens de uma tabela de objetos.

Permissões necessárias

• Para criar uma conexão, você precisa da associação no seguinte papel:

  • roles/bigquery.connectionAdmin

• Para conceder permissões à conta de serviço da conexão, você precisa da seguinte permissão:

  • resourcemanager.projects.setIamPolicy

• Para criar o modelo usando o BigQuery ML, você precisa das seguintes permissões:

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• Para executar a inferência, você precisa das seguintes permissões:

  • bigquery.tables.getData na tabela de objetos
  • bigquery.models.getData no modelo
  • bigquery.jobs.create

Antes de começar

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

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. Enable the BigQuery, BigQuery Connection API, and Cloud Vision API APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

6. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

7. Enable the BigQuery, BigQuery Connection API, and Cloud Vision API APIs.

   Enable the APIs

Crie uma conexão

Crie uma conexão de recursos de nuvem e tenha acesso à conta de serviço da conexão.

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. Para criar uma conexão, clique em Adicionar e em Conexões com fontes de dados externas.

3. Na lista Tipo de conexão, selecione Modelos remotos da Vertex AI, funções remotas e BigLake (Cloud Resource).

4. No campo ID da conexão, insira um nome para a conexão.

5. Clique em Criar conexão.

6. Clique em Ir para conexão.

7. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa posterior.

bq

1. Em um ambiente de linha de comando, crie uma conexão:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID
   

   O parâmetro --project_id substitui o projeto padrão.

   Substitua:

   • REGION: sua região de conexão
   • PROJECT_ID: o ID do projeto do Google Cloud
   • CONNECTION_ID: um ID para sua conexão

   Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

   Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID
   

   O resultado será assim:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Anexe a seguinte seção ao seu arquivo main.tf.

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}        

Substitua:

• CONNECTION_ID: um ID para sua conexão
• PROJECT_ID: o ID do projeto do Google Cloud
• REGION: sua região de conexão

Conceder acesso à conta de serviço

Selecione uma das seguintes opções:

Console

1. Acesse a página IAM e administrador.

   Acessar IAM e administrador

2. Clique em Adicionar.

   A caixa de diálogo Adicionar principais é aberta.

3. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

4. No campo Selecionar um papel, selecione Service Usage e, em seguida, selecione Consumidor do Service Usage.

5. Clique em Adicionar outro papel.

6. No campo Selecionar um papel, selecione BigQuery e, em seguida, selecione Usuário de conexão do BigQuery.

7. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding (em inglês).

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/serviceusage.serviceUsageConsumer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/bigquery.connectionUser' --condition=None

Substitua:

• PROJECT_NUMBER: o número do projeto.
• MEMBER: o ID da conta de serviço que você copiou anteriormente.

Deixar de conceder a permissão resulta em erro.

Criar uma tabela de objetos

Crie uma tabela de objetos com conteúdo de imagens. Com a tabela de objetos, é possível analisar as imagens sem movê-las do Cloud Storage.

O bucket do Cloud Storage usado pela tabela de objetos precisa estar no mesmo projeto em que você planeja criar o modelo e chamar a função ML.ANNOTATE_IMAGE. Se você quiser chamar a função ML.ANNOTATE_IMAGE em um projeto diferente que contém o bucket do Cloud Storage usado pela tabela de objetos, é preciso conceder o papel de Administrador do Storage no nível do bucket

Criar um modelo

Crie um modelo remoto com um REMOTE_SERVICE_TYPE de CLOUD_AI_VISION_V1:

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION PROJECT_ID.REGION.CONNECTION_ID
OPTIONS (REMOTE_SERVICE_TYPE = 'CLOUD_AI_VISION_V1');

Substitua:

• PROJECT_ID: o ID do projeto.
• DATASET_ID: o ID do conjunto de dados para conter o modelo. Esse conjunto de dados precisa estar no mesmo local que a conexão que você está usando.
• MODEL_NAME: o nome do modelo
• REGION: a região usada pela conexão.
• CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.

  Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

Anotar imagens

Anote as imagens com a função ML.ANNOTATE_IMAGE:

SELECT *
FROM ML.ANNOTATE_IMAGE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME,
  STRUCT(['FEATURE_NAME' [,...]] AS vision_features)
);

Substitua:

• PROJECT_ID: o ID do projeto.
• DATASET_ID: o ID do conjunto de dados que contém o modelo.
• MODEL_NAME: o nome do modelo
• OBJECT_TABLE_NAME: o nome da tabela de objetos que contém os URIs das imagens a serem anotadas.
• FEATURE_NAME: o nome de um recurso da API Cloud Vision compatível.

Exemplo 1

O exemplo a seguir rotula os itens mostrados nas imagens:

SELECT *
FROM ML.ANNOTATE_IMAGE(
  MODEL `myproject.mydataset.myvisionmodel`,
  TABLE myproject.mydataset.image_table,
  STRUCT(['label_detection'] AS vision_features)
);

Exemplo 2

O exemplo a seguir detecta todos os rostos mostrados nas imagens e também retorna atributos de imagem, como cores dominantes:

SELECT *
FROM ML.ANNOTATE_IMAGE(
  MODEL `myproject.mydataset.myvisionmodel`,
  TABLE myproject.mydataset.image_table,
  STRUCT(['face_detection', 'image_properties'] AS vision_features)
);

A seguir

• Para saber mais sobre a inferência de modelo, incluindo outras funções que podem ser usadas para analisar dados do BigQuery, consulte Visão geral da inferência de modelo.
• Para informações sobre as funções e instruções SQL compatíveis com cada tipo de modelo, consulte Jornada do usuário completa de cada modelo.
• Teste o notebook de análise de dados não estruturados com o BigQuery ML e os modelos pré-treinados da Vertex AI.