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 permanente para uma execução de pipeline, você ajuda a garantir a disponibilidade de recursos de computação e reduz o tempo de inicialização da tarefa do pipeline. Os recursos permanentes dão suporte a todas as VMs e GPUs compatíveis com jobs de treinamento personalizados. Para saber mais sobre recursos permanentes, consulte Visão geral de recursos permanentes.

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

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

Antes de começar

Antes de criar uma execução de pipeline com um recurso permanente, você precisa concluir os pré-requisitos a seguir.

Definir e compilar um pipeline

Defina seu pipeline e compile a definição dele 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 criar 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 permanente

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

gcloud

Para criar um recurso permanente que pode ser associado a uma execução de pipeline, use o gcloud ai persistent-resources create comando 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 flags --resource-pool-spec.

É possível especificar todas as configurações do pool de recursos como parte da linha de comando ou usar a flag --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 em que você quer criar o recurso permanente. Google Cloud
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: um ID exclusivo, definido pelo usuário para o recurso permanente. Ele precisa começar e terminar com uma letra ou número e conter apenas letras minúsculas, números e hífens (-).
DISPLAY_NAME: opcional. O nome de exibição do recurso permanente.
MACHINE_TYPE: o tipo de máquina virtual (VM) a ser usada. Para uma lista de VMs compatíveis, consulte Tipos de máquina. Esse campo corresponde ao machineSpec.machineType na ResourcePool mensagem da API.
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 tanto MIN_REPLICA_COUNT quanto 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 tanto MIN_REPLICA_COUNT quanto 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 substituirão o arquivo de configuração. Observe que 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 pode ser usado com uma execução de pipeline, defina o enable_custom_service_account parâmetro como True no objeto ResourceRuntimeSpec ao criar o recurso 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,
)

Substitua:

PERSISTENT_RESOURCE_ID: um ID exclusivo definido pelo usuário para o recurso permanente. O ID precisa conter apenas letras minúsculas, números e hífens (-). O primeiro caractere precisa ser uma letra minúscula e o último caractere precisa ser uma letra minúscula ou um número.
DISPLAY_NAME: opcional. O nome de exibição do recurso permanente.
MACHINE_TYPE: o tipo de máquina virtual (VM) a ser usada. Para uma lista de VMs compatíveis, 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 pode 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 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 em que você quer criar o recurso permanente. Google Cloud
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: um ID exclusivo, definido pelo usuário para o recurso permanente. Ele precisa começar e terminar com uma letra ou número e conter apenas letras minúsculas, números e hífens (-).
DISPLAY_NAME: opcional. O nome de exibição do recurso permanente.
MACHINE_TYPE: o tipo de máquina virtual (VM) a ser usada. Para uma lista de VMs compatíveis, consulte Tipos de máquina. Esse campo corresponde ao machineSpec.machineType na ResourcePool mensagem da API.
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 tanto MIN_REPLICA_COUNT quanto 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 tanto MIN_REPLICA_COUNT quanto 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": {
    "service_account_spec": {
      "enable_custom_service_account": true
    }
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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

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

Para criar um job de pipeline, primeiro é necessário criar uma especificação de pipeline. Uma especificação de pipeline é um objeto na memória que você cria convertendo uma definição de pipeline compilada.

Criar uma especificação de pipeline

Siga estas instruções para criar uma especificação de pipeline na memória que pode ser usada para criar a execução do pipeline:

Defina um pipeline e compile-o em um arquivo YAML. Para mais informações sobre como definir e compilar um pipeline, consulte Criar um pipeline.
Use o exemplo de código a seguir para converter o arquivo YAML do pipeline compilado em uma especificação de pipeline na memória.
```
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)
```
Substitua COMPILED_PIPELINE_PATH pelo caminho local para o arquivo YAML do pipeline compilado.

Criar uma execução de pipeline

Use o exemplo de código Python a seguir para criar uma execução de pipeline que usa o recurso 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}")