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 recursos do AI Platform Prediction (jobs, modelos e versões do modelo) para organizá-los em categorias para fins de visualização ou monitoramento.

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, é possível usar o comando gcloud ou o AI Platform Training e a API Prediction no aplicativo Python para adicionar rótulos aos jobs, modelos e versões do modelo. 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 cria um modelo com os rótulos especificados:

REGION="us-central1"
MODEL_NAME="your_model_name"

gcloud ai-platform models create $MODEL_NAME \
        --labels $RESOURCE_LABELS \
        --regions $REGION

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 modelocom três rótulos: team:engineering, phase:test e owner:alice.

requestDict = {'name': modelName,
    'description': 'A model with labels.',
    'labels': {
       'team': 'engineering',
       'phase': 'test',
       'owner': 'alice'
    }}

Envie a solicitação:

request = ml.projects().models().create(parent=projectID,
                            body=requestDict)
response = request.execute()

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ção ao 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 atualizar ou remover rótulos de um recurso existente, como um modelo, faça o seguinte:

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

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

existingModel = ml.projects().models().get(name=fullModelName).execute()
etag = existingModel['etag']

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

# projects.models.patch API returns a long-running operation object
# instead of a model object. See
# https://cloud.google.com/ai-platform/prediction/docs/reference/rest/v1/projects.models/patch
updateModelRequest = ml.projects().models().patch(name=fullModelName,
      body=updatedModel, updateMask='labels,etag')
updateModelOperation = updateModelRequest.execute()

# You can choose appropriate ways to poll the operation.
delay = 1
while not updateModelOperation['done']:
  time.sleep(delay)
  delay *= 2
  updateModelOperation = ml.projects().operations().get(name=updateModelOperation['name'])
updatedModel = ml.projects().models().get(name=fullModelName).execute()

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 campo Filtrar 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

O exemplo a seguir lista todos os modelos rotulados com o par de chave-valor team:engineering:

gcloud ai-platform models list --filter='labels.team:engineering'

O exemplo a seguir lista 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 models.list para recuperar todos os modelos rotulados com o par de chave-valor team:engineering:

request = ml.projects().models().list(parent=projectID,
      filter='labels.team=engineering')
results = request.execute()

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