このページでは、リソースにラベルを付け、そのラベルを使用してリソースを整理、フィルタリングする方法について説明します。
ラベルの概要
AI Platform Prediction（ジョブ、モデル、モデル バージョン）にラベルを追加して、リソースを表示またはモニタリングする際に、そのラベルを使用してリソースをカテゴリ別に整理できます。
たとえば、チーム別（engineering や research など）や開発フェーズ別（prod や test など）にジョブにラベルを付けると、チームとフェーズを基準にしてジョブをフィルタリングできます。
ラベルはオペレーションでも使用できますが、この場合はオペレーションの適用先のリソースからラベルが導出されます。オペレーションに対してラベルを追加または更新することはできません。
ラベルは Key-Value ペアで、キーと値の両方とも、デベロッパーが指定するカスタム文字列です。
制限とルール:
- 1 つのリソースあたり最大 64 個のラベル。
- キーまたは値の最大文字数は 63。
- キーと値に使用できるのは、小文字、数字、アンダースコア、ダッシュ。
- キーの先頭は文字にする必要がある。
- 国際文字も使用可能。
例:
- チームまたはコストセンターを示すラベル:
team:engineeringとteam:research。 - 開発フェーズを示すラベル:
phase:prodとphase:test。 - オーナーまたは連絡先を示すラベル:
owner:aliceとowner:bob。
リソース作成時のラベルの追加
リソースを作成するときに、gcloud コマンドを使用して、または Python アプリケーション内で AI Platform トレーニングと Prediction API を使用して、ジョブ、モデル、モデル バージョンにラベルを付けることができます。以下のタブを選択すると、ラベルを追加するそれぞれの方法の例が表示されます。
Console
ラベルを追加する前にリソースを作成する必要があります。ラベルの追加と更新の方法をご覧ください。
gcloud
新しいリソースを作成する場合は、新しいリソースにラベルを付ける labels フィールドを指定します。
以下の例では、ラベル team:engineering、phase:test、owner: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:engineering、phase:test、owner: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:engineering、phase:test、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}
リクエストを送信します。
request = cloudml.projects().jobs().create(body=job_spec,
parent=project_id)
response = request.execute()
ラベルの更新と削除
gcloud コマンドを使用するか、Python アプリケーションで、ジョブとモデルのラベルを更新または削除できます。既存のモデル バージョンのラベルは更新できません。
以下のタブを選択すると、ラベルを削除 / 更新するそれぞれの方法の例が表示されます。
Console
ラベルを付けるリソースの Google Cloud コンソール ページを開きます。
ジョブにラベルを付けるには、Google Cloud コンソールで AI Platform Prediction の [ジョブ] ページを開きます。
モデルにラベルを付けるには、Google Cloud コンソールで AI Platform Prediction の [モデル] ページを開きます。
Select the ラベルを付けるリソースの名前の横にあるチェックボックスをオンにします。
すべてのラベル編集は、リソース名の右側のパネルで行われます。
ラベルを追加するには、ラベルのキー（およびオプションで値）を入力します。複数のラベルを追加するには、[ラベルの追加] ボタンをクリックします。
ラベルを削除するには、ラベルの右にカーソルを合わせて、表示される [削除] アイコンをクリックします。
ラベルを編集したら、[保存] をクリックして変更を確定するか、[変更を破棄] してやり直します。
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
既存のリソース（モデルなど）のラベルを更新または削除するには:
次のサンプルは、モデルのラベルを更新するための、読み取り - 変更 - 書き込みのパターンを示しています。
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()
既存のジョブのラベルを削除または更新するには:
次のサンプルは、ジョブのラベルを更新するための、読み取り - 変更 - 書き込みのパターンを示しています。
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
フィルタリングするリソースの Google Cloud コンソール ページを開きます。
ジョブをフィルタリングするには、Google Cloud コンソールで AI Platform Prediction の [ジョブ] ページを開きます。
モデルをフィルタリングするには、Google Cloud コンソールで AI Platform Prediction の [モデル] ページを開きます。
Click within the ジョブのリストの上にある、[前方一致でフィルタ] フィールド内をクリックします。[ラベル] プレフィックスを選択します。
フィルタを完成させるには、「key:value」という構文を使用してキーと値を入力します。たとえば、「team:engineering」や「owner:alice」などです。
フィルタがリソース リストに適用され、フィルタ名がフィルタ フィールドに表示されます。たとえば、「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()
次のステップ
- モデルとジョブの管理について学習する。