Annotare le immagini con la funzione ML.ANNOTATE_IMAGE

Questo documento descrive come utilizzare la funzione ML.ANNOTATE_IMAGE con un modello remoto per annotare le immagini di una tabella di oggetti.

Autorizzazioni obbligatorie

• Per creare una connessione, devi disporre del seguente ruolo:

  • roles/bigquery.connectionAdmin

• Per concedere le autorizzazioni all'account di servizio della connessione, devi disporre della seguente autorizzazione:

  • resourcemanager.projects.setIamPolicy

• Per creare il modello utilizzando BigQuery ML, sono necessarie le seguenti autorizzazioni:

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

• Per eseguire l'inferenza, devi disporre delle seguenti autorizzazioni:

  • bigquery.tables.getData nella tabella degli oggetti
  • bigquery.models.getData sul modello
  • bigquery.jobs.create

Prima di iniziare

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.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

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.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

Crea una connessione

Crea una connessione della risorsa cloud e recupera il account di servizio della connessione.

Seleziona una delle seguenti opzioni:

# 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 {}
}

Concedi l'accesso all'account di servizio

Seleziona una delle seguenti opzioni:

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

Sostituisci quanto segue:

• PROJECT_NUMBER: il numero del progetto.
• MEMBER: l'ID account di servizio che hai copiato in precedenza.

La mancata concessione dell'autorizzazione comporta un errore.

Crea una tabella di oggetti

Crea una tabella di oggetti con contenuti di immagini. La tabella degli oggetti consente di analizzare le immagini senza spostarle da Cloud Storage.

Il bucket Cloud Storage utilizzato dalla tabella di oggetti deve trovarsi nello stesso progetto in cui prevedi di creare il modello e chiamare la funzione ML.ANNOTATE_IMAGE. Se vuoi chiamare la funzione ML.ANNOTATE_IMAGE in un progetto diverso da quello che contiene il bucket Cloud Storage utilizzato dalla tabella di oggetti, devi concedere il ruolo Amministratore Storage a livello di bucket.

crea un modello

Crea un modello remoto con un REMOTE_SERVICE_TYPE di 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');

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• DATASET_ID: l'ID del set di dati che deve contenere il modello. Questo set di dati deve trovarsi nella stessa posizione della connessione che stai utilizzando.
• MODEL_NAME: il nome del modello.
• REGION: la regione utilizzata dalla connessione.
• CONNECTION_ID: l'ID connessione, ad esempio myconnection.

  Quando visualizzi i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo visualizzato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

Annotare le immagini

Aggiungi annotazioni alle immagini con la funzione 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)
);

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• DATASET_ID: l'ID del set di dati che contiene il modello.
• MODEL_NAME: il nome del modello.
• OBJECT_TABLE_NAME: il nome della tabella degli oggetti che contiene gli URI delle immagini da annotare.
• FEATURE_NAME: il nome di una funzionalità dell'API Cloud Vision supportata.

Esempio 1

L'esempio seguente etichetta gli elementi mostrati nelle immagini:

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

Esempio 2

L'esempio seguente rileva tutti i volti mostrati nelle immagini e restituisce anche gli attributi delle immagini, come i colori dominanti:

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

Passaggi successivi

• Per scoprire di più sull'inferenza del modello, incluse altre funzioni che puoi utilizzare per analizzare i dati di BigQuery, consulta la Panoramica dell'inferenza del modello.
• Per informazioni sugli statement e sulle funzioni SQL supportati per ogni tipo di modello, consulta Percorso utente end-to-end per ogni modello.
• Prova il notebook Analisi dei dati non strutturati con BigQuery ML e modelli pre-addestrati di Vertex AI.