Criar pipelines de treinamento

Os pipelines de treinamento permitem executar treinamentos personalizados de machine learning (ML) e criar automaticamente um recurso Model com base na saída do treinamento.

Antes de criar um pipeline

Antes de criar um pipeline de treinamento na Vertex AI, é preciso criar um aplicativo de treinamento em Python ou um contêiner personalizado para definir o código e as dependências de treinamento que você queremos executar a Vertex AI. Se você criar um aplicativo de treinamento em Python usando o TensorFlow, o scikit-learn ou o XGBoost, poderá usar nossos contêineres pré-criados para executar o código. Se você não tiver certeza de qual dessas opções escolher, consulte os requisitos do código de treinamento para saber mais.

Opções de pipeline de treinamento

Um pipeline de treinamento encapsula jobs de treinamento com etapas adicionais. Neste guia, explicamos dois pipelines de treinamento diferentes:

  • Iniciar um CustomJob e fazer upload do modelo resultante para a Vertex AI
  • Iniciar um job de ajuste de hiperparâmetros e fazer upload do modelo resultante para o Vertex AI.

Além disso, é possível usar conjuntos de dados gerenciados no pipeline de treinamento. Saiba mais sobre como configurar o pipeline de treinamento para usar um conjunto de dados gerenciado.

O que um CustomJob inclui

Ao criar um job personalizado, você especifica as configurações que a Vertex AI precisa executar no seu código de treinamento, incluindo:

Nos pools de workers, é possível especificar as seguintes configurações:

Se você quiser criar um job personalizado independente de um pipeline de treinamento da Vertex AI, consulte o guia sobre jobs personalizados.

Configurar o pipeline para usar um conjunto de dados gerenciado

No pipeline de treinamento, configure o job de treinamento personalizado ou o job de ajuste de hiperparâmetros para usar um conjunto de dados gerenciado. Com os conjuntos de dados gerenciados, é possível gerenciar os conjuntos de dados com os aplicativos e modelos de treinamento.

Para usar um conjunto de dados gerenciado no pipeline de treinamento:

  1. Crie o conjunto de dados.
  2. Atualize seu aplicativo de treinamento para usar um conjunto de dados gerenciado. Para mais informações, consulte Como a Vertex AI passa o conjunto de dados para seu aplicativo de treinamento.
  3. Especifique um conjunto de dados gerenciado ao criar o pipeline de treinamento. Por exemplo, se você criar seu pipeline de treinamento usando a API REST, especifique as configurações do conjunto de dados na seção inputDataConfig.

    É necessário criar o pipeline de treinamento na mesma região em que criou o conjunto de dados.

Para saber mais, consulte a Referência da API para TrainingPipeline.

Configurar o treinamento distribuído

No pipeline de treinamento, é possível configurar o job de treinamento personalizado ou o job de ajuste de hiperparâmetros para treinamento distribuído especificando vários pools de workers.

Todos os exemplos nesta página mostram jobs de treinamento de réplica única com um pool de workers. Para modificá-los no treinamento distribuído:

  • Use o primeiro pool de workers para configurar a réplica principal e defina a contagem de réplicas como 1.
  • Adicione mais pools de workers para configurar réplicas de workers, réplicas de servidores de parâmetros ou réplicas de avaliadores se o framework de machine learning for compatível com essas tarefas adicionais do cluster para treinamento distribuído.

Saiba mais sobre como usar o treinamento distribuído.

Job personalizado e upload de modelo

Este pipeline de treinamento encapsula um job personalizado com uma etapa adicional que facilita a implantação do modelo na Vertex AI após o treinamento. Esse pipeline de treinamento executa, principalmente, as seguintes tarefas:

  1. O pipeline de treinamento cria um recurso CustomJob. O job personalizado executa o aplicativo de treinamento usando os recursos de computação especificados.

  2. Após a conclusão do job personalizado, o pipeline de treinamento encontrará os artefatos de modelo criados pelo aplicativo de treinamento no diretório de saída especificado para o bucket do Cloud Storage. Ele usa esses artefatos para criar um recurso de modelo, que o configura para a implantação do modelo.

Há duas maneiras diferentes de definir o local dos artefatos do modelo:

  • Se você definir um baseOutputDirectory para o job de treinamento, verifique se o código de treinamento salva os artefatos do modelo no local, usando a variável de ambiente $AIP_MODEL_DIR definida pela Vertex AI. Após a conclusão do job de treinamento, a Vertex AI pesquisa os artefatos do modelo resultante em gs://BASE_OUTPUT_DIRECTORY/model.

  • Se você definir o campo modelToUpload.artifactUri, o pipeline de treinamento fará upload dos artefatos do modelo a partir desse URI. Defina esse campo se não tiver definido o baseOutputDirectory.

Se você especificar baseOutputDirectory e modelToUpload.artifactUri, a Vertex AII usará modelToUpload.artifactUri.

Para criar esse tipo de pipeline de treinamento:

Console

  1. No Console do Google Cloud, na seção "Vertex AI", acesse a página Pipelines de treinamento.

    Acessar pipelines de treinamento

  2. Clique em Criar para abrir o painel Treinar novo modelo.

  3. Na etapa Escolher método de treinamento, especifique as seguintes configurações:

    1. Se você quiser usar um conjunto de dados gerenciado para treinamento, especifique um conjunto de dados e um conjunto de anotações.

      Na lista suspensa Conjunto de dados, selecione Nenhum conjunto de dados gerenciado.

    2. Selecione Treinamento personalizado (avançado).

    Clique em Continuar.

  4. Na etapa Detalhes do modelo, escolha Treinar novo modelo ou Treinar nova versão. Se você selecionar "Treinar novo modelo", insira um nome para sua escolha, MODEL_NAME, para seu modelo. Clique em Continuar.

  5. Na etapa Contêiner de treinamento, especifique as seguintes configurações:

    1. Selecione se precisa usar um contêiner pré-criado ou um contêiner personalizado para treinamento.

    2. Dependendo do que você escolher, siga um destes procedimentos:

    3. No campo Diretório de saída do modelo, especifique o URI do Cloud Storage de um diretório em um bucket a que você tenha acesso. O conjunto de dados ainda não precisa existir.

      Esse valor é transmitido à Vertex AI no campo da API baseOutputDirectory, que define várias variáveis de ambiente que o aplicativo de treinamento pode acessar quando ele é executado.

      No final do treinamento, a Vertex AI procura artefatos de modelo em um subdiretório deste URI para criar um Model. Esse subdiretório está disponível para seu código de treinamento como a variável de ambiente AIP_MODEL_DIR.

      Quando você não usa o ajuste de hiperparâmetro, a Vertex AI espera encontrar artefatos de modelo em BASE_OUTPUT_DIRECTORY/model/.

    4. Opcional: no campo Arguments, é possível especificar argumentos para que a Vertex AI use quando começar a executar seu código de treinamento. O tamanho máximo de todos os argumentos combinados é de 100.000 caracteres. O comportamento desses argumentos varia de acordo com o tipo de contêiner que você está usando:

    Clique em Continuar.

  6. Na etapa Ajuste de hiperparâmetros, verifique se a caixa de seleção Ativar ajuste de hiperparâmetros não está marcada. Clique em Continuar.

  7. Na etapa Computação e preços, especifique as seguintes configurações:

    1. Na lista suspensa Região, selecione uma região compatível com o treinamento personalizado.

    2. Na seção Pool de worker 0, especifique recursos de computação que serão usados no treinamento.

      Se você especificar aceleradores, verifique se o tipo de acelerador escolhido está disponível na região selecionada.

      Se você quiser executar o treinamento distribuído, clique em Adicionar mais pools de workers e especifique um conjunto adicional de recursos de computação para cada um deles. que você quiser.

    Clique em Continuar.

  8. Na etapa Contêiner de treinamento, especifique as seguintes configurações:

    1. Indique se você quer usar um contêiner pré-criado ou um contêiner personalizado para exibir previsões do modelo treinado.

    2. Dependendo do que você escolher, siga um destes procedimentos:

    3. O campo Diretório do modelo contém o valor que você definiu anteriormente no campo Diretório de saída do modelo da etapa do Contêiner de treinamento. A alteração de qualquer um desses campos tem o mesmo efeito. Para saber mais sobre esse campo, consulte as instruções anteriores.

    4. Deixe os campos na seção Schemata de previsão em branco.

  9. Clique em Iniciar treinamento.

REST

Use o exemplo de código a seguir para criar um pipeline de treinamento usando o método create do recurso trainingPipeline.

Observação: se você quiser definir esse pipeline para criar uma nova versão de modelo, é possível adicionar o PARENT_MODEL ao campo trainingPipeline.

Para saber mais, consulte Controle de versão de modelo com o Vertex AI Model Registry.

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

  • LOCATION_ID: a região em que o código de treinamento é executado e o Model é armazenado.
  • PROJECT_ID: o ID do projeto
  • TRAINING_PIPELINE_NAME: obrigatório. Um nome de exibição do trainingPipeline.
  • Se o aplicativo de treinamento usar um conjunto de dados da Vertex AI, especifique o seguinte:
    • DATASET_ID: o ID do conjunto de dados.
    • ANNOTATIONS_FILTER: filtra o conjunto de dados pelas anotações especificadas.
    • ANNOTATION_SCHEMA_URI: filtra o conjunto de dados pelo URI do esquema de anotação especificado.
    • Use uma das opções a seguir para especificar como os itens de dados são divididos em conjuntos de treinamento, validação e teste.
      • Para dividir o conjunto de dados com base em frações que definem o tamanho de cada conjunto, especifique o seguinte:
        • TRAINING_FRACTION: a fração do conjunto de dados a ser usada para treinar o modelo.
        • VALIDATION_FRACTION: a fração do conjunto de dados a ser usada para validar o modelo.
        • TEST_FRACTION: a fração do conjunto de dados a ser usada para avaliar o modelo.
      • Para dividir o conjunto de dados com base em filtros, especifique o seguinte:
        • TRAINING_FILTER: filtra o conjunto de dados com os itens de dados a serem usados no treinamento do modelo.
        • VALIDATION_FILTER: filtra o conjunto de dados com os itens de dados a serem usados na validação do modelo.
        • TEST_FILTER: filtra o conjunto de dados com os itens de dados a serem usados para avaliar o modelo.
      • Para usar uma divisão predefinida, especifique o seguinte:
        • PREDEFINED_SPLIT_KEY: o nome da coluna a ser usada para dividir o conjunto de dados. Os valores aceitáveis nessa coluna incluem "training", "validation" e "test".
      • Para dividir o conjunto de dados com base no carimbo de data/hora nos itens de dados, especifique o seguinte:
        • TIMESTAMP_TRAINING_FRACTION: a fração do conjunto de dados a ser usada para treinar o modelo.
        • TIMESTAMP_VALIDATION_FRACTION: a fração do conjunto de dados a ser usada para validar o modelo.
        • TIMESTAMP_TEST_FRACTION: a fração do conjunto de dados a ser usada para avaliar o modelo.
        • TIMESTAMP_SPLIT_KEY: o nome da coluna de carimbo de data/hora a ser usada para dividir o conjunto de dados.
    • OUTPUT_URI_PREFIX: o local do Cloud Storage em que a Vertex AI exporta o conjunto de dados de treinamento, depois de ser dividido em conjuntos de treinamento, validação e teste.
  • Defina o job de treinamento personalizado:
    • MACHINE_TYPE: o tipo da máquina. Consulte os tipos de máquina disponíveis para treinamento.
    • ACCELERATOR_TYPE: opcional. O tipo de acelerador a ser anexado a cada teste.
    • ACCELERATOR_COUNT: opcional. O número de aceleradores a serem anexados a cada teste.
    • REPLICA_COUNT: o número de réplicas de worker a serem usadas em cada teste.
    • Se o aplicativo de treinamento for executado em um contêiner personalizado, especifique o seguinte:
      • CUSTOM_CONTAINER_IMAGE_URI: o URI de uma imagem de contêiner no Artifact Registry, do Container Registry ou do Docker Hub a ser executado em cada réplica de worker.
      • CUSTOM_CONTAINER_COMMAND: opcional. O comando que será invocado quando o contêiner for iniciado. Esse comando substitui o ponto de entrada padrão do contêiner.
      • CUSTOM_CONTAINER_ARGS: opcional. Argumentos a serem passados ao iniciar o contêiner. O tamanho máximo de todos os argumentos combinados é de 100.000 caracteres.
    • Se o aplicativo de treinamento for um pacote Python executado em um contêiner pré-criado, especifique o seguinte:
      • PYTHON_PACKAGE_EXECUTOR_IMAGE_URI: o URI da imagem do contêiner que executa o pacote Python fornecido. Consulte os contêineres pré-criados disponíveis para treinamento.
      • PYTHON_PACKAGE_URIS: o local do Cloud Storage dos arquivos do pacote do Python que são o programa de treinamento e os pacotes dependentes. O número máximo de URIs de pacote é 100.
      • PYTHON_MODULE: O nome do módulo Python que será executado após a instalação dos pacotes.
      • PYTHON_PACKAGE_ARGS: opcional. Argumentos da linha de comando a serem passados para o módulo Python. O tamanho máximo de todos os argumentos combinados é de 100.000 caracteres.
    • TIMEOUT: opcional. O tempo máximo de execução do job.
  • MODEL_NAME: um nome de exibição do modelo enviado (criado) pelo TrainingPipeline.
  • MODEL_DESCRIPTION: uma descrição para o modelo.
  • IMAGE_URI: o URI da imagem do contêiner a ser usado para executar previsões. Por exemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Use contêineres pré-criados ou contêineres personalizados.
  • modelToUpload.labels: qualquer conjunto de pares de chave-valor para organizar os modelos. Por exemplo:
    • "env": "prod"
    • "tier": "backend"
  • Especifique LABEL_NAME e LABEL_VALUE para todos os rótulos que você quiser aplicar a esse pipeline de treinamento.

Método HTTP e URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/trainingPipelines

Corpo JSON da solicitação:

{
  "displayName": "TRAINING_PIPELINE_NAME",
  "inputDataConfig": {
    "datasetId": DATASET_ID,
    "annotationsFilter": ANNOTATIONS_FILTER,
    "annotationSchemaUri": ANNOTATION_SCHEMA_URI,

    // Union field split can be only one of the following:
    "fractionSplit": {
      "trainingFraction": TRAINING_FRACTION,
      "validationFraction": VALIDATION_FRACTION,
      "testFraction": TEST_FRACTION
    },
    "filterSplit": {
      "trainingFilter": TRAINING_FILTER,
      "validationFilter": VALIDATION_FILTER,
      "testFilter": TEST_FILTER
    },
    "predefinedSplit": {
      "key": PREDEFINED_SPLIT_KEY
    },
    "timestampSplit": {
      "trainingFraction": TIMESTAMP_TRAINING_FRACTION,
      "validationFraction": TIMESTAMP_VALIDATION_FRACTION,
      "testFraction": TIMESTAMP_TEST_FRACTION,
      "key": TIMESTAMP_SPLIT_KEY
    }
    // End of list of possible types for union field split.
    "gcsDestination": {
      "outputUriPrefix": OUTPUT_URI_PREFIX
    }
  },
  "trainingTaskDefinition": "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml",
  "trainingTaskInputs": {
    "workerPoolSpecs": [
        {
          "machineSpec": {
            "machineType": MACHINE_TYPE,
            "acceleratorType": ACCELERATOR_TYPE,
            "acceleratorCount": ACCELERATOR_COUNT
          },
          "replicaCount": REPLICA_COUNT,

          // Union field task can be only one of the following:
          "containerSpec": {
            "imageUri": CUSTOM_CONTAINER_IMAGE_URI,
            "command": [
              CUSTOM_CONTAINER_COMMAND
            ],
            "args": [
              CUSTOM_CONTAINER_ARGS
            ]
          },
          "pythonPackageSpec": {
            "executorImageUri": PYTHON_PACKAGE_EXECUTOR_IMAGE_URI,
            "packageUris": [
              PYTHON_PACKAGE_URIS
            ],
            "pythonModule": PYTHON_MODULE,
            "args": [
              PYTHON_PACKAGE_ARGS
            ]
          }
          // End of list of possible types for union field task.
        }
      ],
      "scheduling": {
        "TIMEOUT": TIMEOUT
      }
    }
  },
  "modelToUpload": {
    "displayName": "MODEL_NAME",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    }
  },
  "labels": {
    LABEL_NAME_1": LABEL_VALUE_1,
    LABEL_NAME_2": LABEL_VALUE_2
  }
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/trainingPipelines"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/trainingPipelines" | Select-Object -Expand Content

A resposta contém informações sobre especificações, bem como o TRAININGPIPELINE_ID.

Java

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

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.

import com.google.cloud.aiplatform.v1.LocationName;
import com.google.cloud.aiplatform.v1.Model;
import com.google.cloud.aiplatform.v1.ModelContainerSpec;
import com.google.cloud.aiplatform.v1.PipelineServiceClient;
import com.google.cloud.aiplatform.v1.PipelineServiceSettings;
import com.google.cloud.aiplatform.v1.TrainingPipeline;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;

public class CreateTrainingPipelineCustomJobSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String displayName = "DISPLAY_NAME";
    String modelDisplayName = "MODEL_DISPLAY_NAME";
    String containerImageUri = "CONTAINER_IMAGE_URI";
    String baseOutputDirectoryPrefix = "BASE_OUTPUT_DIRECTORY_PREFIX";
    createTrainingPipelineCustomJobSample(
        project, displayName, modelDisplayName, containerImageUri, baseOutputDirectoryPrefix);
  }

  static void createTrainingPipelineCustomJobSample(
      String project,
      String displayName,
      String modelDisplayName,
      String containerImageUri,
      String baseOutputDirectoryPrefix)
      throws IOException {
    PipelineServiceSettings settings =
        PipelineServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (PipelineServiceClient client = PipelineServiceClient.create(settings)) {
      JsonObject jsonMachineSpec = new JsonObject();
      jsonMachineSpec.addProperty("machineType", "n1-standard-4");

      // A working docker image can be found at
      // gs://cloud-samples-data/ai-platform/mnist_tfrecord/custom_job
      // This sample image accepts a set of arguments including model_dir.
      JsonObject jsonContainerSpec = new JsonObject();
      jsonContainerSpec.addProperty("imageUri", containerImageUri);
      JsonArray jsonArgs = new JsonArray();
      jsonArgs.add("--model_dir=$(AIP_MODEL_DIR)");
      jsonContainerSpec.add("args", jsonArgs);

      JsonObject jsonJsonWorkerPoolSpec0 = new JsonObject();
      jsonJsonWorkerPoolSpec0.addProperty("replicaCount", 1);
      jsonJsonWorkerPoolSpec0.add("machineSpec", jsonMachineSpec);
      jsonJsonWorkerPoolSpec0.add("containerSpec", jsonContainerSpec);

      JsonArray jsonWorkerPoolSpecs = new JsonArray();
      jsonWorkerPoolSpecs.add(jsonJsonWorkerPoolSpec0);

      JsonObject jsonBaseOutputDirectory = new JsonObject();
      // The GCS location for outputs must be accessible by the project's AI Platform
      // service account.
      jsonBaseOutputDirectory.addProperty("output_uri_prefix", baseOutputDirectoryPrefix);

      JsonObject jsonTrainingTaskInputs = new JsonObject();
      jsonTrainingTaskInputs.add("workerPoolSpecs", jsonWorkerPoolSpecs);
      jsonTrainingTaskInputs.add("baseOutputDirectory", jsonBaseOutputDirectory);

      Value.Builder trainingTaskInputsBuilder = Value.newBuilder();
      JsonFormat.parser().merge(jsonTrainingTaskInputs.toString(), trainingTaskInputsBuilder);
      Value trainingTaskInputs = trainingTaskInputsBuilder.build();
      String trainingTaskDefinition =
          "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml";
      String imageUri = "gcr.io/cloud-aiplatform/prediction/tf-cpu.1-15:latest";
      ModelContainerSpec containerSpec =
          ModelContainerSpec.newBuilder().setImageUri(imageUri).build();
      Model modelToUpload =
          Model.newBuilder()
              .setDisplayName(modelDisplayName)
              .setContainerSpec(containerSpec)
              .build();
      TrainingPipeline trainingPipeline =
          TrainingPipeline.newBuilder()
              .setDisplayName(displayName)
              .setTrainingTaskDefinition(trainingTaskDefinition)
              .setTrainingTaskInputs(trainingTaskInputs)
              .setModelToUpload(modelToUpload)
              .build();
      LocationName parent = LocationName.of(project, location);
      TrainingPipeline response = client.createTrainingPipeline(parent, trainingPipeline);
      System.out.format("response: %s\n", response);
      System.out.format("Name: %s\n", response.getName());
    }
  }
}

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

Os exemplos a seguir mostram como usar o SDK do Vertex para Python para criar um pipeline de treinamento personalizado. Escolha se você pretende usar um contêiner personalizado ou um contêiner pré-criado para treinamento:

Contêiner pré-criado

Quando você usa o Vertex AI SDK para Python para criar um pipeline de treinamento que executa o código Python em um contêiner pré-criado, é possível fornecer o código de treinamento de uma das seguintes maneiras:

  • Especifique o URI de um pacote de distribuição de origem Python no Cloud Storage.

    Essa opção também está disponível ao criar um pipeline de treinamento sem usar o SDK do Vertex para Python.

  • Especifique o caminho para um script Python na máquina local. Antes de criar um pipeline de treinamento, o SDK do Vertex para Python empacota o script como uma distribuição de origem. Em seguida, ele é enviado ao bucket do Cloud Storage que você escolher.

    Essa opção só está disponível quando você usa o Vertex AI SDK para Python.

Para ver um exemplo de código para cada uma dessas opções, selecione a guia correspondente:

Pacote

O exemplo a seguir usa a classe CustomPythonPackageTrainingJob.

def create_training_pipeline_custom_package_job_sample(
    project: str,
    location: str,
    staging_bucket: str,
    display_name: str,
    python_package_gcs_uri: str,
    python_module_name: str,
    container_uri: str,
    model_serving_container_image_uri: str,
    dataset_id: Optional[str] = None,
    model_display_name: Optional[str] = None,
    args: Optional[List[Union[str, float, int]]] = None,
    replica_count: int = 1,
    machine_type: str = "n1-standard-4",
    accelerator_type: str = "ACCELERATOR_TYPE_UNSPECIFIED",
    accelerator_count: int = 0,
    training_fraction_split: float = 0.8,
    validation_fraction_split: float = 0.1,
    test_fraction_split: float = 0.1,
    sync: bool = True,
    tensorboard_resource_name: Optional[str] = None,
    service_account: Optional[str] = None,
):
    aiplatform.init(project=project, location=location, staging_bucket=staging_bucket)

    job = aiplatform.CustomPythonPackageTrainingJob(
        display_name=display_name,
        python_package_gcs_uri=python_package_gcs_uri,
        python_module_name=python_module_name,
        container_uri=container_uri,
        model_serving_container_image_uri=model_serving_container_image_uri,
    )

    # This example uses an ImageDataset, but you can use another type
    dataset = aiplatform.ImageDataset(dataset_id) if dataset_id else None

    model = job.run(
        dataset=dataset,
        model_display_name=model_display_name,
        args=args,
        replica_count=replica_count,
        machine_type=machine_type,
        accelerator_type=accelerator_type,
        accelerator_count=accelerator_count,
        training_fraction_split=training_fraction_split,
        validation_fraction_split=validation_fraction_split,
        test_fraction_split=test_fraction_split,
        sync=sync,
        tensorboard=tensorboard_resource_name,
        service_account=service_account,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    print(model.uri)
    return model

Script

O exemplo a seguir usa a classe CustomTrainingJob.

def create_training_pipeline_custom_job_sample(
    project: str,
    location: str,
    staging_bucket: str,
    display_name: str,
    script_path: str,
    container_uri: str,
    model_serving_container_image_uri: str,
    dataset_id: Optional[str] = None,
    model_display_name: Optional[str] = None,
    args: Optional[List[Union[str, float, int]]] = None,
    replica_count: int = 0,
    machine_type: str = "n1-standard-4",
    accelerator_type: str = "ACCELERATOR_TYPE_UNSPECIFIED",
    accelerator_count: int = 0,
    training_fraction_split: float = 0.8,
    validation_fraction_split: float = 0.1,
    test_fraction_split: float = 0.1,
    sync: bool = True,
    tensorboard_resource_name: Optional[str] = None,
    service_account: Optional[str] = None,
):
    aiplatform.init(project=project, location=location, staging_bucket=staging_bucket)

    job = aiplatform.CustomTrainingJob(
        display_name=display_name,
        script_path=script_path,
        container_uri=container_uri,
        model_serving_container_image_uri=model_serving_container_image_uri,
    )

    # This example uses an ImageDataset, but you can use another type
    dataset = aiplatform.ImageDataset(dataset_id) if dataset_id else None

    model = job.run(
        dataset=dataset,
        model_display_name=model_display_name,
        args=args,
        replica_count=replica_count,
        machine_type=machine_type,
        accelerator_type=accelerator_type,
        accelerator_count=accelerator_count,
        training_fraction_split=training_fraction_split,
        validation_fraction_split=validation_fraction_split,
        test_fraction_split=test_fraction_split,
        sync=sync,
        tensorboard=tensorboard_resource_name,
        service_account=service_account,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    print(model.uri)
    return model

Contêiner personalizado

O exemplo a seguir usa a classe CustomContainerTrainingJob.

def create_training_pipeline_custom_container_job_sample(
    project: str,
    location: str,
    staging_bucket: str,
    display_name: str,
    container_uri: str,
    model_serving_container_image_uri: str,
    dataset_id: Optional[str] = None,
    model_display_name: Optional[str] = None,
    args: Optional[List[Union[str, float, int]]] = None,
    replica_count: int = 1,
    machine_type: str = "n1-standard-4",
    accelerator_type: str = "ACCELERATOR_TYPE_UNSPECIFIED",
    accelerator_count: int = 0,
    training_fraction_split: float = 0.8,
    validation_fraction_split: float = 0.1,
    test_fraction_split: float = 0.1,
    sync: bool = True,
    tensorboard_resource_name: Optional[str] = None,
    service_account: Optional[str] = None,
):
    aiplatform.init(project=project, location=location, staging_bucket=staging_bucket)

    job = aiplatform.CustomContainerTrainingJob(
        display_name=display_name,
        container_uri=container_uri,
        model_serving_container_image_uri=model_serving_container_image_uri,
    )

    # This example uses an ImageDataset, but you can use another type
    dataset = aiplatform.ImageDataset(dataset_id) if dataset_id else None

    model = job.run(
        dataset=dataset,
        model_display_name=model_display_name,
        args=args,
        replica_count=replica_count,
        machine_type=machine_type,
        accelerator_type=accelerator_type,
        accelerator_count=accelerator_count,
        training_fraction_split=training_fraction_split,
        validation_fraction_split=validation_fraction_split,
        test_fraction_split=test_fraction_split,
        sync=sync,
        tensorboard=tensorboard_resource_name,
        service_account=service_account,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    print(model.uri)
    return model

Job de ajuste de hiperparâmetros e upload de modelo

Este pipeline de treinamento encapsula um job de ajuste de hiperparâmetros com uma etapa adicional que facilita a implantação do modelo na Vertex AI após o treinamento. Esse pipeline de treinamento executa, principalmente, as seguintes tarefas:

  1. O pipeline de treinamento cria um recurso de job de ajuste de hiperparâmetros. O job de ajuste de hiperparâmetros cria vários testes. Para cada teste, um job personalizado executa o aplicativo de treinamento usando os recursos de computação e os hiperparâmetros especificados.

  2. Após a conclusão do job de ajuste de hiperparâmetros, o pipeline de treinamento encontrará os artefatos do modelo do melhor teste no diretório de saída (baseOutputDirectory) que você especificou para o bucket do Cloud Storage. O pipeline de treinamento usa esses artefatos para criar um recurso de modelo que configura a implantação do modelo.

Para este pipeline de treinamento, você precisa especificar um baseOutputDirectory em que a Vertex AI pesquisa os artefatos do modelo a partir da melhor avaliação.

Os jobs de ajuste de hiperparâmetros têm configurações adicionais a serem definidas. Saiba mais sobre as configurações para HyperparameterTuningJob.

REST

Use o exemplo de código a seguir para criar um pipeline de treinamento usando o método create do recurso trainingPipeline.

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

  • LOCATION_ID: a região do seu projeto.
  • PROJECT_ID: o ID do projeto
  • TRAINING_PIPELINE_NAME: obrigatório. Um nome de exibição do trainingPipeline.
  • Se o aplicativo de treinamento usar um conjunto de dados da Vertex AI, especifique o seguinte:
    • DATASET_ID: o ID do conjunto de dados.
    • ANNOTATIONS_FILTER: filtra o conjunto de dados pelas anotações especificadas.
    • ANNOTATION_SCHEMA_URI: filtra o conjunto de dados pelo URI do esquema de anotação especificado.
    • Use uma das opções a seguir para especificar como os itens de dados são divididos em conjuntos de treinamento, validação e teste.
      • Para dividir o conjunto de dados com base em frações que definem o tamanho de cada conjunto, especifique o seguinte:
        • TRAINING_FRACTION: a fração do conjunto de dados a ser usada para treinar o modelo.
        • VALIDATION_FRACTION: a fração do conjunto de dados a ser usada para validar o modelo.
        • TEST_FRACTION: a fração do conjunto de dados a ser usada para avaliar o modelo.
      • Para dividir o conjunto de dados com base em filtros, especifique o seguinte:
        • TRAINING_FILTER: filtra o conjunto de dados com os itens de dados a serem usados no treinamento do modelo.
        • VALIDATION_FILTER: filtra o conjunto de dados com os itens de dados a serem usados na validação do modelo.
        • TEST_FILTER: filtra o conjunto de dados com os itens de dados a serem usados para avaliar o modelo.
      • Para usar uma divisão predefinida, especifique o seguinte:
        • PREDEFINED_SPLIT_KEY: o nome da coluna a ser usada para dividir o conjunto de dados. Os valores aceitáveis nessa coluna incluem "training", "validation" e "test".
      • Para dividir o conjunto de dados com base no carimbo de data/hora nos itens de dados, especifique o seguinte:
        • TIMESTAMP_TRAINING_FRACTION: a fração do conjunto de dados a ser usada para treinar o modelo.
        • TIMESTAMP_VALIDATION_FRACTION: a fração do conjunto de dados a ser usada para validar o modelo.
        • TIMESTAMP_TEST_FRACTION: a fração do conjunto de dados a ser usada para avaliar o modelo.
        • TIMESTAMP_SPLIT_KEY: o nome da coluna de carimbo de data/hora a ser usada para dividir o conjunto de dados.
    • OUTPUT_URI_PREFIX: o local do Cloud Storage em que a Vertex AI exporta o conjunto de dados de treinamento, depois de dividi-lo em conjuntos de treinamento, validação e teste.
  • Especifique o job de ajuste de hiperparâmetros:
    • Especifique as métricas:
      • METRIC_ID: o nome desta métrica.
      • METRIC_GOAL: a meta desta métrica. Pode ser MAXIMIZE ou MINIMIZE.
    • Especifique os hiperparâmetros:
      • PARAMETER_ID: o nome desse hiperparâmetro.
      • PARAMETER_SCALE: opcional. Como o parâmetro deve ser dimensionado. Deixe indefinido para parâmetros CATEGÓRICOS. Pode ser UNIT_LINEAR_SCALE, UNIT_LOG_SCALE, UNIT_REVERSE_LOG_SCALE ou SCALE_TYPE_UNSPECIFIED
      • Se o tipo de hiperparâmetro for DOUBLE, especifique os valores mínimo (DOUBLE_MIN_VALUE) e máximo (DOUBLE_MAX_VALUE) para ele.
      • Se o tipo de hiperparâmetro for INTEGER, especifique os valores mínimo (INTEGER_MIN_VALUE) e máximo (INTEGER_MAX_VALUE) para ele.
      • Se o tipo desse hiperparâmetro for COTEGORICAL, especifique os valores aceitáveis (CATEGORICAL_VALUES) como uma matriz de strings.
      • Se o tipo desse hiperparâmetro for DISCRETE, especifique os valores aceitáveis (DISCRETE_VALUES) como uma matriz de números.
    • ALGORITHM: opcional. O algoritmo de pesquisa a ser usado neste job de ajuste de hiperparâmetro. Pode ser ALGORITHM_UNSPECIFIED, GRID_SEARCH ou RANDOM_SEARCH.
    • MAX_TRIAL_COUNT: o número máximo de testes a serem executados neste job.
    • PARALLEL_TRIAL_COUNT: o número máximo de testes que podem ser executados em paralelo.
    • MAX_FAILED_TRIAL_COUNT: o número de jobs que podem falhar antes que o job de ajuste de hiperparâmetros falhe.
    • Defina o job de treinamento personalizado da avaliação:
      • MACHINE_TYPE: o tipo da máquina. Consulte os tipos de máquina disponíveis para treinamento.
      • ACCELERATOR_TYPE: opcional. O tipo de acelerador a ser anexado a cada teste.
      • ACCELERATOR_COUNT: opcional. O número de aceleradores a serem anexados a cada teste.
      • REPLICA_COUNT: o número de réplicas de worker a serem usadas em cada teste.
      • Se o aplicativo de treinamento for executado em um contêiner personalizado, especifique o seguinte:
        • CUSTOM_CONTAINER_IMAGE_URI: o URI de uma imagem de contêiner no Artifact Registry, do Container Registry ou do Docker Hub a ser executado em cada réplica de worker.
        • CUSTOM_CONTAINER_COMMAND: opcional. O comando que será invocado quando o contêiner for iniciado. Esse comando substitui o ponto de entrada padrão do contêiner.
        • CUSTOM_CONTAINER_ARGS: opcional. Argumentos a serem passados ao iniciar o contêiner.
      • Se o aplicativo de treinamento for um pacote Python executado em um contêiner pré-criado, especifique o seguinte:
        • PYTHON_PACKAGE_EXECUTOR_IMAGE_URI: o URI da imagem do contêiner que executa o pacote Python fornecido. Consulte os contêineres pré-criados disponíveis para treinamento.
        • PYTHON_PACKAGE_URIS: o local do Cloud Storage dos arquivos do pacote do Python que são o programa de treinamento e os pacotes dependentes. O número máximo de URIs de pacote é 100.
        • PYTHON_MODULE: o nome do módulo Python que será executado após a instalação dos pacotes.
        • PYTHON_PACKAGE_ARGS: opcional. Argumentos da linha de comando a serem passados para o módulo Python.
    • Saiba mais sobre as opções de programação de jobs.
    • TIMEOUT: opcional. O tempo máximo de execução para cada avaliação.
    • Especifique LABEL_NAME e LABEL_VALUE para todos os rótulos que você quiser aplicar a esse job de ajuste de hiperparâmetros.
  • MODEL_NAME: um nome de exibição do modelo enviado (criado) pelo TrainingPipeline.
  • MODEL_DESCRIPTION: opcional. Uma descrição do modelo.
  • PREDICTION_IMAGE_URI: obrigatório. Especifique uma das opções a seguir:
  • modelToUpload.labels: opcional. Qualquer conjunto de pares de chave-valor para organizar os modelos. Por exemplo:
    • "env": "prod"
    • "tier": "backend"
  • Especifique LABEL_NAME e LABEL_VALUE para todos os rótulos que você quiser aplicar a esse pipeline de treinamento.

Método HTTP e URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/trainingPipelines

Corpo JSON da solicitação:

{
  "displayName": "TRAINING_PIPELINE_NAME",
  "inputDataConfig": {
    "datasetId": DATASET_ID,
    "annotationsFilter": ANNOTATIONS_FILTER,
    "annotationSchemaUri": ANNOTATION_SCHEMA_URI,

    // Union field split can be only one of the following:
    "fractionSplit": {
      "trainingFraction": TRAINING_FRACTION,
      "validationFraction": VALIDATION_FRACTION,
      "testFraction": TEST_FRACTION
    },
    "filterSplit": {
      "trainingFilter": TRAINING_FILTER,
      "validationFilter": VALIDATION_FILTER,
      "testFilter": TEST_FILTER
    },
    "predefinedSplit": {
      "key": PREDEFINED_SPLIT_KEY
    },
    "timestampSplit": {
      "trainingFraction": TIMESTAMP_TRAINING_FRACTION,
      "validationFraction": TIMESTAMP_VALIDATION_FRACTION,
      "testFraction": TIMESTAMP_TEST_FRACTION,
      "key": TIMESTAMP_SPLIT_KEY
    }
    // End of list of possible types for union field split.
    "gcsDestination": {
      "outputUriPrefix": OUTPUT_URI_PREFIX
    }
  },
  "trainingTaskDefinition": "gs://google-cloud-aiplatform/schema/trainingjob/definition/hyperparameter_tuning_task_1.0.0.yaml",
  "trainingTaskInputs": {
    "studySpec": {
    "metrics": [
      {
        "metricId": METRIC_ID,
        "goal": METRIC_GOAL
      }
    ],
    "parameters": [
      {
        "parameterId": PARAMETER_ID,
        "scaleType": PARAMETER_SCALE,

        // Union field parameter_value_spec can be only one of the following:
        "doubleValueSpec": {
            "minValue": DOUBLE_MIN_VALUE,
            "maxValue": DOUBLE_MAX_VALUE
        },
        "integerValueSpec": {
            "minValue": INTEGER_MIN_VALUE,
            "maxValue": INTEGER_MAX_VALUE
        },
        "categoricalValueSpec": {
            "values": [
              CATEGORICAL_VALUES
            ]
        },
        "discreteValueSpec": {
            "values": [
              DISCRETE_VALUES
            ]
        }
        // End of list of possible types for union field parameter_value_spec.
      }
    ],
    "ALGORITHM": ALGORITHM
  },
  "maxTrialCount": MAX_TRIAL_COUNT,
  "parallelTrialCount": PARALLEL_TRIAL_COUNT,
  "maxFailedTrialCount": MAX_FAILED_TRIAL_COUNT,
  "trialJobSpec": {
      "workerPoolSpecs": [
        {
          "machineSpec": {
            "machineType": MACHINE_TYPE,
            "acceleratorType": ACCELERATOR_TYPE,
            "acceleratorCount": ACCELERATOR_COUNT
          },
          "replicaCount": REPLICA_COUNT,

          // Union field task can be only one of the following:
          "containerSpec": {
            "imageUri": CUSTOM_CONTAINER_IMAGE_URI,
            "command": [
              CUSTOM_CONTAINER_COMMAND
            ],
            "args": [
              CUSTOM_CONTAINER_ARGS
            ]
          },
          "pythonPackageSpec": {
            "executorImageUri": PYTHON_PACKAGE_EXECUTOR_IMAGE_URI,
            "packageUris": [
              PYTHON_PACKAGE_URIS
            ],
            "pythonModule": PYTHON_MODULE,
            "args": [
              PYTHON_PACKAGE_ARGS
            ]
          }
          // End of list of possible types for union field task.
        }
      ],
      "scheduling": {
        "TIMEOUT": TIMEOUT
      }
    },
    "labels": {
      LABEL_NAME_1": LABEL_VALUE_1,
      LABEL_NAME_2": LABEL_VALUE_2
    }
  },
  "modelToUpload": {
    "displayName": "MODEL_NAME",
    "description": "MODEL_DESCRIPTION",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "PREDICTION_IMAGE_URI"
    }
  },
  "labels": {
    LABEL_NAME_1": LABEL_VALUE_1,
    LABEL_NAME_2": LABEL_VALUE_2
  }
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/trainingPipelines"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/trainingPipelines" | Select-Object -Expand Content

A resposta contém informações sobre especificações, bem como o TRAININGPIPELINE_ID.

Monitorar o treinamento

Para visualizar os logs de treinamento faça o seguinte:

  1. No Console do Google Cloud, na seção "Vertex AI", acesse a página Treinamento.

    Acesse a página de treinamento

  2. Clique no nome do seu job para acessar a página do job personalizado.

  3. Clique em Ver registros.

Também é possível usar um shell interativo para inspecionar os contêineres de treinamento enquanto o pipeline de treinamento está em execução.

Ver o modelo treinado

Quando o pipeline de treinamento personalizado for concluído, será possível encontrar o modelo treinado no Console do Google Cloud, na seção "Vertex AI", na página Modelos.

Acessar a página de modelos

A seguir