Étiqueter et filtrer les ressources

Vous trouverez sur cette page la procédure à suivre pour étiqueter vos ressources afin de pouvoir les organiser et les filtrer de manière plus efficace.

Présentation des étiquettes

Vous pouvez ajouter des étiquettes à vos tâches, modèles et versions de modèles AI Platform Prediction, puis les utiliser pour organiser les ressources en catégories lorsque vous les consultez ou les supervisez.

Vous pouvez ainsi étiqueter les tâches correspondant à différentes équipes (par exemple, engineering ou research) ou à différentes phases de développement (prod ou test), puis les filtrer en fonction de l'équipe ou de la phase.

Les operations peuvent aussi bénéficier d'étiquettes, mais celles-ci sont alors dérivées de la ressource à laquelle l'opération s'applique. Vous ne pouvez pas ajouter ni modifier d'étiquettes sur une opération.

Une étiquette est une paire clé/valeur dont la clé et la valeur sont des chaînes personnalisées que vous fournissez.

Limites et règles :

  • Une ressource peut recevoir un maximum de 64 étiquettes.
  • Une clé ou une valeur peut contenir un maximum de 63 caractères.
  • Les clés et les valeurs peuvent contenir des lettres minuscules, des chiffres, des traits de soulignement et des tirets.
  • Les clés doivent commencer par une lettre.
  • Les caractères internationaux sont acceptés.

Exemples :

  • Étiquettes indiquant une équipe ou un centre de coûts : team:engineering et team:research
  • Étiquettes indiquant une phase de développement : phase:prod et phase:test
  • Étiquettes indiquant un propriétaire ou un contact : owner:alice et owner:bob

Ajouter des étiquettes lors de la création d'une ressource

Lorsque vous créez une ressource, vous pouvez utiliser la commande gcloud ou l'API AI Platform Training and Prediction dans votre application Python pour ajouter des étiquettes à vos tâches, modèles et versions de modèles. Sélectionnez l'un des onglets ci-dessous pour afficher des exemples de chaque méthode d'ajout d'étiquette :

Console

Vous devez créer la ressource avant d'ajouter des étiquettes. Découvrez comment ajouter et modifier des étiquettes.

gcloud

Lors de la création d'une ressource, spécifiez le champ labels pour associer une étiquette à la nouvelle ressource.

Pour les exemples ci-dessous, supposons que vous souhaitiez utiliser les étiquettes suivantes : team:engineering, phase:test et owner:alice.

Pour plus de simplicité, configurez une variable d'environnement contenant les étiquettes :

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

Le code suivant crée un model doté des libellés spécifiés :

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

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

Le code suivant envoie une tâche d'apprentissage dotée des libellés spécifiés :

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

Configurez un dictionnaire contenant les champs de la ressource que vous souhaitez créer. Incluez les étiquettes sous la forme d'une entrée de dictionnaire mappant les chaînes par paires.

L'exemple suivant montre comment créer un model avec trois étiquettes : team:engineering, phase:test et owner:alice.

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

Envoyez la requête :

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

L'exemple suivant montre comment créer une tâche avec trois étiquettes : team:engineering, phase:test et 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}

Envoyez la requête :

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

Modifier et supprimer des étiquettes

Vous pouvez modifier ou supprimer des étiquettes associées à des tâches ou des modèles à l'aide de la commande gcloud ou directement dans votre application Python. Il n'est pas possible de modifier les étiquettes sur les versions de modèles existantes.

Choisissez un onglet ci-dessous pour voir des exemples de chaque méthode de suppression ou de modification des étiquettes :

Console

  1. Ouvrez la page de la console Google Cloud de la ressource à laquelle ajouter une étiquette :

  2. Sélectionnez le à côté du nom de la ou des ressources à étiqueter.

  3. Toutes les modifications d'étiquettes sont effectuées dans le volet situé à droite des noms de ressources.

    • Pour ajouter une étiquette, saisissez sa clé et, éventuellement, sa valeur. Pour ajouter plusieurs étiquettes, cliquez sur le bouton Ajouter une étiquette.

    • Pour supprimer des libellés, pointez sur leur droite et cliquez sur l'icône Supprimer qui s'affiche.

  4. Après avoir modifié vos étiquettes, cliquez sur Enregistrer pour confirmer les modifications ou sur Annuler les modifications pour recommencer.

gcloud

Vous pouvez utiliser la commande gcloud pour modifier ou supprimer des étiquettes sur une ressource existante. Par exemple, pour modifier les étiquettes appliquées à une tâche, exécutez la commande gcloud ai-platform jobs update avec les options suivantes :

  • --update-labels pour modifier la valeur des étiquettes existantes et ajouter des étiquettes. Par exemple, pour remplacer la valeur de l'étiquette phase par production et ajouter une étiquette status, procédez comme suit :

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

  • --clear-labels pour supprimer toutes les étiquettes de la tâche. Si vous incluez une option --update-labels dans la même commande, la commande clear est appliquée en premier, suivie de la commande update. Par exemple, pour supprimer toutes les étiquettes et appliquer les nouvelles étiquettes foo et baz, procédez comme suit :

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

  • --remove-labels pour supprimer des étiquettes spécifiques de la tâche. Si vous spécifiez une étiquette qui n'existe pas dans la tâche, la commande remove est ignorée pour celle-ci. Par exemple, pour supprimer les étiquettes status et visibility, procédez comme suit :

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

Python

Pour modifier ou supprimer des étiquettes associées à une ressource existante, telle qu'un model, procédez comme suit :

  • Récupérez le modèle à l'aide d'une requête GET.
  • Modifiez le champ labels.
  • Modifiez le modèle à l'aide d'une requête PATCH.

L'exemple suivant montre le schéma LIRE-MODIFIER-ÉCRIRE correspondant à la mise à jour des étiquettes d'un modèle :

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

Pour supprimer ou modifier les étiquettes d'une tâche existante, procédez comme suit :

  • Récupérez la tâche à l'aide d'une requête GET.
  • Modifiez le champ labels.
  • Modifiez la tâche à l'aide d'une requête PATCH.

L'exemple suivant présente le schéma "LIRE-MODIFIER-ÉCRIRE" correspondant à la mise à jour des étiquettes d'une tâche :

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

Filtrer les ressources à l'aide d'étiquettes

Lorsque vous répertoriez vos ressources, vous pouvez filtrer la liste par étiquette.

Console

  1. Ouvrez la page de la console Google Cloud de la ressource à filtrer :

  2. Cliquez dans le champ Filtrer par préfixe, situé au-dessus de votre liste de tâches. Sélectionnez le préfixe Label (Étiquette).

  3. Pour terminer le filtrage, saisissez la clé et la valeur en appliquant la syntaxe "key.value". Par exemple, "team:engineering" ou "owner:alice".

  4. Le filtre est appliqué à votre liste de ressources et le nom du filtre s'affiche dans le champ de filtrage. Par exemple, "Labels:owner:alice" ou "Labels:team:engineering". Vous pouvez ajouter plusieurs filtres si nécessaire.

gcloud

L'exemple suivant répertorie tous les modèles étiquetés avec la paire clé/valeur team:engineering :

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

L'exemple suivant répertorie toutes les tâches étiquetées avec la paire clé/valeur team:engineering et la paire clé/valeur owner:alice :

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

Python

L'exemple suivant utilise la requête models.list pour récupérer tous les modèles étiquetés avec la paire clé/valeur team:engineering :

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

L'exemple suivant utilise la requête jobs.list pour récupérer toutes les tâches étiquetées avec la paire clé/valeur team:engineering et la paire clé/valeur owner:alice :

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

Étapes suivantes