Etichettatura e filtri delle risorse

Questa pagina spiega come etichettare le risorse e poi utilizzarle per organizzarle e filtrarle.

Panoramica delle etichette

Puoi aggiungere etichette ai job, ai modelli e alle versioni dei modelli di AI Platform Prediction e poi utilizzare queste etichette per organizzare le risorse in categorie quando le visualizzi o le monitori.

Ad esempio, puoi etichettare i job in base al team (ad es. engineering o research) e alla fase di sviluppo (prod o test), quindi filtrare i job in base al team e alla fase.

Le etichette sono disponibili anche per le operazioni, ma queste etichette derivano dalla risorsa a cui si applica l'operazione. Non puoi aggiungere o aggiornare le etichette di un'operazione.

Un'etichetta è una coppia chiave-valore, in cui sia la chiave sia il valore sono stringhe personalizzate fornite da te.

Limiti e regole:

  • Massimo 64 etichette per risorsa.
  • Massimo 63 caratteri per chiave o valore.
  • Le chiavi e i valori possono contenere lettere minuscole, caratteri numerici, trattini bassi e trattini.
  • Le chiavi devono iniziare con una lettera.
  • Sono consentiti caratteri internazionali.

Esempi:

  • Etichette che indicano il team o il centro di costo: team:engineering e team:research.
  • Etichette che indicano la fase di sviluppo: phase:prod e phase:test.
  • Etichette che indicano il proprietario o il contatto: owner:alice e owner:bob.

Aggiungere etichette durante la creazione di una risorsa

Quando crei una risorsa, puoi utilizzare il comando gcloud o l'API AI Platform Training and Prediction nella tua applicazione Python per aggiungere etichette ai job, ai modelli e alle versioni dei modelli. Scegli una scheda di seguito per visualizzare esempi di ciascun metodo di aggiunta di etichette:

console

Devi creare la risorsa prima di aggiungere le etichette. Scopri come aggiungere e aggiornare le etichette.

gcloud

Quando crei una nuova risorsa, specifica il campo labels per allegare un'etichetta alla nuova risorsa.

Per gli esempi riportati di seguito, supponiamo che tu voglia utilizzare queste etichette: team:engineering,phase:test e owner:alice.

Per comodità, configura una variabile di ambiente contenente le etichette:

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

Il seguente codice crea un modello con le etichette specificate:

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

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

Il seguente codice invia un job di addestramento con le etichette specificate:

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 dizionario contenente i campi per la risorsa che vuoi creare. Includi le etichette come voce di dizionario che mappa stringhe a stringhe.

L'esempio seguente mostra come creare un modello con tre etichette: team:engineering, phase:test e owner:alice.

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

Invia la richiesta:

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

L'esempio seguente mostra come creare un job con tre etichette: 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}

Invia la richiesta:

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

Aggiornamento e rimozione delle etichette

Puoi aggiornare o rimuovere le etichette su job e modelli utilizzando il comando gcloud o nell'applicazione Python. Non è possibile aggiornare le etichette delle versioni del modello esistenti.

Scegli una scheda di seguito per visualizzare esempi di ciascun metodo di rimozione/aggiornamento delle etichette:

console

  1. Apri la pagina della console Google Cloud della risorsa che vuoi etichettare:

  2. Seleziona casella di controllo accanto ai nomi delle risorse che vuoi etichettare.

  3. Tutte le modifiche alle etichette vengono eseguite nel riquadro a destra dei nomi delle risorse.

    • Per aggiungere le etichette, inserisci la chiave (e, facoltativamente, il valore) per l'etichetta. Per aggiungere più etichette, fai clic sul pulsante Aggiungi etichetta.

    • Per rimuovere le etichette, passa il mouse sopra la parte destra dell'etichetta e fai clic sulla Icona Elimina visualizzata.

  4. Dopo aver modificato le etichette, fai clic su Salva per confermare le modifiche o su Annulla modifiche per ricominciare da capo.

gcloud

Puoi utilizzare il comando gcloud per aggiornare o rimuovere le etichette di una risorsa esistente. Ad esempio, per modificare le etichette di un job, esegui il comando gcloud ai-platform jobs update con i seguenti flag:

  • --update-labels per modificare il valore delle etichette esistenti e aggiungerne di nuove. Ad esempio, per modificare il valore dell'etichetta phase in production e aggiungere una nuova etichetta status:

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

  • --clear-labels per rimuovere tutte le etichette dal job. Se includi un --update-labels flag nello stesso comando, viene applicato prima il comando clear, seguito dal comando update. Ad esempio, per rimuovere tutte le etichette e applicare nuove etichette foo e baz:

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

  • --remove-labels per rimuovere etichette specifiche dal job. Se specifichi un'etichetta che non esiste nel job, il comando remove viene ignorato per quell'etichetta. Ad esempio, per rimuovere le etichette status e visibility:

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

Python

Per aggiornare o rimuovere le etichette di una risorsa esistente, ad esempio un modello:

  • Ottieni il modello utilizzando una richiesta GET.
  • Modifica il campo labels.
  • Aggiorna il modello utilizzando una richiesta PATCH.

L'esempio seguente mostra il pattern LETTURA-MODIFICA-SCRITTURA per aggiornare le etichette di un modello:

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

Per rimuovere o aggiornare le etichette di un job esistente:

  • Ottieni il job utilizzando una richiesta GET.
  • Modifica il campo labels.
  • Aggiorna il job utilizzando una richiesta PATCH.

L'esempio seguente mostra il pattern LETTURA-MODIFICA-SCRITTURA per aggiornare le etichette dei job:

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

Utilizzare le etichette per filtrare le risorse

Quando elenchi le risorse, puoi filtrare l'elenco per etichetta.

console

  1. Apri la pagina della console Google Cloud della risorsa da filtrare:

  2. Fai clic all'interno del Campo Filtra per prefisso, che si trova sopra l'elenco dei job. Seleziona il prefisso Etichetta.

  3. Per completare il filtro, inserisci la chiave e il valore utilizzando la sintassi "chiave:valore". Ad esempio, "team:engineering" o "owner:alice".

  4. Il filtro viene applicato all'elenco delle risorse e il nome del filtro viene visualizzato nel campo del filtro. Ad esempio: "Etichette:proprietario:alice" o "Etichette:team:engineering". Se necessario, puoi aggiungere più filtri.

gcloud

L'esempio seguente elenca tutti i modelli etichettati con la coppia chiave-valore team:engineering:

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

L'esempio seguente elenca tutti i job etichettati sia con la coppia chiave-valoreteam:engineering sia con la coppia chiave-valore owner:alice:

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

Python

L'esempio seguente utilizza la richiesta models.list per recuperare tutti i modelli etichettati con la coppia chiave-valore team:engineering:

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

L'esempio seguente utilizza la richiesta jobs.list per recuperare tutti i job etichettati sia con la coppia chiave-valore team:engineering sia con la coppia chiave-valore owner:alice:

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

Passaggi successivi