Como rotular e filtrar recursos

Nesta página, explicamos como adicionar rótulos e usá-los para organizar e filtrar seus recursos.

Visão geral dos rótulos

É possível adicionar rótulos aos jobs (em inglês) do AI Platform Training para organizá-los em categorias ao visualizar ou monitorar os recursos.

Por exemplo, é possível rotular e filtrar jobs por equipe (como engineering ou research) e fase de desenvolvimento (prod ou test).

Os rótulos também estão disponíveis nas operações, mas eles são derivados do recurso ao qual a operação se aplica. Não é possível adicionar ou atualizar rótulos em uma operação.

Um rótulo é um par de chave-valor, em que a chave e o valor são strings personalizadas enviadas por você.

Limites e regras:

  • Um máximo de 64 rótulos é aceito por recurso.
  • Um máximo de 63 caracteres é aceito por chave ou valor.
  • As chaves e os valores podem conter apenas letras minúsculas, caracteres numéricos, sublinhados e traços.
  • As chaves precisam começar com uma letra.
  • Caracteres internacionais são permitidos.

Exemplos:

  • Rótulos que indicam a equipe ou o centro de custo: team:engineering e team:research.
  • Rótulos que indicam a fase de desenvolvimento: phase:prod e phase:test.
  • Rótulos que indicam o proprietário ou contato: owner:alice e owner:bob.

Como adicionar rótulos ao criar um recurso

Ao criar um recurso, use o comando gcloud ou a API AI Platform Training and Prediction no seu aplicativo Python para adicionar rótulos aos jobs (em inglês). Escolha uma guia abaixo para ver exemplos de cada método de adição de rótulos:

Console

É preciso criar o recurso antes de adicionar rótulos. Consulte como adicionar e atualizar rótulos.

gcloud

Ao criar um novo recurso, especifique o campo labels para anexar um rótulo ao novo recurso.

Para os exemplos abaixo, suponha que você queira usar esses rótulos: team:engineering, phase:test e owner:alice.

Para sua conveniência, configure uma variável de ambiente contendo esses rótulos:

RESOURCE_LABELS="team=engineering,phase=test,owner=alice"

O código a seguir envia um job de treinamento com os rótulos especificados:

JOB_NAME="your_job_name"
TRAINER_PACKAGE_PATH="/path/to/your/application/sources"
MAIN_TRAINER_MODULE="trainer.task"
JOB_DIR="gs://your/job/output/path"
TRAIN_DATA="gs://your/training/data/path"
EVAL_DATA="gs://your/eval/data/path"

gcloud ai-platform jobs submit training $JOB_NAME \
        --labels $RESOURCE_LABELS \
        --scale-tier basic \
        --package-path $TRAINER_PACKAGE_PATH \
        --module-name $MAIN_TRAINER_MODULE \
        --job-dir $JOB_DIR \
        --runtime-version 2.11 \
        --region $REGION \
        -- \
        --train-files $TRAIN_DATA \
        --eval-files $EVAL_DATA \
        --train-steps 1000

Python

Configure um dicionário contendo os campos do recurso que você quer criar. Inclua seus rótulos como uma entrada de dicionário que mapeia strings com outras strings.

O exemplo a seguir mostra como criar um job com três rótulos: team:engineering, phase:test e owner:alice.

training_inputs = {'scaleTier': 'BASIC',
    'packageUris': ['gs://your/trainer/path/package-0.0.0.tar.gz'],
    'pythonModule': 'trainer.task'
    'args': ['--arg1', 'value1', '--arg2', 'value2'],
    'region': 'us-central1',
    'labels': {
       'team': 'engineering',
       'phase': 'test',
       'owner': 'alice'
    },
    'jobDir': 'gs://your/training/job/directory',
    'runtimeVersion': '2.11'}

job_spec = {'jobId': your_job_name, 'trainingInput': training_inputs}

Envie a solicitação:

request = cloudml.projects().jobs().create(body=job_spec,
      parent=project_id)
response = request.execute()

Como atualizar e remover rótulos

É possível atualizar ou remover rótulos em jobs e modelos usando o comando gcloud ou em seu aplicativo Python. Não é possível atualizar rótulos em versões de modelo atuais.

Escolha uma guia abaixo para ver exemplos de cada método de remoção/atualização de rótulos:

Console

  1. Abra a página do console do Google Cloud do recurso que você quer rotular:

  2. Marque a caixa de seleçãoao lado dos nomes dos recursos a serem rotulados.

  3. Todas as edições de rótulos são feitas no painel à direita dos nomes dos recursos.

    • Para adicionar rótulos, insira a chave e, opcionalmente, o valor do rótulo. Para adicionar vários rótulos, clique no botão Adicionar rótulo.

    • Para remover rótulos, passe o mouse sobre o rótulo à direita e clique noícone Excluir exibido.

  4. Depois de editar os rótulos, clique em Salvar para confirmar as alterações ou em Descartar alterações para recomeçar.

gcloud

É possível usar o comando gcloud para atualizar ou remover rótulos em um recurso existente. Por exemplo, para ajustar os rótulos em um job, execute o comando gcloud ai-platform jobs update com as sinalizações a seguir:

  • --update-labels para modificar o valor de rótulos atuais e adicionar novos rótulos. Por exemplo, para alterar o valor do rótulo phase para production e adicionar um novo rótulo status:

    gcloud ai-platform jobs update $JOB_NAME \
        --update-labels phase=production,status=deployed

  • --clear-labels para remover todos os rótulos do job. Caso inclua uma sinalização --update-labels no mesmo comando, o comando clear será aplicado primeiro, seguido do comando update. Por exemplo, para remover todos os rótulos e aplicar os novos rótulos foo e baz:

    gcloud ai-platform jobs update $JOB_NAME \
        --clear-labels \
        --update-labels foo=bar,baz=qux

  • --remove-labels para remover rótulos específicos do job. Se você especificar um rótulo que não existe no job, o comando remove será ignorado para esse rótulo. Por exemplo, para remover os rótulos status e visibility:

    gcloud ai-platform jobs update $JOB_NAME \
    --remove-labels=status,visibility

Python

Para remover ou atualizar rótulos para um job existente, faça o seguinte:

  • Receba o job usando uma solicitação GET.
  • Modifique o campo labels.
  • Atualize o job usando uma solicitação PATCH.

Veja na amostra a seguir como o padrão READ-MODIFY-WRITE é usado para atualizar os rótulos dos jobs:

existingJob = ml.projects().jobs().get(jobId=jobId).execute()
etag = existingJob['etag']

updatedJob = {
    'labels': {
        'phase': 'prod',
        'team': 'research'
    },
    'etag': etag
}

updateJobRequest = ml.projects().jobs().patch(name=jobId,
      body=updatedJob, updateMask='labels,etag')
updatedJob = updateJobRequest.execute()

Como usar rótulos para filtrar recursos

Ao listar os recursos, é possível filtrar a lista por rótulo.

Console

  1. Abra a página do console do Google Cloud do recurso que você quer filtrar:

  2. Clique no campoFiltrar por prefixo, localizado acima da lista de jobs. Selecione o prefixo Rótulo.

  3. Para concluir o filtro, insira a chave e o valor usando a sintaxe "key:value". Por exemplo, "team:engineering" ou "owner:alice".

  4. O filtro é aplicado à lista de recursos, e o nome dele é exibido no campo de filtro. Por exemplo: "Labels:owner:alice" ou "Labels:team:engineering". É possível adicionar vários filtros, se necessário.

gcloud

No exemplo a seguir, listamos todos os jobs rotulados com o par de chave-valor team:engineering e owner:alice:

gcloud ai-platform jobs list \
        --filter='labels.team:engineering AND labels.owner=alice'

Python

O exemplo a seguir usa a solicitação jobs.list para recuperar todos os jobs rotulados com o par de chave-valor team:engineering e owner:alice:

request = ml.projects().jobs().list(parent=projectID,
      filter='labels.team=engineering AND labels.owner=alice')
results = request.execute()

A seguir