Etiqueta y filtra recursos

En esta página, se explica cómo etiquetar tus recursos y usar las etiquetas para organizar y filtrar tus recursos.

Descripción general de las etiquetas

Puedes agregar etiquetas a tus trabajos de AI Platform Training y usarlas para organizar los recursos en categorías cuando tengas que visualizarlos o supervisarlos.

Por ejemplo, puedes etiquetar trabajos por equipo (como engineering o research) y por fase de desarrollo (prod o test) y, luego, filtrar los trabajos según el equipo y la fase.

Las etiquetas también están disponibles en las operaciones, pero estas etiquetas derivan del recurso al que se aplica la operación. No puedes agregar o actualizar etiquetas en una operación.

Una etiqueta es un par clave-valor en el que la clave y el valor son strings personalizadas que proporcionas.

Límites y reglas:

  • Máximo de 64 etiquetas por recurso.
  • Máximo de 63 caracteres por clave o valor.
  • Las claves y los valores pueden contener letras en minúscula, números, guiones bajos y guiones.
  • Las claves deben comenzar con una letra.
  • Se permite el uso de caracteres internacionales.

Ejemplos:

  • Etiquetas que indican el equipo o el centro de costos: team:engineering y team:research.
  • Etiquetas que indican la fase de desarrollo: phase:prod y phase:test.
  • Etiquetas que indican el propietario o el contacto: owner:alice y owner:bob.

Agrega etiquetas cuando crees un recurso

Cuando creas un recurso, puedes usar el comando de gcloud o la API de entrenamiento y predicción de AI Platform en tu aplicación de Python para agregar etiquetas a los trabajos. Elige una pestaña de las que se encuentran a continuación a fin de ver ejemplos de cada método para agregar etiquetas:

Console

Debes crear el recurso antes de agregar etiquetas. Consulta cómo agregar y actualizar etiquetas.

gcloud

Cuando crees un recurso nuevo, especifica el campo labels para adjuntar una etiqueta a un recurso nuevo.

Para los ejemplos a continuación, supón que deseas usar estas etiquetas: team:engineering, phase:test y owner:alice.

Para facilitarlo, configura una variable de entorno que contenga las siguientes etiquetas:

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

Con el siguiente código, se envía un trabajo de entrenamiento con las etiquetas especificadas:

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

Configura un diccionario que contenga los campos para el recurso que desees crear. Incluye las etiquetas como una entrada del diccionario que asigna strings a strings.

En el siguiente ejemplo, se muestra cómo crear un trabajo con tres etiquetas: team:engineering, phase:test y 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}

Envía la solicitud:

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

Actualiza y quita etiquetas

Puedes actualizar o quitar etiquetas en trabajos y modelos con el comando de gcloud o en tu aplicación de Python. No es posible actualizar las etiquetas de las versiones de modelo existentes.

Elige una pestaña de las que se encuentran a continuación a fin de ver ejemplos de cada método para quitar o actualizar etiquetas:

Console

  1. Abre la página Consola de Google Cloud para el recurso que deseas etiquetar:

  2. Selecciona la casilla de verificaciónjunto a los nombres de los recursos que deseas etiquetar.

  3. Toda la edición de etiquetas ocurre en el panel a la derecha de los nombres de los recursos.

    • Para agregar etiquetas, ingresa la clave (y, de manera opcional, el valor) de la etiqueta. Para agregar varias etiquetas, haz clic en el botón Agregar etiqueta.

    • Para quitar etiquetas, coloca el cursor sobre la derecha de la etiqueta y haz clic en el íconoBorrar que se muestra.

  4. Después de editar tus etiquetas, haz clic en Guardar a fin de confirmar los cambios o en Descartar cambios para comenzar de nuevo.

gcloud

Puedes usar el comando de gcloud para actualizar o quitar etiquetas en un recurso existente. Por ejemplo, para ajustar las etiquetas de un trabajo, ejecuta el comando gcloud ai-platform jobs update con las siguientes marcas:

  • --update-labels para modificar el valor de las etiquetas existentes y agregar etiquetas nuevas. Por ejemplo, para cambiar el valor de la etiqueta phase a production y agregar una etiqueta status nueva, ejecuta el siguiente comando:

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

  • --clear-labels para quitar todas las etiquetas del trabajo. Si incluyes una marca --update-labels en el mismo comando, primero se aplica el comando clear, seguido del comando update. Por ejemplo, para quitar todas las etiquetas y aplicar etiquetas foo y baz nuevas, ejecuta el siguiente comando:

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

  • --remove-labels para quitar etiquetas específicas del trabajo. Si especificas una etiqueta que no existe en el trabajo, se omite el comando remove para esa etiqueta. Por ejemplo, para quitar las etiquetas status y visibility, ejecuta el siguiente comando:

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

Python

Para quitar o actualizar las etiquetas de un trabajo existente, realiza las siguientes acciones:

  • Obtén el trabajo mediante una solicitud GET.
  • Modifica el campo labels.
  • Actualiza el trabajo mediante una solicitud PATCH.

En la siguiente muestra, aparece el patrón LECTURA-MODIFICACIÓN-ESCRITURA para actualizar las etiquetas de un trabajo:

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()

Usa etiquetas para filtrar recursos

Cuando enumeres tus recursos, puedes filtrar la lista por etiqueta.

Console

  1. Abre la página Consola de Google Cloud para el recurso que deseas filtrar:

  2. Haz clic en el campoFiltrar por prefijo, que se encuentra sobre tu lista de trabajos. Selecciona el prefijo Etiqueta.

  3. Para completar el filtro, ingresa la clave y el valor con la sintaxis "key:value". Por ejemplo, “team:engineering” o “owner:alice”.

  4. El filtro se aplica a tu lista de recursos, y el nombre del filtro aparece en el campo del filtro. Por ejemplo, “Labels:owner:alice” o “Labels:team:engineering”. Si es necesario, puedes agregar varios filtros.

gcloud

En el siguiente ejemplo, se enumeran todos los trabajos etiquetados con el par clave-valor team:engineering y el par clave-valor owner:alice:

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

Python

En el siguiente ejemplo, se usa la solicitud jobs.list para recuperar todos los trabajos etiquetados con el par clave-valor team:engineering y el par clave-valor owner:alice:

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

¿Qué sigue?