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

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

ラベルの概要

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

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

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

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

制限とルール:

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

例:

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

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

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

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 1.13 \
        --region $REGION \
        -- \
        --train-files $TRAIN_DATA \
        --eval-files $EVAL_DATA \
        --train-steps 1000

Python

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

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

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

次の例は、team:engineeringphase:testowner:alice という 3 つのラベルを付けたジョブを作成する方法を示しています。

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': '1.13'}

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 アプリケーションを使用して、ジョブモデルのラベルを更新または削除できます。既存のモデル バージョンのラベルを更新することはできません。

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

gcloud

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

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

    gcloud ai-platform models update $MODEL_NAME \
            --update-labels phase=production,status=deployed
    
  • --clear-labels: すべてのラベルをモデルから削除します。同じコマンドで --update-labels フラグを指定すると、最初に clear コマンドが適用され、次に update コマンドが適用されます。たとえば、すべてのラベルを削除して、新しい foo ラベルと baz ラベルを適用するには、次を実行します。

    gcloud ai-platform models update $MODEL_NAME \
            --clear-labels \
            --update-labels foo=bar,baz=qux
    
  • --remove-labels: モデルから特定のラベルを削除します。モデルに存在しないラベルを指定すると、remove コマンドはそのラベルを無視します。たとえば、status ラベルと visibility ラベルを削除するには、次を実行します。

    gcloud ai-platform models update $MODEL_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/ml-engine/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()

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

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

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

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

scikit-learn と XGBoost の AI Platform