Configurer une exécution de pipeline sur une ressource persistante

Une ressource persistante Gemini Enterprise Agent Platform est un cluster de longue durée que vous pouvez utiliser pour exécuter des jobs d'entraînement personnalisés et des exécutions de pipeline. En utilisant une ressource persistante pour une exécution de pipeline, vous pouvez garantir la disponibilité des ressources de calcul et réduire le temps de démarrage des tâches de pipeline. Les ressources persistantes sont compatibles avec toutes les VM et tous les GPU compatibles avec les jobs d'entraînement personnalisés. Pour en savoir plus sur les ressources persistantes, consultez Présentation des ressources persistantes.

Cette page vous explique comment :

Créer une ressource persistante
Créer une exécution de pipeline à l'aide de la ressource persistante

Avant de commencer

Avant de pouvoir créer une exécution de pipeline avec une ressource persistante, vous devez d'abord remplir les conditions préalables suivantes.

Définir et compiler un pipeline

Définissez votre pipeline puis compilez la définition du pipeline dans un fichier YAML. Pour en savoir plus sur la définition et la compilation d'un pipeline, consultez Créer un pipeline.

Rôles IAM requis

Pour obtenir l'autorisation dont vous avez besoin pour créer une ressource persistante, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Agent Platform (roles/aiplatform.admin) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation aiplatform.persistentResources.create, qui est nécessaire pour créer une ressource persistante.

Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer une ressource persistante

Utilisez les exemples suivants pour créer une ressource persistante que vous pouvez associer à une exécution de pipeline. Pour en savoir plus sur la création de ressources persistantes, consultez Créer une ressource persistante.

gcloud

Pour créer une ressource persistante que vous pouvez associer à une exécution de pipeline, utilisez la gcloud ai persistent-resources create commande avec l'option --enable-custom-service-account.

Une ressource persistante peut avoir un ou plusieurs pools de ressources. Pour créer plusieurs pools de ressources dans une ressource persistante, spécifiez plusieurs options --resource-pool-spec.

Vous pouvez spécifier toutes les configurations de pool de ressources dans la ligne de commande ou utiliser l'option --config pour spécifier le chemin d'accès à un fichier YAML contenant les configurations.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : ID du projet dans lequel vous souhaitez créer la ressource persistante. Google Cloud
LOCATION : région dans laquelle vous souhaitez créer la ressource persistante. Pour obtenir la liste des régions disponibles, consultez la section Disponibilité des fonctionnalités.
PERSISTENT_RESOURCE_ID : ID unique défini par l'utilisateur pour la ressource persistante. Il doit commencer par une lettre, se terminer par une lettre ou un chiffre, et ne contenir que des lettres minuscules, des chiffres et des traits d'union (-).
DISPLAY_NAME : facultatif. Nom à afficher de la ressource persistante.
MACHINE_TYPE : type de machine virtuelle (VM) à utiliser. Pour obtenir la liste des VM compatibles, consultez la section Types de machines. Ce champ correspond au machineSpec.machineType champ du ResourcePool message de l'API.
REPLICA_COUNT : facultatif. Nombre d'instances dupliquées à créer pour le pool de ressources si vous ne souhaitez pas utiliser l'autoscaling. Ce champ correspond au replicaCount champ du message de l'API ResourcePool. Vous devez spécifier le nombre d'instances dupliquées si vous ne spécifiez pas les champs MIN_REPLICA_COUNT et MAX_REPLICA_COUNT.
MIN_REPLICA_COUNT : facultatif. Nombre minimal d'instances dupliquées si vous utilisez l'autoscaling pour le pool de ressources. Vous devez spécifier à la fois MIN_REPLICA_COUNT et MAX_REPLICA_COUNT pour utiliser l'autoscaling.
MAX_REPLICA_COUNT : facultatif. Nombre maximal d'instances dupliquées si vous utilisez l'autoscaling pour le pool de ressources. Vous devez spécifier à la fois MIN_REPLICA_COUNT et MAX_REPLICA_COUNT pour utiliser l'autoscaling.
CONFIG : chemin d'accès au fichier de configuration YAML de la ressource persistante, contenant une liste de spécifications ResourcePool. Si une option est spécifiée à la fois dans le fichier de configuration et dans les arguments de ligne de commande, les arguments de ligne de commande prévalent sur le fichier de configuration. Notez que les clés avec des traits de soulignement ne sont pas valides.
Exemple de fichier de configuration YAML :
```
resourcePoolSpecs:
  machineSpec:
    machineType: n1-standard-4
  replicaCount: 1
    
```

Exécutez la commande suivante :

Linux, macOS ou 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

Vous devriez obtenir un résultat semblable à celui-ci :

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

Exemple de commande 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

Configurations `gcloud` avancées

Si vous souhaitez spécifier des options de configuration qui ne sont pas disponibles dans les exemples précédents, vous pouvez utiliser l'indicateur --config pour spécifier le chemin d'accès à un fichier config.yaml de votre environnement local contenant les champs persistentResources. Exemple :

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

Python

Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Pour créer une ressource persistante que vous pouvez utiliser avec une exécution de pipeline, définissez le enable_custom_service_account paramètre sur True dans l'objet ResourceRuntimeSpec lors de la création de la ressource persistante.

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,
)

Remplacez les éléments suivants :

PERSISTENT_RESOURCE_ID : ID unique défini par l'utilisateur pour la ressource persistante. L'ID ne doit contenir que des lettres minuscules, des chiffres et des traits d'union (-). Le premier caractère doit être une lettre minuscule et le dernier caractère doit être une lettre minuscule ou un chiffre.
DISPLAY_NAME : facultatif. Nom à afficher de la ressource persistante.
MACHINE_TYPE : type de machine virtuelle (VM) à utiliser. Pour obtenir la liste des VM compatibles, consultez la section Types de machines. Ce champ correspond au champ machineSpec.machineType du message de l'API ResourcePool.
REPLICA_COUNT : nombre d'instances dupliquées à créer lors de la création de ce pool de ressources.

REST

Pour créer une ressource PersistentResource que vous pouvez associer à une exécution de pipeline, envoyez une requête POST à l'aide de la persistentResources/create méthode avec le paramètre enable_custom_service_account défini sur true dans le corps de la requête.

Une ressource persistante peut avoir un ou plusieurs pools de ressources. Vous pouvez configurer chaque pool de ressources pour qu'il utilise un nombre fixe d'instances dupliquées ou l'autoscaling.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : ID du projet dans lequel vous souhaitez créer la ressource persistante. Google Cloud
LOCATION : région dans laquelle vous souhaitez créer la ressource persistante. Pour obtenir la liste des régions disponibles, consultez la section Disponibilité des fonctionnalités.
PERSISTENT_RESOURCE_ID : ID unique défini par l'utilisateur pour la ressource persistante. Il doit commencer par une lettre, se terminer par une lettre ou un chiffre, et ne contenir que des lettres minuscules, des chiffres et des traits d'union (-).
DISPLAY_NAME : facultatif. Nom à afficher de la ressource persistante.
MACHINE_TYPE : type de machine virtuelle (VM) à utiliser. Pour obtenir la liste des VM compatibles, consultez la section Types de machines. Ce champ correspond au machineSpec.machineType champ du ResourcePool message de l'API.
REPLICA_COUNT : facultatif. Nombre d'instances dupliquées à créer pour le pool de ressources si vous ne souhaitez pas utiliser l'autoscaling. Ce champ correspond au replicaCount champ du message de l'API ResourcePool. Vous devez spécifier le nombre d'instances dupliquées si vous ne spécifiez pas les champs MIN_REPLICA_COUNT et MAX_REPLICA_COUNT.
MIN_REPLICA_COUNT : facultatif. Nombre minimal d'instances dupliquées si vous utilisez l'autoscaling pour le pool de ressources. Vous devez spécifier à la fois MIN_REPLICA_COUNT et MAX_REPLICA_COUNT pour utiliser l'autoscaling.
MAX_REPLICA_COUNT : facultatif. Nombre maximal d'instances dupliquées si vous utilisez l'autoscaling pour le pool de ressources. Vous devez spécifier à la fois MIN_REPLICA_COUNT et MAX_REPLICA_COUNT pour utiliser l'autoscaling.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :

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

Exécutez ensuite la commande suivante pour envoyer votre requête 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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :

@'
{
  "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

Exécutez ensuite la commande suivante pour envoyer votre requête 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

Vous devriez recevoir une réponse JSON de ce type :

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

Créer une exécution de pipeline à l'aide de la ressource persistante

Pour créer un job de pipeline, vous devez d'abord créer une spécification de pipeline. Une spécification de pipeline est un objet en mémoire que vous créez en convertissant une définition de pipeline compilée.

Créer une spécification de pipeline

Suivez ces instructions pour créer une spécification de pipeline en mémoire que vous pouvez utiliser pour créer l'exécution de pipeline :

Définissez un pipeline et compilez-le dans un fichier YAML. Pour en savoir plus sur la définition et la compilation d'un pipeline, consultez Créer un pipeline.
Utilisez l'exemple de code suivant pour convertir le fichier YAML du pipeline compilé en spécification de pipeline en mémoire.
```
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)
```
Remplacez COMPILED_PIPELINE_PATH par le chemin d'accès local au fichier YAML du pipeline compilé.

Créer une exécution de pipeline

Utilisez l'exemple de code Python suivant pour créer une exécution de pipeline qui utilise la ressource persistante :

# 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}")