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 deResourcePool
. - 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 deResourcePool
. 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ámetroenable_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 deResourcePool
. - 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 deResourcePool
. - 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 deResourcePool
. 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:
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.
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?
- Obtén información sobre cómo ejecutar una canalización.