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
eteam:research
. - Rótulos que indicam a fase de desenvolvimento:
phase:prod
ephase:test
. - Rótulos que indicam o proprietário ou contato:
owner:alice
eowner: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
Abra a página do console do Google Cloud do recurso que você quer rotular:
Para rotular jobs, abra a página Jobs do AI Platform Prediction no console do Google Cloud.
Para rotular modelos, abra a página Modelos do AI Platform Prediction no console do Google Cloud.
Marque a caixa de seleção
ao lado dos nomes dos recursos a serem rotulados.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.
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ótulophase
paraproduction
e adicionar um novo rótulostatus
: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ótulosfoo
ebaz
: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ótulosstatus
evisibility
: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
Abra a página do console do Google Cloud do recurso que você quer filtrar:
Para filtrar jobs, abra a página Jobs do AI Platform Prediction no console do Google Cloud.
Para filtrar modelos, abra a página Modelos do AI Platform Prediction no console do Google Cloud.
Clique no campo
Filtrar por prefixo, localizado acima da lista de jobs. Selecione o prefixo Rótulo.Para concluir o filtro, insira a chave e o valor usando a sintaxe "key:value". Por exemplo, "team:engineering" ou "owner:alice".
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
- Saiba mais sobre como gerenciar modelos e jobs.