Configurar uma execução de pipeline em um recurso permanente

Um recurso permanente da Vertex AI é um cluster de longa duração que pode ser usado para executar jobs de treinamento personalizados e execuções de pipeline. Ao usar um recurso persistente para uma execução de pipeline, você pode garantir a disponibilidade de recursos de computação e reduzir o tempo de inicialização da tarefa do pipeline. Os recursos permanentes oferecem suporte a todas as VMs e GPUs que têm suporte para jobs de treinamento personalizados. Saiba mais sobre recursos persistentes.

Nesta página, você aprende as seguintes ações com relação à verificação de tempo de atividade:

Antes de começar

Antes de criar uma execução de pipeline com um recurso persistente, é necessário concluir os pré-requisitos a seguir.

Definir e compilar um pipeline

Defina seu pipeline e compile a definição do pipeline em um arquivo YAML. Para mais informações sobre como definir e compilar um pipeline, consulte Criar um pipeline.

Papéis do IAM obrigatórios

Para receber a permissão necessária a fim de excluir um recurso permanente, peça ao administrador para conceder a você o papel IAM de Administrador da Vertex AI (roles/aiplatform.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão aiplatform.persistentResources.create, que é necessária para excluir um recurso permanente.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Criar um recurso persistente

Use os exemplos a seguir para criar um recurso permanente que possa ser associado a uma execução de pipeline. Para mais informações sobre a criação de recursos persistentes, consulte Criar um recurso persistente.

gcloud

Para criar um recurso permanente que possa ser associado a uma execução de pipeline, use o comando gcloud ai persistent-resources create com a flag --enable-custom-service-account.

Um recurso permanente pode ter um ou mais pools de recursos. Para criar vários pools de recursos em um recurso persistente, especifique várias sinalizações --resource-pool-spec.

É possível especificar todas as configurações do pool de recursos como parte da linha de comando ou usar a sinalização --config para especificar o caminho para um arquivo YAML que contenha as configurações.

Antes de usar os dados do comando abaixo, faça estas substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud em que você quer criar o recurso permanente.
  • LOCATION: a região em que você quer criar o recurso permanente. Para uma lista de regiões com suporte, consulte Disponibilidade do recurso.
  • PERSISTENT_RESOURCE_ID: o ID do recurso permanente.
  • DISPLAY_NAME: opcional. O nome de exibição do recurso permanente.
  • MACHINE_TYPE: o tipo de máquina virtual (VM) a ser usado. Para uma lista de VMs com suporte, consulte Tipos de máquina. Esse campo corresponde ao machineSpec.machineType na mensagem da API ResourcePool.
  • REPLICA_COUNT: opcional. O número de réplicas a serem criadas para o pool de recursos, se você não quiser usar o escalonamento automático. Esse campo corresponde ao replicaCount na mensagem da API ResourcePool. É necessário especificar a contagem de réplicas se você não especificar os campos MIN_REPLICA_COUNT e MAX_REPLICA_COUNT.
  • MIN_REPLICA_COUNT: opcional. O número mínimo de réplicas se você estiver usando o escalonamento automático para o pool de recursos. É necessário especificar MIN_REPLICA_COUNT e MAX_REPLICA_COUNT para usar o escalonamento automático.
  • MAX_REPLICA_COUNT: opcional. O número máximo de réplicas se você estiver usando o escalonamento automático para o pool de recursos. É necessário especificar MIN_REPLICA_COUNT e MAX_REPLICA_COUNT para usar o escalonamento automático.
  • CONFIG: caminho para o arquivo de configuração YAML do recurso permanente, que contém uma lista de especificações ResourcePool. Se uma opção for especificada no arquivo de configuração e nos argumentos da linha de comando, os argumentos da linha de comando vão substituir o arquivo de configuração. As chaves com sublinhados são consideradas inválidas.

    Exemplo de arquivo de configuração YAML:

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

Execute o seguinte comando:

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

Você receberá uma resposta semelhante a esta:

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 exemplo:

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

Configurações gcloud avançadas

Se você quiser especificar opções de configuração que não estejam disponíveis nos exemplos anteriores, use a sinalização --config para especificar o caminho para um arquivo config.yaml no ambiente local que contém os campos de persistentResources. Exemplo:

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 testar essa amostra, siga as instruções de configuração para Python Guia de início rápido da Vertex AI: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Para criar um recurso permanente que possa ser usado com uma execução de pipeline, defina o parâmetro enable_custom_service_account como True no objeto ResourceRuntimeSpec ao criar o recurso permanente.

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

Substitua:

  • PERSISTENT_RESOURCE_ID: o ID do recurso permanente.
  • DISPLAY_NAME: opcional. O nome de exibição do recurso persistente.
  • MACHINE_TYPE: o tipo de máquina virtual (VM) a ser usado. Para uma lista de VMs com suporte, consulte Tipos de máquina. Esse campo corresponde ao machineSpec.machineType na mensagem da API ResourcePool.
  • REPLICA_COUNT: o número de réplicas a serem criadas ao criar este pool de recursos.

REST

Para criar um recurso PersistentResource que possa ser associado a uma execução de pipeline, envie uma solicitação POST usando o método persistentResources/create com o parâmetro enable_custom_service_account definido como true no corpo da solicitação.

Um recurso permanente pode ter um ou mais pools de recursos. É possível configurar cada pool de recursos para usar um número fixo de réplicas ou o escalonamento automático.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud em que você quer criar o recurso permanente.
  • LOCATION: a região em que você quer criar o recurso permanente. Para uma lista de regiões com suporte, consulte Disponibilidade do recurso.
  • PERSISTENT_RESOURCE_ID: o ID do recurso permanente.
  • DISPLAY_NAME: opcional. O nome de exibição do recurso permanente.
  • MACHINE_TYPE: o tipo de máquina virtual (VM) a ser usado. Para uma lista de VMs com suporte, consulte Tipos de máquina. Esse campo corresponde ao machineSpec.machineType na mensagem da API ResourcePool.
  • REPLICA_COUNT: opcional. O número de réplicas a serem criadas para o pool de recursos, se você não quiser usar o escalonamento automático. Esse campo corresponde ao replicaCount na mensagem da API ResourcePool. É necessário especificar a contagem de réplicas se você não especificar os campos MIN_REPLICA_COUNT e MAX_REPLICA_COUNT.
  • MIN_REPLICA_COUNT: opcional. O número mínimo de réplicas se você estiver usando o escalonamento automático para o pool de recursos. É necessário especificar MIN_REPLICA_COUNT e MAX_REPLICA_COUNT para usar o escalonamento automático.
  • MAX_REPLICA_COUNT: opcional. O número máximo de réplicas se você estiver usando o escalonamento automático para o pool de recursos. É necessário especificar MIN_REPLICA_COUNT e MAX_REPLICA_COUNT para usar o escalonamento automático.

Método 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 da solicitação:

{
  "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": {
    "enable_custom_service_account: true
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Criar uma execução de pipeline usando o recurso permanente

Use o exemplo de código abaixo para criar uma execução de pipeline que use o recurso persistente:

  job = aiplatform.PipelineJob(display_name = 'DISPLAY_NAME',
  template_path = 'COMPILED_PIPELINE_PATH',
  pipeline_root = 'PIPELINE_ROOT',
  project = 'PROJECT_ID',
  location = 'LOCATION',
  default_runtime = {
    "persistentResourceRuntimeDetail": {
    "persistentResourceName": "PERSISTENT_RESOURCE_ID",
    "taskResourceUnavailableWaitTimeMs": WAIT_TIME,
    "taskResourceUnavailableTimeoutBehavior": TIMEOUT_BEHAVIOR,
    }
  }

Substitua:

  • DISPLAY_NAME: o nome do pipeline. Ela aparece no console do Google Cloud.

  • COMPILED_PIPELINE_PATH: o caminho para o arquivo YAML do pipeline compilado. Pode ser um caminho local ou um URI do Google Cloud Storage.

  • PIPELINE_ROOT: especifique um URI do Cloud Storage para armazenar os artefatos da execução do pipeline.

  • PROJECT_ID: o projeto Google Cloud em que este pipeline é executado.

  • LOCATION: a região em que a execução do pipeline é executada. Para mais informações sobre as regiões em que a Vertex AI Pipelines está disponível, consulte o guia de locais da Vertex AI. Se você não definir esse parâmetro, o Vertex AI Pipelines vai usar o local padrão definido em aiplatform.init.

  • PERSISTENT_RESOURCE_ID: o ID do recurso permanente que você criou.

  • WAIT_TIME: o tempo em milissegundos para aguardar se o recurso persistente estiver indisponível.

  • TIMEOUT_BEHAVIOR: especifica o comportamento de fallback da tarefa do pipeline caso o WAIT_TIME seja excedido. Os valores possíveis incluem:

    • FAIL A tarefa do pipeline falha após exceder o tempo de espera.

    • FALL_BACK_TO_ON_DEMAND A tarefa do pipeline continua sendo executada usando os recursos de treinamento padrão da Vertex AI, sem usar o recurso persistente.

A seguir