Esegui una pipeline

Vertex AI Pipelines consente di eseguire pipeline di machine learning (ML) create utilizzando l'SDK Kubeflow Pipelines o TensorFlow Extended in modalità serverless. Questo documento descrive come eseguire una pipeline ML.

Puoi anche creare esecuzioni di pipeline utilizzando modelli predefiniti nella Galleria modelli. Per ulteriori informazioni sulla Galleria modelli, consulta Utilizzare un modello predefinito dalla Galleria modelli.

Prima di iniziare

Prima di eseguire una pipeline con Vertex AI Pipelines, utilizza le seguenti istruzioni per configurare il tuo progetto e l'ambiente di sviluppo Google Cloud:

Crea una pipeline.
Per eseguire una pipeline utilizzando l'SDK Vertex AI per Python, installa l'SDK Vertex.
- Installa l'SDK Vertex AI.

Crea un'esecuzione della pipeline

Segui le istruzioni riportate di seguito per eseguire una pipeline ML utilizzando la console Google Cloud o Python.

Console

Segui le istruzioni riportate di seguito per eseguire una pipeline ML utilizzando la console Google Cloud.

Nella sezione Vertex AI della console Google Cloud, vai alla pagina Pipelines.

Vai a Pipeline
Nell'elenco a discesa Regione, seleziona la regione per creare l'esecuzione della pipeline.
Fai clic su Crea esecuzione per aprire il riquadro Crea esecuzione pipeline.
Nella sezione Esegui dettagli, segui questi passaggi:
1. Fai clic su Esegui origine. Sono disponibili le seguenti opzioni:
  - Seleziona da pipeline esistenti: per creare un'esecuzione della pipeline basata su un modello di pipeline esistente, fai clic su Seleziona da pipeline esistenti e inserisci i seguenti dettagli:
    1. Seleziona il Repository contenente la pipeline o il file di definizione del componente.
    2. Seleziona Pipeline o componente e Versione.
    3. Specifica un Nome esecuzione per identificare in modo univoco l'esecuzione della pipeline.
  - Selezionare una pipeline Galleria di modelli: per creare una pipeline basata su un modello di pipeline creato da Google nella Galleria modelli, fai clic su Seleziona una pipeline Galleria di modelli e inserisci i seguenti dettagli:
    1. Nell'elenco pipeline Galleria modelli, seleziona il modello di pipeline.
    2. (Facoltativo) Modifica il valore predefinito in Nome esecuzione che identifica in modo univoco l'esecuzione della pipeline.
    Nota: queste istruzioni descrivono come creare un'esecuzione della pipeline utilizzando l'interfaccia predefinita della pagina Crea esecuzione pipeline, che include le sezioni Dettagli esecuzione e Configurazione runtime. Per alcuni modelli della Galleria modelli, questa pagina contiene sezioni aggiuntive. Ad esempio, il modello AutoML per la classificazione tabulare / regressione include anche le sezioni Metodo di addestramento, Opzioni di addestramento e Calcolo e prezzi.
  - Carica file: per caricare una definizione della pipeline compilata, fai clic su Carica file e inserisci i seguenti dettagli:
    1. Fai clic su Sfoglia per aprire il selettore di file. Passa al file YAML della pipeline compilata che vuoi eseguire, seleziona la pipeline e fai clic su Apri.
    2. Il campo Nome pipeline o componente mostra il nome specificato nella definizione della pipeline, per impostazione predefinita. (Facoltativo) Specifica un nome pipeline diverso.
    3. Specifica un Nome esecuzione per identificare in modo univoco l'esecuzione della pipeline.
  - Importa da Cloud Storage: per importare un file di definizione della pipeline da Cloud Storage, fai clic su Importa da Cloud Storage e inserisci i seguenti dettagli:
    1. Fai clic su Sfoglia per accedere al bucket Cloud Storage contenente l'oggetto di definizione della pipeline, seleziona il file e fai clic su Seleziona.
    2. Specifica il Nome pipeline o componente.
    3. Specifica un Nome esecuzione per identificare in modo univoco l'esecuzione della pipeline.
2. (Facoltativo) Per pianificare esecuzioni di pipeline ricorrenti, specifica la pianificazione di esecuzione come segue:
  1. Seleziona Ricorrente.
  2. In Ora di inizio, specifica quando la pianificazione deve diventare attiva.
    - Per pianificare la prima esecuzione in modo che venga eseguita immediatamente dopo la creazione della pianificazione, seleziona Immediatamente.
    - Per pianificare la prima esecuzione in modo che venga eseguita in una data e un'ora specifiche, seleziona On.
  3. Nel campo Frequenza, specifica la frequenza con cui pianificare ed eseguire le esecuzioni della pipeline, utilizzando un'espressione di pianificazione cron basata su unix-cron.
  4. In Termina, specifica quando termina la pianificazione.
    - Per indicare che la pianificazione crea la pipeline a tempo indeterminato, seleziona Mai.
    - Per indicare che la pianificazione termina in una data e un'ora specifiche, seleziona On e specifica la data e l'ora di fine della pianificazione.
  5. (Facoltativo) Per specificare che l'esecuzione della pipeline utilizza un account di servizio personalizzato, una chiave di crittografia gestita dal cliente (CMEK) o una rete VPC in peering, fai clic su Opzioni avanzate e segui queste istruzioni:
    - Per specificare un account di servizio, selezionane uno dall'elenco a discesa Account di servizio.
      
      Se non specifichi un account di servizio, Vertex AI Pipelines esegue la pipeline utilizzando l'account di servizio predefinito di Compute Engine.
      
      Scopri di più sulla configurazione di un account di servizio da utilizzare con Vertex AI Pipelines.
    - Per utilizzare una CMEK, seleziona Utilizza una chiave di crittografia gestita dal cliente. Viene visualizzato l'elenco a discesa Seleziona una chiave gestita dal cliente. Nell'elenco a discesa Seleziona una chiave gestita dal cliente, scegli la chiave che vuoi utilizzare.
    - Per utilizzare una rete VPC in peering in questa esecuzione della pipeline, inserisci il nome della rete VPC nella casella Rete VPC in peering.
3. Fai clic su Continua.
Nella sezione Configurazione runtime, configura l'esecuzione della pipeline come segue:
1. In Località Cloud Storage, fai clic su Sfoglia per selezionare il bucket Cloud Storage in cui archiviare gli artefatti di output della pipeline, quindi fai clic su Seleziona.
2. (Facoltativo) Per configurare il criterio di errore e la cache per l'esecuzione della pipeline, fai clic su Opzioni avanzate, quindi segui le istruzioni riportate di seguito:
  - In Criterio di errore, specifica il criterio di errore per l'intera pipeline. Scopri di più sui criteri relativi agli errori della pipeline.
    - Per configurare la pipeline in modo che continui a pianificare le attività dopo il mancato completamento di un'attività, seleziona Esegui tutti i passaggi fino al completamento. Questa opzione è selezionata per impostazione predefinita.
    - Per configurare la pipeline in modo che abbia esito negativo dopo un'attività non riuscita, seleziona Fail this run as soon as one step fail.
  - In Configurazione memorizzazione nella cache, specifica la configurazione della cache per l'intera pipeline.
    - Per utilizzare la configurazione della cache a livello di attività per l'attività nella pipeline, seleziona Non sostituire la configurazione della cache a livello di attività.
    - Per attivare la memorizzazione nella cache per tutte le attività nella pipeline e sostituire qualsiasi configurazione della cache a livello di attività, seleziona Abilita la lettura dalla cache per tutti i passaggi (più veloce).
    - Per disattivare la memorizzazione nella cache per tutte le attività nella pipeline e sostituire qualsiasi configurazione della cache a livello di attività, seleziona Disabilita la lettura dalla cache per tutti i passaggi (più veloce).
3. (Facoltativo) Se la pipeline contiene parametri, in Parametri della pipeline, specifica i parametri di esecuzione della pipeline.
Per creare l'esecuzione della pipeline, fai clic su Invia.

SDK Vertex AI per Python

Segui le istruzioni riportate di seguito per eseguire una pipeline ML utilizzando l'SDK Vertex AI per Python. Prima di eseguire il seguente esempio di codice, devi configurare l'autenticazione.

Configura l'autenticazione

Per configurare l'autenticazione, devi creare una chiave dell'account di servizio e impostare una variabile di ambiente per il percorso della chiave dell'account di servizio.

Crea un account di servizio:
1. Nella console Google Cloud, vai alla pagina Crea account di servizio.
  
  Vai a Crea account di servizio
2. Inserisci un nome nel campo Nome account di servizio.
3. (Facoltativo) Nel campo Descrizione account di servizio, inserisci una descrizione.
4. Fai clic su Crea.
5. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona Vertex AI > Utente Vertex AI.
6. Fai clic su Fine per creare l'account di servizio.
  
  Non chiudere la finestra del browser. Lo utilizzerai nel passaggio successivo.
Crea una chiave dell'account di servizio per l'autenticazione:
1. Nella console Google Cloud, fai clic sull'indirizzo email dell'account di servizio che hai creato.
2. Fai clic su Chiavi.
3. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.
4. Fai clic su Crea. Un file di chiave JSON viene scaricato sul computer.
5. Fai clic su Chiudi.
Concedi al nuovo account di servizio l'accesso all'account di servizio che utilizzi per eseguire le pipeline.
1. Fai clic su per tornare all'elenco degli account di servizio.
2. Fai clic sul nome dell'account di servizio che utilizzi per eseguire le pipeline. Viene visualizzata la pagina Dettagli account di servizio.
  
  Se hai seguito le istruzioni nella guida per configurare il tuo progetto per Vertex AI Pipelines, questo sarà lo stesso account di servizio che hai creato nella sezione Configura un account di servizio con autorizzazioni granulari. Altrimenti, Vertex AI utilizza l'account di servizio predefinito di Compute Engine per eseguire le pipeline. L'account di servizio predefinito di Compute Engine è denominato come segue: PROJECT_NUMBER-compute@developer.gserviceaccount.com
3. Fai clic sulla scheda Autorizzazioni.
4. Fai clic su Concedi accesso. Viene visualizzato il riquadro Aggiungi entità.
5. Nella casella Nuove entità, inserisci l'indirizzo email dell'account di servizio creato in un passaggio precedente.
6. Nell'elenco a discesa Ruolo, seleziona Account di servizio > Utente account di servizio.
7. Fai clic su Salva
Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON che contiene la chiave dell'account di servizio. Questa variabile si applica solo alla sessione di Shell corrente; di conseguenza, se apri una nuova sessione, imposta di nuovo la variabile.

Esempio: Linux o macOS

Sostituisci [PATH] con il percorso del file JSON che contiene la chiave dell'account di servizio.
```
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
```
Ad esempio:
```
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
```
Esempio: Windows

Sostituisci [PATH] con il percorso del file JSON che contiene la chiave dell'account di servizio e [FILE_NAME] con il nome file.

Con PowerShell:
```
$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
```
Ad esempio:
```
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"
```
Con il prompt dei comandi:
```
set GOOGLE_APPLICATION_CREDENTIALS=[PATH]
```

Esegui una pipeline

L'esecuzione di un oggetto PipelineJob Vertex AI richiede la creazione di un oggetto PipelineJob e la chiamata del metodo submit.

Tipi di input speciali supportati da KFP

Durante la creazione di un'esecuzione della pipeline, puoi anche passare come input i seguenti segnaposto supportati dall'SDK KFP:

{{$.pipeline_job_name_placeholder}}
{{$.pipeline_job_resource_name_placeholder}}
{{$.pipeline_job_id_placeholder}}
{{$.pipeline_task_name_placeholder}}
{{$.pipeline_task_id_placeholder}}
{{$.pipeline_job_create_time_utc_placeholder}}
{{$.pipeline_root_placeholder}}

Per ulteriori informazioni, consulta la sezione Tipi di input speciali nella documentazione di Kubeflow Pipelines v2.

from google.cloud import aiplatform

job = aiplatform.PipelineJob(display_name = DISPLAY_NAME,
                             template_path = COMPILED_PIPELINE_PATH,
                             job_id = JOB_ID,
                             pipeline_root = PIPELINE_ROOT_PATH,
                             parameter_values = PIPELINE_PARAMETERS,
                             enable_caching = ENABLE_CACHING,
                             encryption_spec_key_name = CMEK,
                             labels = LABELS,
                             credentials = CREDENTIALS,
                             project = PROJECT_ID,
                             location = LOCATION,
                             failure_policy = FAILURE_POLICY)

job.submit(service_account=SERVICE_ACCOUNT,
           network=NETWORK)

Sostituisci quanto segue:

DISPLAY_NAME: il nome della pipeline, che verrà visualizzato nella console Google Cloud.
COMPILED_PIPELINE_PATH: il percorso del file YAML della pipeline compilata. Può essere un percorso locale o un URI Cloud Storage.

(Facoltativo) Per specificare una determinata versione di una pipeline compilata, includi il tag di versione in uno dei seguenti formati:
- COMPILED_PIPELINE_PATH:TAG, dove TAG è il tag di versione.
- COMPILED_PIPELINE_PATH@SHA256_TAG, dove SHA256_TAG è il valore hash sha256 della versione della pipeline.
JOB_ID: (facoltativo) un identificatore univoco per l'esecuzione di questa pipeline. Se l'ID job non è specificato, Vertex AI Pipelines crea un ID job per te utilizzando il nome della pipeline e il timestamp corrispondente al momento in cui è stata avviata l'esecuzione della pipeline.
PIPELINE_ROOT_PATH: (facoltativo) per eseguire l'override del percorso principale della pipeline specificato nella definizione della pipeline, specifica un percorso a cui può accedere il job della pipeline, ad esempio l'URI di un bucket Cloud Storage.
PIPELINE_PARAMETERS: (facoltativo) i parametri della pipeline da passare a questa esecuzione. Ad esempio, crea un elemento dict() con i nomi dei parametri come chiavi del dizionario e i valori dei parametri come valori del dizionario.
ENABLE_CACHING: (facoltativo) specifica se l'esecuzione della pipeline utilizza la memorizzazione nella cache di esecuzione. La memorizzazione nella cache di esecuzione riduce i costi saltando le attività della pipeline in cui l'output è noto per l'attuale set di input. Se l'argomento di attivazione della memorizzazione nella cache non è specificato, in questa esecuzione della pipeline viene utilizzata la memorizzazione nella cache. Scopri di più sull'esecuzione della memorizzazione nella cache.
CMEK: (facoltativo) il nome della chiave di crittografia gestita dal cliente che vuoi utilizzare per questa esecuzione della pipeline.
LABELS: (facoltativo) le etichette definite dall'utente per organizzare questo PipelineJob. Per maggiori informazioni sulle etichette delle risorse, consulta Creazione e gestione delle etichette nella documentazione di Resource Manager.

Vertex AI Pipelines associa automaticamente la seguente etichetta all'esecuzione della pipeline:

vertex-ai-pipelines-run-billing-id: pipeline_run_id

dove pipeline_run_id è l'ID univoco dell'esecuzione della pipeline.

Questa etichetta collega l'utilizzo delle risorse Google Cloud generate dalla pipeline eseguita nei report di fatturazione.
CREDENTIALS: (facoltativo) credenziali personalizzate da utilizzare per creare questo PipelineJob. Esegue l'override delle credenziali impostate in aiplatform.init.
PROJECT_ID: (facoltativo) il progetto Google Cloud in cui vuoi eseguire la pipeline. Se non imposti questo parametro, viene utilizzato il progetto impostato in aiplatform.init.
LOCATION: (facoltativo) la regione in cui vuoi eseguire la pipeline. Per ulteriori informazioni sulle regioni in cui Vertex AI Pipelines è disponibile, consulta la guida alle località di Vertex AI. Se non imposti questo parametro, viene utilizzata la località predefinita impostata in aiplatform.init.
FAILURE_POLICY: (facoltativo) specifica il criterio di errore per l'intera pipeline. Sono disponibili le seguenti configurazioni:
- Per configurare la pipeline in modo che abbia esito negativo dopo un'attività non riuscita, inserisci fast.
- Per configurare la pipeline in modo che continui a pianificare le attività dopo che un'attività non va a buon fine, inserisci slow.
Se non imposti questo parametro, la configurazione del criterio di errore è impostata su slow per impostazione predefinita. Scopri di più sui criteri relativi agli errori della pipeline.
SERVICE_ACCOUNT: (facoltativo) il nome dell'account di servizio da utilizzare per l'esecuzione di questa pipeline. Se non specifichi un account di servizio, Vertex AI Pipelines esegue la pipeline utilizzando l'account di servizio predefinito di Compute Engine.
NETWORK: (facoltativo) :il nome della rete in peering VPC da utilizzare per questa esecuzione della pipeline.