Esegui una pipeline

Agent Platform Pipelines ti 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 i modelli predefiniti nella Galleria modelli. Per saperne di più sulla Galleria modelli, consulta Utilizza un modello predefinito della Galleria modelli.

Puoi utilizzare Gemini Enterprise Agent Platform Experiments per monitorare, analizzare e confrontare le esecuzioni della pipeline associandole a un esperimento o a un'esecuzione dell'esperimento. Confrontando i parametri, gli output e le metriche sul rendimento delle esecuzioni della pipeline, puoi identificare la configurazione della pipeline più adatta al tuo caso d'uso. Per saperne di più, consulta Introduzione agli esperimenti di Gemini Enterprise Agent Platform.

Prima di iniziare

Prima di eseguire una pipeline con Agent Platform Pipelines, segui queste istruzioni per configurare il progetto e l'ambiente di sviluppoGoogle Cloud :

1. Crea una pipeline.

2. Per eseguire una pipeline utilizzando l'SDK Agent Platform per Python, installa l'SDK Vertex.

   • Installa l'SDK Agent Platform.

Crea un'esecuzione della pipeline

Segui queste istruzioni per eseguire una pipeline ML utilizzando la console Google Cloud o Python.

Console

Segui queste istruzioni per eseguire una pipeline ML utilizzando la console Google Cloud .

1. Nella console Google Cloud , nella sezione Agent Platform, vai alla pagina Pipeline.

   Vai alle pipeline

2. Nell'elenco a discesa Regione, seleziona la regione in cui creare l'esecuzione della pipeline.

3. Fai clic su Crea esecuzione per aprire il riquadro Crea esecuzione pipeline.

4. Nella sezione Dettagli esecuzione, segui questi passaggi:

   1. Fai clic su un'origine di esecuzione. Sono disponibili le seguenti opzioni:

      • Seleziona dalle pipeline esistenti: per creare un'esecuzione della pipeline basata su un modello di pipeline esistente, fai clic su Seleziona dalle pipeline esistenti e inserisci i seguenti dettagli:

        1. Seleziona il repository contenente il file di definizione della pipeline o del componente.

        2. Seleziona Pipeline o componente e Versione.

        3. Specifica un Nome esecuzione per identificare in modo univoco l'esecuzione della pipeline.

      • Seleziona una pipeline Galleria di template: per creare un'esecuzione della pipeline basata su un template di pipeline creato da Google dalla Galleria di template, fai clic su Seleziona una pipeline Galleria di template e inserisci i seguenti dettagli:

        1. Nell'elenco Pipeline Galleria di modelli, seleziona il modello di pipeline.

        2. (Facoltativo) Modifica il Nome esecuzione predefinito 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 di pipeline compilata, fai clic su Carica file e inserisci i seguenti dettagli:

        1. Fai clic su Sfoglia per aprire il selettore file. Vai al file YAML della pipeline compilata che vuoi eseguire, seleziona la pipeline e fai clic su Apri.

        2. Il Nome pipeline o componente mostra il nome specificato nella definizione della pipeline, per impostazione predefinita. Facoltativamente, specifica un nome diverso per la pipeline.

        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 poi fai clic su Seleziona.

           In alternativa, inserisci l'URI Cloud Storage o l'URL HTTP/HTTPS del file di definizione della pipeline.

        2. Specifica il Nome pipeline o componente.

        3. Specifica un Nome esecuzione per identificare in modo univoco l'esecuzione della pipeline.

  1. Optional: To schedule recurring pipeline runs, specify the **Run schedule**, as follows:

      1. Select **Recurring**.

      1. Under **Start time**, specify when the schedule becomes active.

          * To schedule the first run to occur immediately after schedule creation, select **Immediately**.

          * To schedule the first run to occur at a specific time and date, select **On**.

      1. In the **Frequency** field, specify the frequency to schedule and execute the
      pipeline runs, using a cron schedule expression based on
      [unix-cron](https://man7.org/linux/man-pages/man5/crontab.5.html).

      1. Under **Ends**, specify when the schedule ends.

          * To indicate that the schedule creates pipeline runs indefinitely, select **Never**.

          * To indicate that the schedule ends on a specific date and time, select **On**, and specify the end date and time for the schedule.

      1. Optional: To specify that the pipeline run uses a custom service account,
      Customer-managed encryption keys (CMEK), or a peered VPC network, click
      **Advanced options**, and then follow these instructions:

          *  To specify a service account, select a service account from the
            **Service account** drop-down list.

              If you don't specify a service account,
              Agent Platform Pipelines runs your pipeline using the default
              Compute Engine service account.

              Learn more about [configuring a service account for use with
              Agent Platform Pipelines](/gemini-enterprise-agent-platform/machine-learning/pipelines/configure-project#service-account).

          *  To use a CMEK, select **Use a customer-managed encryption key**. The **Select a customer-managed key** drop-down list appears. In the **Select a customer-managed key** drop-down list, select the key that you want to use.

          *  To use a peered VPC network in this pipeline run, enter the VPC
          network name in the **Peered VPC network** box.

  1. Click **Continue**.

1. Nella sezione Configurazione di runtime, configura l'esecuzione della pipeline come segue:

   1. In Località di 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 la policy di errore e la cache per l'esecuzione della pipeline, fai clic su Opzioni avanzate, quindi segui queste istruzioni:

      • In Policy di errore, specifica la policy di errore per l'intera pipeline. Scopri di più sulle policy relative agli errori della pipeline.

        • Per configurare la pipeline in modo che continui a pianificare le attività dopo che un'attività non è riuscita, seleziona Esegui tutti i passaggi fino al completamento. Questa opzione è selezionata per impostazione predefinita.

        • Per configurare la pipeline in modo che non vada a buon fine dopo l'errore di un'attività, seleziona Interrompi questa esecuzione non appena un passaggio non va a buon fine.

      • In Configurazione della 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 eseguire l'override della configurazione della cache a livello di attività.

        • Per attivare la memorizzazione nella cache per tutte le attività della pipeline e ignorare qualsiasi configurazione della cache a livello di attività, seleziona Attiva la lettura dalla cache per tutti i passaggi (più veloce).

        • Per disattivare la memorizzazione nella cache per tutte le attività della pipeline e ignorare qualsiasi configurazione della cache a livello di attività, seleziona Disattiva la lettura dalla cache per tutti i passaggi (più veloce).

   3. (Facoltativo) Se la pipeline ha dei parametri, in Parametri pipeline, specifica i parametri di esecuzione della pipeline.

2. Per creare l'esecuzione della pipeline, fai clic su Invia.

Python

Segui queste istruzioni per eseguire una pipeline ML utilizzando l'SDK Agent Platform 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.

1. Crea un service account:

   1. Nella console Google Cloud vai a Crea service account.

      Vai a Crea service account

   2. Nel campo Nome service account, inserisci un nome.
   3. (Facoltativo) Nel campo Descrizione service account, inserisci una descrizione.
   4. Fai clic su Crea.
   5. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona Gemini Enterprise Agent Platform > Utente Agent Platform.
   Nota: i ruoli selezionati consentono al account di servizio di accedere alle risorse. Puoi visualizzare e modificare questi ruoli in un secondo momento utilizzando la consoleGoogle Cloud . Per saperne di più, consulta Controllo degli accessi per Agent Platform.

   6. Fai clic su Fine per creare il account di servizio.

      Non chiudere la finestra del browser. Lo utilizzerai nel prossimo passaggio.

2. Crea una chiave del account di servizio per l'autenticazione:

   1. Nella console Google Cloud , fai clic sull'indirizzo email del account di servizio che hai creato.
   2. Fai clic su Chiavi.
   3. Fai clic su Aggiungi chiave, poi su Crea nuova chiave.
   4. Fai clic su Crea. Un file della chiave JSON viene scaricato sul computer.
   5. Fai clic su Chiudi.
3. Concedi al nuovo account di servizio l'accesso al account di servizio che utilizzi per eseguire le pipeline.
   1. Fai clic su per tornare all'elenco dei service account.

   2. Fai clic sul nome del account di servizio che utilizzi per eseguire le pipeline. Viene visualizzata la pagina Dettagli service account.

      Se hai seguito le istruzioni della guida alla configurazione del progetto per le pipeline della piattaforma dell'agente Gemini Enterprise, questo è lo stesso account di servizio che hai creato nella sezione Configura un account di servizio con autorizzazioni granulari. In caso contrario, Gemini Enterprise Agent Platform utilizza il account di servizio predefinito di Compute Engine per eseguire le pipeline. Il account di servizio predefinito di Compute Engine ha un nome simile al seguente: [e-mail]

   3. Fai clic sulla scheda Autorizzazioni.
   4. Fai clic su Concedi l'accesso. Viene visualizzato il riquadro Aggiungi entità.
   5. Nella casella Nuove entità, inserisci l'indirizzo email del service account che hai creato in un passaggio precedente.
   6. Nell'elenco a discesa Ruolo, seleziona Service account > Utente service account.
   7. Fai clic su Salva.

4. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio. Questa variabile si applica solo alla sessione di Shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.

   Esempio: Linux o macOS

   Sostituisci [PATH] con il percorso del file JSON contenente 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 del 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 PipelineJob di Gemini Enterprise Agent Platform richiede la creazione di una risorsa PipelineJob e il richiamo del metodo submit.

Tipi di input speciali supportati da KFP

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

• {{$.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 saperne di più, consulta 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,
           reserved_ip_ranges=RESERVED_IP_RANGES)

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 URI Cloud Storage, un URL HTTP/HTTPS o un percorso locale.
  

  (Facoltativo) Per specificare una versione particolare di una pipeline compilata, includi il tag della versione in uno dei seguenti formati:

  • COMPILED_PIPELINE_PATH:TAG, dove TAG è il tag della versione.

  • COMPILED_PIPELINE_PATH@SHA256_TAG, dove SHA256_TAG è il valore hash sha256 della versione della pipeline.

• JOB_ID: (facoltativo) un identificatore univoco per questa esecuzione della pipeline. Se l'ID job non è specificato, le pipeline di Agent Platform creano un ID job per te utilizzando il nome della pipeline e il timestamp di avvio dell'esecuzione della pipeline.

• PIPELINE_ROOT_PATH: (facoltativo) per eseguire l'override del percorso root della pipeline specificato nella definizione della pipeline, specifica un percorso a cui il job della pipeline può accedere, ad esempio un URI del bucket Cloud Storage.

• PIPELINE_PARAMETERS: (facoltativo) i parametri della pipeline da passare a questa esecuzione. Ad esempio, crea un dict() con i nomi dei parametri come chiavi del dizionario e i valori dei parametri come valori del dizionario.

• ENABLE_CACHING: (facoltativo) specifica se questa esecuzione della pipeline utilizza la memorizzazione nella cache dell'esecuzione. La memorizzazione nella cache dell'esecuzione riduce i costi saltando le attività della pipeline in cui l'output è noto per l'insieme corrente di input. Se l'argomento per l'abilitazione della memorizzazione nella cache non è specificato, in questa esecuzione della pipeline viene utilizzata la memorizzazione nella cache dell'esecuzione. Scopri di più sulla memorizzazione nella cache di esecuzione.

• CMEK: (opzionale) Il nome delle chiavi di crittografia gestite dal cliente che si desidera utilizzare per questa esecuzione della pipeline.

• LABELS: (facoltativo) le etichette definite dall'utente per organizzare questo PipelineJob. Per saperne di più sulle etichette delle risorse, consulta Creazione e gestione delle etichette nella documentazione di Resource Manager.

  Le pipeline di Agent Platform applicano 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 dall'esecuzione della pipeline nei report sulla 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 saperne di più sulle regioni in cui è disponibile Agent Platform Pipelines, consulta la guida alle località di Gemini Enterprise Agent Platform. Se non imposti questo parametro, viene utilizzata la località predefinita impostata in aiplatform.init.

• FAILURE_POLICY: (facoltativo) specifica la policy di errore per l'intera pipeline. Sono disponibili le seguenti configurazioni:

  • Per configurare la pipeline in modo che l'esecuzione non vada a buon fine dopo l'errore di un'attività, inserisci fast.

  • Per configurare la pipeline in modo che continui a pianificare le attività dopo l'errore di un'attività, inserisci slow.

  Se non imposti questo parametro, la configurazione della policy di errore viene impostata su slow per impostazione predefinita. Scopri di più sulle policy relative agli errori della pipeline.

• SERVICE_ACCOUNT: (facoltativo) il nome del service account da utilizzare per l'esecuzione della pipeline. Se non specifichi un account di servizio, Agent Platform Pipelines esegue la pipeline utilizzando il account di servizio Compute Engine predefinito.

• NETWORK: (facoltativo) il nome della rete VPC in peering da utilizzare per questa esecuzione della pipeline.

• RESERVED_IP_RANGES: (Facoltativo) Un elenco di nomi per gli intervalli IP riservati nella rete VPC utilizzata per il workload dell'esecuzione della pipeline, ad esempio: ['vertex-ai-ip-range'].

Passaggi successivi

• Scopri come creare ed eseguire una pipeline e aggiungerla a un esperimento o a un'esecuzione di un esperimento.