Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare l'esecuzione di una pipeline su una risorsa permanente

Una risorsa permanente Vertex AI è un cluster a esecuzione prolungata che puoi utilizzare per eseguire job di addestramento personalizzato ed esecuzioni di pipeline. Utilizzando una risorsa persistente per l'esecuzione di una pipeline, puoi contribuire a garantire la disponibilità delle risorse di calcolo e ridurre il tempo di avvio dell'attività della pipeline. Le risorse persistenti supportano tutte le VM e le GPU supportate dai job di addestramento personalizzati. Per saperne di più sulle risorse permanenti, consulta Panoramica delle risorse permanenti.

Questa pagina mostra come:

Creare una risorsa permanente
Crea un'esecuzione pipeline utilizzando la risorsa permanente

Prima di iniziare

Prima di poter creare un'esecuzione della pipeline con una risorsa permanente, devi completare i seguenti prerequisiti.

Definisci e compila una pipeline

Definisci la pipeline e poi compila la definizione della pipeline in un file YAML. Per ulteriori informazioni sulla definizione e la compilazione di una pipeline, vedi Creare una pipeline.

Ruoli IAM richiesti

Per ottenere l'autorizzazione necessaria per creare una risorsa permanente, chiedi all'amministratore di concederti il ruolo IAM Vertex AI Administrator (roles/aiplatform.admin) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione aiplatform.persistentResources.create necessaria per creare una risorsa permanente.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Crea una risorsa permanente

Utilizza gli esempi seguenti per creare una risorsa permanente che puoi associare a un'esecuzione della pipeline. Per saperne di più sulla creazione di risorse permanenti, consulta Crea una risorsa permanente.

gcloud

Per creare una risorsa permanente che puoi associare a un'esecuzione della pipeline, utilizza il comando gcloud ai persistent-resources create insieme al flag --enable-custom-service-account.

Una risorsa permanente può avere uno o più pool di risorse. Per creare più pool di risorse in una risorsa permanente, specifica più flag --resource-pool-spec.

Puoi specificare tutte le configurazioni del pool di risorse come parte della riga di comando o utilizzare il flag --config per specificare il percorso di un file YAML che contiene le configurazioni.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

PROJECT_ID: l'ID progetto del Google Cloud progetto in cui vuoi creare la risorsa permanente.
LOCATION: la regione in cui vuoi creare la risorsa permanente. Per un elenco delle regioni supportate, consulta Disponibilità delle funzionalità.
PERSISTENT_RESOURCE_ID: un ID univoco definito dall'utente per la risorsa persistente. Deve iniziare con una lettera, terminare con una lettera o un numero e contenere solo lettere minuscole, numeri e trattini (-).
DISPLAY_NAME: (Facoltativo) Il nome visualizzato della risorsa permanente.
MACHINE_TYPE: Il tipo di macchina virtuale (VM) da utilizzare. Per un elenco delle VM supportate, consulta Tipi di macchine. Questo campo corrisponde al campo machineSpec.machineType nel messaggio dell'API ResourcePool.
REPLICA_COUNT: (Facoltativo) Il numero di repliche da creare per il pool di risorse, se non vuoi utilizzare la scalabilità automatica. Questo campo corrisponde al campo replicaCount nel messaggio dell'API ResourcePool. Devi specificare il numero di repliche se non specifichi i campi MIN_REPLICA_COUNT e MAX_REPLICA_COUNT.
MIN_REPLICA_COUNT: (Facoltativo) Il numero minimo di repliche se utilizzi la scalabilità automatica per il pool di risorse. Devi specificare sia MIN_REPLICA_COUNT sia MAX_REPLICA_COUNT per utilizzare la scalabilità automatica.
MAX_REPLICA_COUNT: (Facoltativo) Il numero massimo di repliche se utilizzi la scalabilità automatica per il pool di risorse. Devi specificare sia MIN_REPLICA_COUNT sia MAX_REPLICA_COUNT per utilizzare la scalabilità automatica.
CONFIG: percorso del file di configurazione YAML della risorsa permanente, contenente un elenco di specifiche ResourcePool. Se un'opzione è specificata sia nel file di configurazione che negli argomenti della riga di comando, questi ultimi prevalgono sul file di configurazione. Tieni presente che le chiavi con trattini bassi sono considerate non valide.
File di configurazione YAML di esempio:
```
resourcePoolSpecs:
  machineSpec:
    machineType: n1-standard-4
  replicaCount: 1
    
```

Esegui questo comando:

Linux, macOS o Cloud Shell

gcloud ai persistent-resources create \
    --persistent-resource-id=PERSISTENT_RESOURCE_ID \
    --display-name=DISPLAY_NAME \
    --project=PROJECT_ID \
    --region=LOCATION \
    --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" \
    --enable-custom-service-account

Windows (PowerShell)

gcloud ai persistent-resources create `
    --persistent-resource-id=PERSISTENT_RESOURCE_ID `
    --display-name=DISPLAY_NAME `
    --project=PROJECT_ID `
    --region=LOCATION `
    --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" `
    --enable-custom-service-account

Windows (cmd.exe)

gcloud ai persistent-resources create ^
    --persistent-resource-id=PERSISTENT_RESOURCE_ID ^
    --display-name=DISPLAY_NAME ^
    --project=PROJECT_ID ^
    --region=LOCATION ^
    --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" ^
    --enable-custom-service-account

Dovresti ricevere una risposta simile alla seguente:

Using endpoint [https://us-central1-aiplatform.googleapis.com/]
Operation to create PersistentResource [projects/PROJECT_NUMBER/locations/us-central1/persistentResources/mypersistentresource/operations/OPERATION_ID] is submitted successfully.

You can view the status of your PersistentResource create operation with the command

  $ gcloud ai operations describe projects/sample-project/locations/us-central1/operations/OPERATION_ID

Esempio di comando gcloud:

gcloud ai persistent-resources create \
    --persistent-resource-id=my-persistent-resource \
    --region=us-central1 \
    --resource-pool-spec="replica-count=4,machine-type=n1-standard-4"
    --enable-custom-service-account

Configurazioni `gcloud` avanzate

Se vuoi specificare opzioni di configurazione non disponibili negli esempi precedenti, puoi utilizzare il flag --config per specificare il percorso di un file config.yaml nell'ambiente locale contenente i campi di persistentResources. Ad esempio:

gcloud ai persistent-resources create \
    --persistent-resource-id=PERSISTENT_RESOURCE_ID \
    --project=PROJECT_ID \
    --region=LOCATION \
    --config=CONFIG
    --enable-custom-service-account

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Python.

Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Per creare una risorsa permanente che puoi utilizzare con l'esecuzione di una pipeline, imposta il parametro enable_custom_service_account su True nell'oggetto ResourceRuntimeSpec durante la creazione della risorsa permanente.

from google.cloud.aiplatform.preview import persistent_resource
from google.cloud.aiplatform_v1beta1.types.persistent_resource import ResourcePool
from google.cloud.aiplatform_v1beta1.types.machine_resources import MachineSpec

my_example_resource = persistent_resource.PersistentResource.create(
    persistent_resource_id='PERSISTENT_RESOURCE_ID',
    display_name='DISPLAY_NAME',
    resource_pools=[
        ResourcePool(
            machine_spec=MachineSpec(
                machine_type='MACHINE_TYPE'
            ),
            replica_count=REPLICA_COUNT
        )
    ],
    enable_custom_service_account=True,
)

Sostituisci quanto segue:

PERSISTENT_RESOURCE_ID: un ID univoco definito dall'utente per la risorsa permanente. L'ID deve contenere solo lettere minuscole, numeri e trattini (-). Il primo carattere deve essere una lettera minuscola e l'ultimo carattere deve essere una lettera minuscola o un numero.
DISPLAY_NAME: (Facoltativo) Il nome visualizzato della risorsa persistente.
MACHINE_TYPE: Il tipo di macchina virtuale (VM) da utilizzare. Per un elenco delle VM supportate, consulta Tipi di macchine. Questo campo corrisponde al campo machineSpec.machineType nel messaggio dell'API ResourcePool.
REPLICA_COUNT: il numero di repliche da creare quando viene creato questo pool di risorse.

REST

Per creare una risorsa PersistentResource che puoi associare a un'esecuzione della pipeline, invia una richiesta POST utilizzando il metodo persistentResources/create con il parametro enable_custom_service_account impostato su true nel corpo della richiesta.

Una risorsa permanente può avere uno o più pool di risorse. Puoi configurare ogni pool di risorse in modo che utilizzi un numero fisso di repliche o la scalabilità automatica.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

PROJECT_ID: l'ID progetto del Google Cloud progetto in cui vuoi creare la risorsa permanente.
LOCATION: la regione in cui vuoi creare la risorsa permanente. Per un elenco delle regioni supportate, consulta Disponibilità delle funzionalità.
PERSISTENT_RESOURCE_ID: un ID univoco definito dall'utente per la risorsa persistente. Deve iniziare con una lettera, terminare con una lettera o un numero e contenere solo lettere minuscole, numeri e trattini (-).
DISPLAY_NAME: (Facoltativo) Il nome visualizzato della risorsa permanente.
MACHINE_TYPE: Il tipo di macchina virtuale (VM) da utilizzare. Per un elenco delle VM supportate, consulta Tipi di macchine. Questo campo corrisponde al campo machineSpec.machineType nel messaggio dell'API ResourcePool.
REPLICA_COUNT: (Facoltativo) Il numero di repliche da creare per il pool di risorse, se non vuoi utilizzare la scalabilità automatica. Questo campo corrisponde al campo replicaCount nel messaggio dell'API ResourcePool. Devi specificare il numero di repliche se non specifichi i campi MIN_REPLICA_COUNT e MAX_REPLICA_COUNT.
MIN_REPLICA_COUNT: (Facoltativo) Il numero minimo di repliche se utilizzi la scalabilità automatica per il pool di risorse. Devi specificare sia MIN_REPLICA_COUNT sia MAX_REPLICA_COUNT per utilizzare la scalabilità automatica.
MAX_REPLICA_COUNT: (Facoltativo) Il numero massimo di repliche se utilizzi la scalabilità automatica per il pool di risorse. Devi specificare sia MIN_REPLICA_COUNT sia MAX_REPLICA_COUNT per utilizzare la scalabilità automatica.

Metodo HTTP e URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/persistentResources?persistent_resource_id=PERSISTENT_RESOURCE_ID

Corpo JSON della richiesta:

{
  "display_name": "DISPLAY_NAME",
  "resource_pools": [
    {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE"
      },
      "replica_count": REPLICA_COUNT,
      "autoscaling_spec": {
        "min_replica_count": MIN_REPLICA_COUNT,
        "max_replica_count": MAX_REPLICA_COUNT
      }
    }
  ],
  "resource_runtime_spec": {
    "service_account_spec": {
      "enable_custom_service_account": true
    }
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "display_name": "DISPLAY_NAME",
  "resource_pools": [
    {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE"
      },
      "replica_count": REPLICA_COUNT,
      "autoscaling_spec": {
        "min_replica_count": MIN_REPLICA_COUNT,
        "max_replica_count": MAX_REPLICA_COUNT
      }
    }
  ],
  "resource_runtime_spec": {
    "service_account_spec": {
      "enable_custom_service_account": true
    }
  }
}
EOF

Quindi esegui questo comando per inviare la richiesta REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/persistentResources?persistent_resource_id=PERSISTENT_RESOURCE_ID"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "display_name": "DISPLAY_NAME",
  "resource_pools": [
    {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE"
      },
      "replica_count": REPLICA_COUNT,
      "autoscaling_spec": {
        "min_replica_count": MIN_REPLICA_COUNT,
        "max_replica_count": MAX_REPLICA_COUNT
      }
    }
  ],
  "resource_runtime_spec": {
    "service_account_spec": {
      "enable_custom_service_account": true
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/persistentResources?persistent_resource_id=PERSISTENT_RESOURCE_ID" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/persistentResources/mypersistentresource/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreatePersistentResourceOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-02-08T21:17:15.009668Z",
      "updateTime": "2023-02-08T21:17:15.009668Z"
    }
  }
}

Crea un'esecuzione pipeline utilizzando la risorsa permanente

Per creare un job della pipeline, devi prima creare una specifica della pipeline. Una specifica della pipeline è un oggetto in memoria che crei convertendo una definizione di pipeline compilata.

Crea una specifica della pipeline

Segui queste istruzioni per creare una specifica della pipeline in memoria che puoi utilizzare per creare l'esecuzione della pipeline:

Definisci una pipeline e compilala in un file YAML. Per ulteriori informazioni su come definire e compilare una pipeline, vedi Creare una pipeline.
Utilizza il seguente esempio di codice per convertire il file YAML della pipeline compilata in una specifica della pipeline in memoria.
```
import yaml
with open("COMPILED_PIPELINE_PATH", "r") as stream:
  try:
    pipeline_spec = yaml.safe_load(stream)
    print(pipeline_spec)
  except yaml.YAMLError as exc:
    print(exc)
```
Sostituisci COMPILED_PIPELINE_PATH con il percorso locale del file YAML della pipeline compilata.

Crea un'esecuzione della pipeline

Utilizza il seguente esempio di codice Python per creare un'esecuzione della pipeline che utilizza la risorsa permanente:

# Import aiplatform and the appropriate API version v1beta1
from google.cloud import aiplatform, aiplatform_v1beta1
from google.cloud.aiplatform_v1beta1.types import pipeline_job as pipeline_job_types

# Initialize the Vertex SDK using PROJECT_ID and LOCATION
aiplatform.init(project='PROJECT_ID', location='LOCATION')

# Create the API Endpoint
client_options = {
    "api_endpoint": f"LOCATION-aiplatform.googleapis.com"
}

# Initialize the PipeLineServiceClient
client = aiplatform_v1beta1.PipelineServiceClient(client_options=client_options)

# Construct the runtime detail
pr_runtime_detail = pipeline_job_types.PipelineJob.RuntimeConfig.PersistentResourceRuntimeDetail(
    persistent_resource_name=(
        f"projects/PROJECT_NUMBER/"
        f"locations/LOCATION/"
        f"persistentResources/PERSISTENT_RESOURCE_ID"
    ),
    task_resource_unavailable_wait_time_ms=WAIT_TIME,
    task_resource_unavailable_timeout_behavior='TIMEOUT_BEHAVIOR',
)

# Construct the default runtime configuration block
default_runtime = pipeline_job_types.PipelineJob.RuntimeConfig.DefaultRuntime(
    persistent_resource_runtime_detail=pr_runtime_detail
)

# Construct the main runtime configuration
runtime_config = pipeline_job_types.PipelineJob.RuntimeConfig(
    gcs_output_directory='PIPELINE_ROOT',
    parameter_values={
        'project_id': 'PROJECT_ID'
    },
    default_runtime=default_runtime
)

# Construct the pipeline job object
pipeline_job = pipeline_job_types.PipelineJob(
    display_name='PIPELINE_DISPLAY_NAME',
    pipeline_spec=PIPELINE_SPEC,
    runtime_config=runtime_config,
)

# Construct the request
parent_path = f"projects/PROJECT_ID/locations/LOCATION"
request = aiplatform_v1beta1.CreatePipelineJobRequest(
    parent=parent_path,
    pipeline_job=pipeline_job,
)

# Make the API Call to create the pipeline job
response = client.create_pipeline_job(request=request)

# Construct the Google Cloud console link
job_id = response.name.split('/')[-1]
console_link = (
    f"https://console.cloud.google.com/vertex-ai/locations/LOCATION"
    f"/pipelines/runs/{job_id}"
    f"?project=PROJECT_ID"
)

# Print the Google Cloud console link to the pipeline run
print(f"View Pipeline Run in Google Cloud console: {console_link}")