リソースのラベル付けとフィルタリング

このページでは、リソースにラベルを付け、そのラベルを使用してリソースを整理、フィルタリングする方法について説明します。

ラベルの概要

AI Platform Prediction(ジョブモデルモデル バージョン)にラベルを追加して、リソースを表示またはモニタリングする際に、そのラベルを使用してリソースをカテゴリ別に整理できます。

たとえば、チーム別(engineeringresearch など)や開発フェーズ別(prodtest など)にジョブにラベルを付けると、チームとフェーズを基準にしてジョブをフィルタリングできます。

ラベルはオペレーションでも使用できますが、この場合はオペレーションの適用先のリソースからラベルが導出されます。オペレーションに対してラベルを追加または更新することはできません。

ラベルは Key-Value ペアで、キーと値の両方とも、デベロッパーが指定するカスタム文字列です。

制限とルール:

  • 1 つのリソースあたり最大 64 個のラベル。
  • キーまたは値の最大文字数は 63。
  • キーと値に使用できるのは、小文字、数字、アンダースコア、ダッシュ。
  • キーの先頭は文字にする必要がある。
  • 国際文字も使用可能。

例:

  • チームまたはコストセンターを示すラベル: team:engineeringteam:research
  • 開発フェーズを示すラベル: phase:prodphase:test
  • オーナーまたは連絡先を示すラベル: owner:aliceowner:bob

リソース作成時のラベルの追加

リソースを作成するときに、gcloud コマンドを使用して、または Python アプリケーション内で AI Platform トレーニングと Prediction API を使用して、ジョブモデルモデル バージョンにラベルを付けることができます。以下のタブを選択すると、ラベルを追加するそれぞれの方法の例が表示されます。

Console

ラベルを追加する前にリソースを作成する必要があります。ラベルの追加と更新の方法をご覧ください。

gcloud

新しいリソースを作成する場合は、新しいリソースにラベルを付ける labels フィールドを指定します。

以下の例では、ラベル team:engineeringphase:testowner:alice を使用する場合を考えます。

便宜上、ラベルを含む環境変数を設定します。

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

次のコードは、指定されたラベルが含まれるモデルを作成します。

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

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

次のコードは、指定されたラベルが含まれるトレーニング ジョブを送信します。

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

作成するリソースのフィールドが含まれる辞書を設定します。文字列を文字列にマッピングする辞書エントリとしてラベルを含めます。

次の例は、3 つのラベル team:engineeringphase:testowner:alice が付いたモデルを作成する方法を示しています。

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

リクエストを送信します。

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

次の例は、3 つのラベル team:engineeringphase:testowner: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}

リクエストを送信します。

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

ラベルの更新と削除

gcloud コマンドを使用するか、Python アプリケーションで、ジョブモデルのラベルを更新または削除できます。既存のモデル バージョンのラベルは更新できません。

以下のタブを選択すると、ラベルを削除 / 更新するそれぞれの方法の例が表示されます。

Console

  1. ラベルを付けるリソースの Google Cloud コンソール ページを開きます。

  2. Select the ラベルを付けるリソースの名前の横にあるチェックボックスをオンにします。

  3. すべてのラベル編集は、リソース名の右側のパネルで行われます。

    • ラベルを追加するには、ラベルのキー(およびオプションで)を入力します。複数のラベルを追加するには、[ラベルの追加] ボタンをクリックします。

    • ラベルを削除するには、ラベルの右にカーソルを合わせて、表示される [削除] アイコンをクリックします。

  4. ラベルを編集したら、[保存] をクリックして変更を確定するか、[変更を破棄] してやり直します。

gcloud

gcloud コマンドを使用して、既存のリソースのラベルを更新または削除できます。たとえば、ジョブのラベルを調整するには、次のフラグを指定して gcloud ai-platform jobs update コマンドを実行します。

  • 既存のラベルの値を変更し、新しいラベルを追加するには、--update-labels を指定します。たとえば、phase ラベルの値を production に変更し、新しい status ラベルを追加するには、次のようにします。

    gcloud ai-platform jobs update $JOB_NAME \
            --update-labels phase=production,status=deployed
    
  • ジョブからすべてのラベルを削除するには、--clear-labels を指定します。--update-labels フラグを同じコマンドに含めると、clear コマンドが最初に適用され、その後 update コマンドが実行されます。たとえば、すべてのラベルを削除して新しい foo ラベルと baz ラベルを適用するには次のようにします。

    gcloud ai-platform jobs update $JOB_NAME \
            --clear-labels \
            --update-labels foo=bar,baz=qux
    
  • ジョブから特定のラベルを削除するには、--remove-labels を指定します。ジョブに存在しないラベルを指定すると、remove コマンドはそのラベルを無視します。たとえば、status ラベルと visibility ラベルを削除するには次のようにします。

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

Python

既存のリソース(モデルなど)のラベルを更新または削除するには:

  • GET リクエストを使用してモデルを取得します。
  • labels フィールドを変更します。
  • PATCH リクエストを使用してモデルを更新します。

次のサンプルは、モデルのラベルを更新するための、読み取り - 変更 - 書き込みのパターンを示しています。

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

既存のジョブのラベルを削除または更新するには:

  • GET リクエストを使用してジョブを取得します。
  • labels フィールドを変更します。
  • PATCH リクエストを使用してジョブを更新します。

次のサンプルは、ジョブのラベルを更新するための、読み取り - 変更 - 書き込みのパターンを示しています。

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

ラベルを使用したリソースのフィルタリング

リソースを一覧表示する場合は、ラベルによってリストをフィルタリングできます。

Console

  1. フィルタリングするリソースの Google Cloud コンソール ページを開きます。

  2. Click within the ジョブのリストの上にある、[前方一致でフィルタ] フィールド内をクリックします。[ラベル] プレフィックスを選択します。

  3. フィルタを完成させるには、「key:value」という構文を使用してキーと値を入力します。たとえば、「team:engineering」や「owner:alice」などです。

  4. フィルタがリソース リストに適用され、フィルタ名がフィルタ フィールドに表示されます。たとえば、「Labels:owner:alice」や「Labels:team:engineering」などです。必要に応じて、複数のフィルタを追加できます。

gcloud

次の例では、Key-Value ペア team:engineering のラベルが付いたすべてのモデルが一覧表示されます。

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

次の例では、Key-Value ペア team:engineering と Key-Value ペア owner:alice の両方のラベルが付いたすべてのジョブが一覧表示されます。

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

Python

次の例では、models.list リクエストを使用して Key-Value ペア team:engineering のラベルが付いたすべてのモデルを取得します。

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

次の例では、jobs.list リクエストを使用して、Key-Value ペア team:engineering と Key-Value ペア owner:alice の両方のラベルが付いたすべてのモデルを取得します。

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

次のステップ