Configura una canalización que se ejecute en un recurso persistente

Un recurso persistente de Vertex AI es un clúster de larga duración que puedes usar para ejecutar trabajos de entrenamiento personalizados y ejecuciones de canalizaciones. Si usas un recurso persistente para una ejecución de canalización, puedes garantizar la disponibilidad del recurso de procesamiento y reducir el tiempo de inicio de la tarea de canalización. Los recursos persistentes admiten todas las VMs y GPU compatibles con los trabajos de entrenamiento personalizados. Para obtener más información sobre los recursos persistentes, consulta la Descripción general de los recursos persistentes.

Esta página te muestra cómo hacer lo siguiente:

Antes de comenzar

Antes de crear una ejecución de canalización con un recurso persistente, primero debes completar los siguientes requisitos previos.

Define y compila una canalización

Define tu canalización y, luego, compila la definición de la canalización en un archivo YAML. Para obtener más información sobre cómo definir y compilar una canalización, consulta Crea una canalización.

Roles de IAM obligatorios

Para obtener el permiso que necesitas para crear un recurso persistente, pídele a tu administrador que te otorgue el rol de IAM de administrador de Vertex AI (roles/aiplatform.admin) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso aiplatform.persistentResources.create, que se requiere para crear un recurso persistente.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Crea un recurso persistente

Usa los siguientes ejemplos para crear un recurso persistente que puedas asociar con una ejecución de canalización. Para obtener más información sobre cómo crear recursos persistentes, consulta Crea un recurso persistente.

gcloud

Para crear un recurso persistente que puedas asociar con una ejecución de canalización, usa el comando gcloud ai persistent-resources create junto con la marca --enable-custom-service-account.

Un recurso persistente puede tener uno o más grupos de recursos. Para crear varios grupos de recursos en un recurso persistente, especifica varias marcas --resource-pool-spec.

Puedes especificar todas las configuraciones del grupo de recursos como parte de la línea de comandos o usar la marca --config para especificar la ruta de acceso a un archivo YAML que contiene las configuraciones.

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud proyecto en el que deseas crear el recurso persistente.
  • LOCATION: la región en la que deseas crear el recurso persistente. Para obtener una lista de las regiones compatibles, consulta Disponibilidad de funciones.
  • PERSISTENT_RESOURCE_ID: Es un ID único definido por el usuario para el recurso persistente. Debe comenzar con una letra, terminar con una letra o un número, y contener solo letras en minúscula, números y guiones (-).
  • DISPLAY_NAME: Opcional Es el nombre visible del recurso persistente.
  • MACHINE_TYPE: Es el tipo de máquina virtual (VM) que se usará. Para obtener una lista de las VMs compatibles, consulta Tipos de máquinas. Este campo corresponde al campo machineSpec.machineType en el mensaje de la API de ResourcePool.
  • REPLICA_COUNT: Opcional Cantidad de réplicas que se crearán para el grupo de recursos si no deseas usar el ajuste de escala automático. Este campo corresponde al campo replicaCount en el mensaje de la API de ResourcePool. Debes especificar la cantidad de réplicas si no especificas los campos MIN_REPLICA_COUNT y MAX_REPLICA_COUNT.
  • MIN_REPLICA_COUNT: Opcional Es la cantidad mínima de réplicas si usas el ajuste de escala automático para el grupo de recursos. Debes especificar MIN_REPLICA_COUNT y MAX_REPLICA_COUNT para usar el ajuste de escala automático.
  • MAX_REPLICA_COUNT: Opcional Cantidad máxima de réplicas si usas el ajuste de escala automático para el grupo de recursos. Debes especificar MIN_REPLICA_COUNT y MAX_REPLICA_COUNT para usar el ajuste de escala automático.
  • CONFIG: Ruta de acceso al archivo de configuración YAML del recurso persistente, que contiene una lista de especificaciones de ResourcePool. Si se especifica una opción en el archivo de configuración y en los argumentos de la línea de comandos, los argumentos de la línea de comandos anulan el archivo de configuración. Ten en cuenta que las claves con guiones bajos se consideran no válidas.

    Archivo de configuración YAML de ejemplo:

    resourcePoolSpecs:
      machineSpec:
        machineType: n1-standard-4
      replicaCount: 1
        

Ejecuta el siguiente 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

Deberías recibir una respuesta similar a la que figura a continuación:

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

Comando gcloud de ejemplo

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

Configuraciones gcloud avanzadas

Si deseas especificar opciones de configuración que no están disponibles en los ejemplos anteriores, puedes usar la marca --config para especificar la ruta a un archivo config.yaml en tu entorno local que contiene los campos de persistentResources. Por ejemplo:

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Python.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

Para crear un recurso persistente que puedas usar con una ejecución de canalización, establece el parámetro enable_custom_service_account en True en el objeto ResourceRuntimeSpec mientras creas el recurso persistente.

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

Reemplaza lo siguiente:

  • PERSISTENT_RESOURCE_ID: Es un ID único definido por el usuario para el recurso persistente. El ID solo debe contener letras minúsculas, números y guiones (-). El primer carácter debe ser una letra minúscula y el último debe ser una letra minúscula o un número.
  • DISPLAY_NAME: Opcional Es el nombre visible del recurso persistente.
  • MACHINE_TYPE: Es el tipo de máquina virtual (VM) que se usará. Para obtener una lista de las VMs compatibles, consulta Tipos de máquinas. Este campo corresponde al campo machineSpec.machineType en el mensaje de la API de ResourcePool.
  • REPLICA_COUNT: Es la cantidad de réplicas que se crearán cuando se cree este grupo de recursos.

REST

Para crear un recurso PersistentResource que puedas asociar con una ejecución de canalización, envía una solicitud POST con el método persistentResources/create y el parámetro enable_custom_service_account establecido en true en el cuerpo de la solicitud.

Un recurso persistente puede tener uno o más grupos de recursos. Puedes configurar cada grupo de recursos para que use una cantidad fija de réplicas o el ajuste de escala automático.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud proyecto en el que deseas crear el recurso persistente.
  • LOCATION: la región en la que deseas crear el recurso persistente. Para obtener una lista de las regiones compatibles, consulta Disponibilidad de funciones.
  • PERSISTENT_RESOURCE_ID: Es un ID único definido por el usuario para el recurso persistente. Debe comenzar con una letra, terminar con una letra o un número, y contener solo letras en minúscula, números y guiones (-).
  • DISPLAY_NAME: Opcional Es el nombre visible del recurso persistente.
  • MACHINE_TYPE: Es el tipo de máquina virtual (VM) que se usará. Para obtener una lista de las VMs compatibles, consulta Tipos de máquinas. Este campo corresponde al campo machineSpec.machineType en el mensaje de la API de ResourcePool.
  • REPLICA_COUNT: Opcional Cantidad de réplicas que se crearán para el grupo de recursos si no deseas usar el ajuste de escala automático. Este campo corresponde al campo replicaCount en el mensaje de la API de ResourcePool. Debes especificar la cantidad de réplicas si no especificas los campos MIN_REPLICA_COUNT y MAX_REPLICA_COUNT.
  • MIN_REPLICA_COUNT: Opcional Es la cantidad mínima de réplicas si usas el ajuste de escala automático para el grupo de recursos. Debes especificar MIN_REPLICA_COUNT y MAX_REPLICA_COUNT para usar el ajuste de escala automático.
  • MAX_REPLICA_COUNT: Opcional Cantidad máxima de réplicas si usas el ajuste de escala automático para el grupo de recursos. Debes especificar MIN_REPLICA_COUNT y MAX_REPLICA_COUNT para usar el ajuste de escala automático.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 una ejecución de canalización con el recurso persistente

Para crear un trabajo de canalización, primero debes crear una especificación de canalización. Una especificación de canalización es un objeto en memoria que se crea convirtiendo una definición de canalización compilada.

Crea una especificación de canalización

Sigue estas instrucciones para crear una especificación de canalización en la memoria que puedas usar para crear la ejecución de la canalización:

  1. Define una canalización y compílala en un archivo YAML. Para obtener más información sobre cómo definir y compilar una canalización, consulta Crea una canalización.

  2. Usa la siguiente muestra de código para convertir el archivo YAML de la canalización compilada en una especificación de canalización en 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)
    

    Reemplaza COMPILED_PIPELINE_PATH por la ruta de acceso local a tu archivo YAML de la canalización compilada.

Crea una ejecución de canalización

Usa la siguiente muestra de código de Python para crear una ejecución de canalización que use el recurso persistente:

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el proyecto Google Cloud en el que se ejecuta la canalización.

  • LOCATION: Es la región en la que se ejecuta la canalización. Para obtener más información sobre las regiones en las que está disponible Vertex AI Pipelines, consulta la guía de ubicaciones de Vertex AI. Si no configuras este parámetro, Vertex AI Pipelines usa la ubicación predeterminada establecida en aiplatform.init.

  • PERSISTENT_RESOURCE_ID: Es el ID del recurso persistente que creaste.

  • PROJECT_NUMBER: Es el número de tu proyecto Google Cloud. Es diferente del ID del proyecto. Puedes encontrar el número de proyecto en la página Configuración del proyecto de la Google Cloud consola.

  • COMPILED_PIPELINE_PATH: Es la ruta de acceso al archivo YAML de canalización compilado. Puede ser una ruta local o un URI de Cloud Storage.

  • WAIT_TIME: Es el tiempo en milisegundos que se debe esperar si el recurso persistente no está disponible.

  • TIMEOUT_BEHAVIOR: Es el comportamiento alternativo de la tarea de canalización en caso de que se supere el valor de WAIT_TIME. Entre los valores posibles, se incluyen los siguientes:

    • FAIL La tarea de la canalización falla después de exceder el tiempo de espera.

    • FALL_BACK_TO_ON_DEMAND La tarea de la canalización sigue ejecutándose con los recursos de entrenamiento predeterminados de Vertex AI, sin usar el recurso persistente.

  • PIPELINE_ROOT: Es la ruta de acceso a un URI de Cloud Storage para almacenar los artefactos de la ejecución de tu canalización.

  • PIPELINE_DISPLAY_NAME: Es el nombre de la ejecución de la canalización. La longitud máxima de un nombre visible es de 128 caracteres UTF-8.

  • PIPELINE_SPEC: Es la especificación de la canalización que creaste en Crea una especificación de canalización.

¿Qué sigue?