Questa pagina è stata tradotta dall'API Cloud Translation.

Esegui il deployment di una soluzione di analisi della visione artificiale con Dataflow e l'API Cloud Vision

Last reviewed 2024-05-16 UTC

Questo documento di deployment descrive come eseguire il deployment di una pipeline Dataflow per elaborare file immagine su larga scala con l'API Cloud Vision. Questa pipeline archivia i risultati dei file elaborati in BigQuery. Puoi utilizzare i file per scopi analitici o per addestrare modelli BigQuery ML.

La pipeline Dataflow creata in questo deployment può elaborare milioni di immagini al giorno. L'unico limite è la quota dell'API Vision. Puoi aumentare la quota dell'API Vision in base ai tuoi requisiti di scalabilità.

Queste istruzioni sono rivolte a data engineer e data scientist. Questo documento presuppone che tu abbia una conoscenza di base della creazione di pipeline Dataflow utilizzando l'SDK Java di Apache Beam, GoogleSQL per BigQuery e gli script di shell di base. Inoltre, si presuppone che tu abbia familiarità con l'API Vision.

Architettura

Il seguente diagramma illustra il flusso di sistema per creare una soluzione di analisi della visione artificiale ML.

Un'architettura che mostra il flusso di informazioni per i processi di importazione, attivazione, elaborazione, archiviazione e analisi.

Nel diagramma precedente, le informazioni fluiscono nell'architettura come segue:

Un client carica i file immagine in un bucket Cloud Storage.
Cloud Storage invia un messaggio sul caricamento dei dati in Pub/Sub.
Pub/Sub invia una notifica a Dataflow del caricamento.
La pipeline Dataflow invia le immagini all'API Vision.
L'API Vision elabora le immagini, quindi restituisce le annotazioni.
La pipeline invia i file annotati a BigQuery in modo che tu possa analizzarli.

Obiettivi

Creare una pipeline Apache Beam per l'analisi delle immagini caricate in Cloud Storage.
Utilizza Dataflow Runner v2 per eseguire la pipeline Apache Beam in modalità flusso di dati e analizzare le immagini non appena vengono caricate.
Utilizza l'API Vision per analizzare le immagini per un insieme di tipi di caratteristiche.
Analizza le annotazioni con BigQuery.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Quando finisci di creare l'applicazione di esempio, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per maggiori informazioni, consulta Pulizia.

Prima di iniziare

Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

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

Go to project selector

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

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

Go to project selector

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Nella console Google Cloud, attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

Clona il repository GitHub che contiene il codice sorgente della pipeline Dataflow:

    git clone
    https://github.com/GoogleCloudPlatform/dataflow-vision-analytics.git

Vai alla cartella principale del repository:
```
    cd dataflow-vision-analytics
    
```
Segui le istruzioni nella sezione Introduzione del repository dataflow-vision-analytics in GitHub per svolgere le seguenti attività:
- Abilita diverse API.
- Creare un bucket Cloud Storage.
- Creare un argomento e una sottoscrizione Pub/Sub.
- Creare un set di dati BigQuery.
- Configura diverse variabili di ambiente per questo deployment.

Esecuzione della pipeline Dataflow per tutte le funzionalità implementate dell'API Vision

La pipeline Dataflow richiede ed elabora un set specifico di funzionalità e attributi dell'API Vision all'interno dei file annotati.

I parametri elencati nella seguente tabella sono specifici della pipeline Dataflow in questo deployment. Per l'elenco completo dei parametri di esecuzione standard di Dataflow, consulta Impostare le opzioni della pipeline Dataflow.

Nome parametro	Descrizione
`batchSize`	Il numero di immagini da includere in una richiesta all'API Vision. Il valore predefinito è 1. Puoi aumentare questo valore fino a un massimo di 16.
`datasetName`	Il nome del set di dati BigQuery di output.
`features`	Un elenco di funzionalità di elaborazione delle immagini. La pipeline supporta le funzionalità etichetta, punto di riferimento, logo, volto, suggerimento di ritaglio e proprietà dell'immagine.
`keyRange`	Il parametro che definisce il numero massimo di chiamate parallele all'API Vision. Il valore predefinito è 1.
`labelAnnottationTable, landmarkAnnotationTable, logoAnnotationTable, faceAnnotationTable, imagePropertiesTable, cropHintAnnotationTable, errorLogTable`	Parametri stringa con nomi tabella per varie annotazioni. Per ogni tabella vengono forniti valori predefiniti, ad esempio `label_annotation`.
`maxBatchCompletionDurationInSecs`	Il tempo di attesa prima di elaborare le immagini quando è presente un batch incompleto di immagini. Il valore predefinito è 30 secondi.
`subscriberId`	L'ID della sottoscrizione Pub/Sub che riceve notifiche Cloud Storage in input.
`visionApiProjectId`	L'ID progetto da utilizzare per l'API Vision.

In Cloud Shell, esegui questo comando per elaborare le immagini per tutti i tipi di funzionalità supportati dalla pipeline Dataflow:
```
./gradlew run --args=" \
--jobName=test-vision-analytics \
  --streaming \
  --runner=DataflowRunner \
  --enableStreamingEngine \
  --diskSizeGb=30 \
  --project=${PROJECT} \
  --datasetName=${BIGQUERY_DATASET} \
  --subscriberId=projects/${PROJECT}/subscriptions/${GCS_NOTIFICATION_SUBSCRIPTION} \
  --visionApiProjectId=${PROJECT} \
  --features=IMAGE_PROPERTIES,LABEL_DETECTION,LANDMARK_DETECTION,LOGO_DETECTION,CROP_HINTS,FACE_DETECTION"
```
L'account di servizio dedicato deve avere accesso in lettura al bucket contenente le immagini. In altre parole, all'account deve essere concesso il ruolo roles/storage.objectViewer per quel bucket.

Per ulteriori informazioni sull'utilizzo di un account di servizio dedicato, consulta Sicurezza e autorizzazioni di Dataflow.
Apri l'URL visualizzato in una nuova scheda del browser o vai alla pagina Job Dataflow e seleziona la pipeline test-vision-analytics.

Dopo alcuni secondi, viene visualizzato il grafico del job Dataflow:

La pipeline Dataflow è ora in esecuzione e in attesa di ricevere notifiche di input dalla sottoscrizione Pub/Sub.
Attiva l'elaborazione delle immagini Dataflow caricando i sei file di esempio nel bucket di input:
```
gcloud storage cp data-sample/* gs://${IMAGE_BUCKET}
```
Nella console Google Cloud, individua il riquadro Contatori personalizzati e utilizzalo per esaminare i contatori personalizzati in Dataflow e per verificare che Dataflow abbia elaborato tutte e sei le immagini. Puoi utilizzare la funzionalità di filtro del riquadro per accedere alle metriche corrette. Per visualizzare solo i contatori che iniziano con il prefisso numberOf, digita numberOf nel filtro.

In Cloud Shell, verifica che le tabelle siano state create automaticamente:

bq query --nouse_legacy_sql "SELECT table_name FROM ${BIGQUERY_DATASET}.INFORMATION_SCHEMA.TABLES ORDER BY table_name"

L'output è il seguente:

+----------------------+
|      table_name      |
+----------------------+
| crop_hint_annotation |
| face_annotation      |
| image_properties     |
| label_annotation     |
| landmark_annotation  |
| logo_annotation      |
+----------------------+

Visualizza lo schema per la tabella landmark_annotation. La funzionalità LANDMARK_DETECTION acquisisce gli attributi restituiti dalla chiamata API.

bq show --schema --format=prettyjson ${BIGQUERY_DATASET}.landmark_annotation

L'output è il seguente:

[
   {
      "name":"gcs_uri",
      "type":"STRING"
   },
   {
      "name":"feature_type",
      "type":"STRING"
   },
   {
      "name":"transaction_timestamp",
      "type":"STRING"
   },
   {
      "name":"mid",
      "type":"STRING"
   },
   {
      "name":"description",
      "type":"STRING"
   },
   {
      "name":"score",
      "type":"FLOAT"
   },
   {
      "fields":[
         {
            "fields":[
               {
                  "name":"x",
                  "type":"INTEGER"
               },
               {
              "name":"y",
              "type":"INTEGER"
           }
        ],
        "mode":"REPEATED",
        "name":"vertices",
        "type":"RECORD"
     }
  ],
  "name":"boundingPoly",
  "type":"RECORD"
},
{
  "fields":[
     {
        "fields":[
           {
              "name":"latitude",
              "type":"FLOAT"
           },
           {
              "name":"longitude",
              "type":"FLOAT"
           }
        ],
            "name":"latLon",
            "type":"RECORD"
          }
        ],
      "mode":"REPEATED",
      "name":"locations",
      "type":"RECORD"
   }
]

Visualizza i dati delle annotazioni prodotti dall'API eseguendo i seguenti comandi bq query per vedere tutti i punti di riferimento trovati in queste sei immagini, ordinati in base al punteggio più probabile:

bq query --nouse_legacy_sql "SELECT SPLIT(gcs_uri, '/')[OFFSET(3)] file_name, description, score, locations FROM ${BIGQUERY_DATASET}.landmark_annotation ORDER BY score DESC"

L'output è simile al seguente:

+------------------+-------------------+------------+---------------------------------+
|    file_name     |    description    |   score    |            locations            |
+------------------+-------------------+------------+---------------------------------+
| eiffel_tower.jpg | Eiffel Tower      |  0.7251996 | ["POINT(2.2944813 48.8583701)"] |
| eiffel_tower.jpg | Trocadéro Gardens | 0.69601923 | ["POINT(2.2892823 48.8615963)"] |
| eiffel_tower.jpg | Champ De Mars     |  0.6800974 | ["POINT(2.2986304 48.8556475)"] |
+------------------+-------------------+------------+---------------------------------+

Per descrizioni dettagliate di tutte le colonne specifiche delle annotazioni, consulta AnnotateImageResponse.

Per arrestare la pipeline in modalità flusso, esegui questo comando. La pipeline continua a essere eseguita anche se non ci sono altre notifiche Pub/Sub da elaborare.
```
  gcloud dataflow jobs cancel
    --region ${REGION} $(gcloud dataflow jobs list
    --region ${REGION} --filter="NAME:test-vision-analytics AND STATE:Running"
    --format="get(JOB_ID)")
```
La seguente sezione contiene altri esempi di query che analizzano le diverse caratteristiche delle immagini.

Analisi di un set di dati Flickr30K

In questa sezione, vengono rilevate etichette e punti di riferimento nel set di dati di immagini Flickr30k pubblico ospitato su Kaggle.

In Cloud Shell, modifica i parametri della pipeline Dataflow in modo che siano ottimizzate per un set di dati di grandi dimensioni. Per consentire una velocità effettiva più elevata, aumenta anche i valori batchSize e keyRange. Dataflow scala il numero di worker in base alle esigenze:

./gradlew run --args=" \
  --runner=DataflowRunner \
  --jobName=vision-analytics-flickr \
  --streaming \
  --enableStreamingEngine \
  --diskSizeGb=30 \
  --autoscalingAlgorithm=THROUGHPUT_BASED \
  --maxNumWorkers=5 \
  --project=${PROJECT} \
  --region=${REGION} \
  --subscriberId=projects/${PROJECT}/subscriptions/${GCS_NOTIFICATION_SUBSCRIPTION} \
  --visionApiProjectId=${PROJECT} \
  --features=LABEL_DETECTION,LANDMARK_DETECTION \
  --datasetName=${BIGQUERY_DATASET} \
  --batchSize=16 \
  --keyRange=5"

Poiché il set di dati è di grandi dimensioni, non puoi utilizzare Cloud Shell per recuperare le immagini da Kaggle e inviarle al bucket Cloud Storage. Per farlo, devi usare una VM con una dimensione del disco maggiore.

Per recuperare le immagini basate su Kaggle e inviarle al bucket Cloud Storage, segui le istruzioni nella sezione Simulare le immagini che vengono caricate nel bucket di archiviazione nel repository GitHub.
Per osservare l'avanzamento del processo di copia esaminando le metriche personalizzate disponibili nella UI di Dataflow, vai alla pagina Job Dataflow e seleziona la pipeline vision-analytics-flickr. I contatori dei clienti devono cambiare periodicamente finché la pipeline Dataflow non elabora tutti i file.

L'output è simile al seguente screenshot del riquadro Contatori personalizzati. Uno dei file nel set di dati è di tipo errato e il contatore rejectedFiles riflette questo dato. Questi valori del contatore sono approssimativi. Potresti vedere numeri più alti. Inoltre, molto probabilmente il numero di annotazioni cambierà per via della maggiore accuratezza dell'elaborazione da parte dell'API Vision.

Per determinare se le risorse disponibili si stanno avvicinando o superano, consulta la pagina delle quote dell'API Vision.

Nel nostro esempio, la pipeline Dataflow ha utilizzato solo circa il 50% della sua quota. In base alla percentuale della quota che utilizzi, puoi decidere di aumentare il parallelismo della pipeline aumentando il valore del parametro keyRange.

Arresta la pipeline:

gcloud dataflow jobs list --region $REGION --filter="NAME:vision-analytics-flickr AND STATE:Running" --format="get(JOB_ID)"

Analizza le annotazioni in BigQuery

In questo deployment, hai elaborato più di 30.000 immagini per l'annotazione di etichette e punti di riferimento. In questa sezione verranno raccolte le statistiche relative a questi file. Puoi eseguire queste query nell'area di lavoro GoogleSQL per BigQuery o usare lo strumento a riga di comando bq.

Tieni presente che i numeri visualizzati possono variare rispetto ai risultati della query di esempio in questo deployment. L'API Vision migliora costantemente l'accuratezza dell'analisi e può produrre risultati più completi analizzando la stessa immagine dopo aver testato la soluzione inizialmente.

Nella console Google Cloud, vai alla pagina Editor query di BigQuery ed esegui questo comando per visualizzare le prime 20 etichette nel set di dati:

Vai all'editor di query

SELECT  description, count(*)ascount \
  FROM vision_analytics.label_annotation
  GROUP BY description ORDER BY count DESC LIMIT 20

L'output è simile al seguente:

+------------------+-------+
|   description    | count |
+------------------+-------+
| Leisure          |  7663 |
| Plant            |  6858 |
| Event            |  6044 |
| Sky              |  6016 |
| Tree             |  5610 |
| Fun              |  5008 |
| Grass            |  4279 |
| Recreation       |  4176 |
| Shorts           |  3765 |
| Happy            |  3494 |
| Wheel            |  3372 |
| Tire             |  3371 |
| Water            |  3344 |
| Vehicle          |  3068 |
| People in nature |  2962 |
| Gesture          |  2909 |
| Sports equipment |  2861 |
| Building         |  2824 |
| T-shirt          |  2728 |
| Wood             |  2606 |
+------------------+-------+

Determina quali altre etichette sono presenti in un'immagine con una determinata etichetta, ordinate per frequenza:

DECLARE label STRING DEFAULT 'Plucked string instruments';

WITH other_labels AS (
   SELECT description, COUNT(*) count
FROM vision_analytics.label_annotation
WHERE gcs_uri IN (
    SELECT gcs_uri FROM vision_analytics.label_annotation WHERE description = label )
  AND description != label
GROUP BY description)
SELECT description, count, RANK() OVER (ORDER BY count DESC) rank
FROM other_labels ORDER BY rank LIMIT 20;

L'output è il seguente. Per l'etichetta Plucked string instruments utilizzata nel comando precedente, dovresti vedere:

+------------------------------+-------+------+
|         description          | count | rank |
+------------------------------+-------+------+
| String instrument            |   397 |    1 |
| Musical instrument           |   236 |    2 |
| Musician                     |   207 |    3 |
| Guitar                       |   168 |    4 |
| Guitar accessory             |   135 |    5 |
| String instrument accessory  |    99 |    6 |
| Music                        |    88 |    7 |
| Musical instrument accessory |    72 |    8 |
| Guitarist                    |    72 |    8 |
| Microphone                   |    52 |   10 |
| Folk instrument              |    44 |   11 |
| Violin family                |    28 |   12 |
| Hat                          |    23 |   13 |
| Entertainment                |    22 |   14 |
| Band plays                   |    21 |   15 |
| Jeans                        |    17 |   16 |
| Plant                        |    16 |   17 |
| Public address system        |    16 |   17 |
| Artist                       |    16 |   17 |
| Leisure                      |    14 |   20 |
+------------------------------+-------+------+

Visualizza i 10 principali punti di riferimento rilevati:

  SELECT description, COUNT(description) AS count
  FROM vision_analytics.landmark_annotation
  GROUP BY description ORDER BY count DESC LIMIT 10

L'output è il seguente:

  +--------------------+-------+
  |    description     | count |
  +--------------------+-------+
  | Times Square       |    55 |
  | Rockefeller Center |    21 |
  | St. Mark's Square  |    16 |
  | Bryant Park        |    13 |
  | Millennium Park    |    13 |
  | Ponte Vecchio      |    13 |
  | Tuileries Garden   |    13 |
  | Central Park       |    12 |
  | Starbucks          |    12 |
  | National Mall      |    11 |
  +--------------------+-------+

Individua le immagini che molto probabilmente contengono cascate:

SELECT SPLIT(gcs_uri, '/')[OFFSET(3)] file_name, description, score
FROM vision_analytics.landmark_annotation
WHERE LOWER(description) LIKE '%fall%'
ORDER BY score DESC LIMIT 10

L'output è il seguente:

+----------------+----------------------------+-----------+
|   file_name    |        description         |   score    |
+----------------+----------------------------+-----------+
| 895502702.jpg  | Waterfall Carispaccha      |  0.6181358 |
| 3639105305.jpg | Sahalie Falls Viewpoint    | 0.44379658 |
| 3672309620.jpg | Gullfoss Falls             | 0.41680416 |
| 2452686995.jpg | Wahclella Falls            | 0.39005348 |
| 2452686995.jpg | Wahclella Falls            |  0.3792498 |
| 3484649669.jpg | Kodiveri Waterfalls        | 0.35024035 |
| 539801139.jpg  | Mallela Thirtham Waterfall | 0.29260656 |
| 3639105305.jpg | Sahalie Falls              |  0.2807213 |
| 3050114829.jpg | Kawasan Falls              | 0.27511594 |
| 4707103760.jpg | Niagara Falls              | 0.18691841 |
+----------------+----------------------------+-----------+

Trova immagini di punti di riferimento nel raggio di 3 km dal Colosseo a Roma (la funzione ST_GEOPOINT utilizza la longitudine e la latitudine del Colosseo):

WITH
  landmarksWithDistances AS (
  SELECT
    gcs_uri,
    description,
    location,
    ST_DISTANCE(location,
      ST_GEOGPOINT(12.492231,
        41.890222)) distance_in_meters,
  FROM
    `vision_analytics.landmark_annotation` landmarks
  CROSS JOIN
    UNNEST(landmarks.locations) AS location )
SELECT
  SPLIT(gcs_uri,"/")[OFFSET(3)] file,
  description,
    ROUND(distance_in_meters) distance_in_meters,
  location,
  CONCAT("https://storage.cloud.google.com/", SUBSTR(gcs_uri, 6)) AS image_url
FROM
  landmarksWithDistances
WHERE
  distance_in_meters < 3000
ORDER BY
  distance_in_meters
LIMIT
  100

Quando esegui la query, vedrai che sono presenti più immagini del Colosseo, ma anche immagini dell'Arco di Costantino, del Colle Palatino e di una serie di altri luoghi fotografati di frequente.

Puoi visualizzare i dati in BigQuery Geo Viz incollando nella query precedente. Seleziona un punto sulla mappa per visualizzarne i dettagli. L'attributo Image_url contiene un link al file immagine.

Mappa dei luoghi e della loro distanza dal Colosseo.

Una nota sui risultati delle query. Di solito, per i punti di riferimento sono presenti informazioni sulla posizione. La stessa immagine può contenere più posizioni dello stesso punto di riferimento. Questa funzionalità è descritta nel tipo AnnotateImageResponse.

Poiché una sola posizione può indicare la posizione della scena nell'immagine, possono essere presenti più elementi LocationInfo. Un'altra posizione può indicare dove è stata scattata l'immagine.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa guida, elimina il progetto che contiene le risorse oppure conserva il progetto ed elimina le singole risorse.

Elimina il progetto Google Cloud

Il modo più semplice per eliminare la fatturazione è eliminare il progetto Google Cloud che hai creato per il tutorial.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività in questo documento, quando lo elimini elimini anche qualsiasi altro lavoro svolto nel progetto.
Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Nella console Google Cloud, vai alla pagina Gestisci risorse.
Vai a Gestisci risorse
Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Se decidi di eliminare le risorse singolarmente, segui i passaggi nella sezione Pulizia del repository GitHub.

Passaggi successivi

Per altre architetture di riferimento, diagrammi e best practice, esplora il Cloud Architecture Center.

Collaboratori

Autori:

Masud Hasan | Site Reliability Engineering Manager
Sergei Lilichenko | Solutions Architect
Lakshmanan Sethu | Technical Account Manager

Altri collaboratori:

Jiyeon Kang | Customer Engineer
Sunil Kumar Jang Bahadur | Customer Engineer

Per vedere profili di LinkedIn non pubblici, accedi a LinkedIn.