agent-platform-model-registry

エージェントプラットフォームのモデルレジストリ管理

概要

このスキルでは、エージェントプラットフォームのモデルレジストリで機械学習モデルを管理する手順を説明します。モデルの一覧表示、詳細の説明、新しいモデルやバージョンのアップロード、メタデータの更新、モデルの削除を取り上げます。

安全性と確認の階層（重要）

ユーザーに代わってコマンドを実行する前に、要求された操作に基づいて、以下の安全性の階層を必ず遵守してください。

1. 階層 R：読み取り専用（list、describe、get）
   • 確認は不要です。情報を収集するため、ただちに実行してください。
2. 階層 M：変更可能かつ取り消し可能（upload、update）
   • 「はい」／「いいえ」の選択肢を含む対話型の確認が必要です。確認プロンプトには、必須のすべてのフラグ（例：--region=us-central1、--project=...、--display-name="..."）を含む、正確なコマンド文字列をそのまま記載する必要があります。自然言語による言い換えでは不十分です。
   • 同一ターンでの実行制限：リクエストを受け取ったターン、または確認プロンプトを提示したターンに、コマンドを実行してはいけません。ターン 1 では、正確なコマンド文字列を記載した対話型の確認カードのみを提示してください。ユーザーの返信を待って停止し、明示的な「はい」／承認を受けた次のターンでのみ実行してください。事前の確認なしにターン 1 でuploadやupdateを実行することは固く禁じられています。
   • 途中でのパラメーター変更／拒否：ユーザーがプロンプトを拒否した場合、またはパラメーター（表示名、説明、親モデルなど）を変更した場合、以前のコマンドを実行してはいけません。直ちに変更を反映し、更新した正確なコマンドを記載した新しい確認プロンプトを提示して、承認を待ってください。
3. 階層 D：破壊的かつ取り消し不能（delete）
   • 明示的な入力による確認（例：「確認しました」や「はい、削除してください」）が必要です。事前確認（モデルがエンドポイントにデプロイされているかどうかの確認など）よりも前に、ただちに確認を求めてください。
   • 同一ターンでの実行制限：入力による確認を求めたターンに実行してはいけません。新しいターンでユーザーが返信するまで待ってください。
   • 途中での対象変更：ユーザーが考えを変えた場合（例：「代わりに 2 つ目のモデルを削除して」）、最初のモデルを削除してはいけません。新たに選択されたモデル ID を対象とする確認プロンプトを改めて提示し、承認を待ってください。
4. コストの見積もり：モデルレジストリの操作では、サービング用コンピューティングやエンドポイントをプロビジョニングせず、カタログのメタデータと保存済みのモデルアーティファクトを管理します。モデルレジストリの操作に対してestimate_costツールを呼び出してはいけません。estimate_costはサービングインフラストラクチャ（エンドポイント／バッチ予測）向けに設計されているため、レジストリの操作に対して呼び出すとエラーになります。プレビューカードにコストを含める場合は、モデルレジストリの操作ではサービング用コンピューティング料金が発生しないこと（コンピューティング料金は $0.00。モデルアーティファクトには標準の Cloud Storage 料金が適用されます）を明記してください。

フェーズ 0：環境のセットアップとパラメータの解決

重要：コマンドを実行する前に、必要なパラメータがすべて判明していることを確認してください。

1. リージョンまたはプロジェクトが不明な場合：基本環境の確認ポリシーに従ってください。以前のやり取りでセッションのロケーションまたはプロジェクトが設定されている場合は、再度尋ねずにその値を再利用します。プロンプトにもセッションコンテキストにも設定されていない場合、直接確認できるのは 1 回までです（例：gcloud config get project または gcloud config get compute/region）。それでも解決できない、または曖昧な場合は、変更を伴うコマンドやリソース固有のコマンドを実行する前に処理を中断し、不足しているパラメータをユーザーにはっきり尋ねてください。
2. モデル ID が不明な場合：ユーザーがモデル ID を指定せずにモデルの更新または説明を求めた場合は、処理を中断してモデル ID を尋ねるか、見つけやすいように先にモデル一覧を表示することを提案してください。
3. プレースホルダーの置換：ユーザーが指定した表示名にプレースホルダートークン（例：<unique-suffix>、[suffix]、<timestamp>）が含まれている場合は、短い一意の英数字文字列またはタイムスタンプを生成して、適切に置き換えてください。展開されていないプレースホルダートークンをそのまま API に渡してはいけません。
4. リージョンとプロジェクトのフラグ：すべての gcloud ai models コマンドで、必ず --region=$LOCATION_ID と --project=$PROJECT_ID を明示的に指定してください。global は使用しないでください。

1. モデルの一覧表示（Tier R）

このコマンドを使って、レジストリ内の既存モデルを確認し、数値 ID を取得します。確認は不要です。

必ず --limit を指定してください。1 つのプロジェクトには数千のモデルを保存できます。上限のない一覧表示では、すべてのページを取得するため、1 分以上かかり、数百 KB の出力が返されることがあります。結果は最終更新日時の新しい順に返されるため、--limit=50 を指定すると、最新のモデルを数秒で取得できます。

gcloud ai models list \
    --region=$LOCATION_ID \
    --project=$PROJECT_ID \
    --limit=50

• ユーザーが「すべて」のモデルの一覧を求めた場合も、--limit=50 を維持し、表示されるのは最終更新日時の新しいモデル 50 件だと伝えてください。ユーザーが件数または完全な一覧を求めない限り、レジストリ全体をページングして取得してはいけません（gcloud または Model.list() を使用）。代わりに、表示名を指定して特定のモデルを検索する方法を提案してください。

• ユーザーが完全な一覧を求めて譲らない場合は、--limit を削除し、--format="value(name.basename(),displayName)" を使ってモデルごとに簡潔な 1 行を出力してください。大規模なプロジェクトでは 1 分以上かかる場合があることを警告してください。

• ユーザーがモデルの件数を尋ねた場合は、一覧を表示せずに ID の数を数えてください。件数を取得する API はないため、すべてのモデルをページングして取得する必要があります（モデル 1,500 件あたり約 1 分）。時間がかかる可能性があることをユーザーに伝えてください。先に --limit を指定して一覧表示してはいけません。

  gcloud ai models list \
      --region=$LOCATION_ID \
      --project=$PROJECT_ID \
      --format="value(name)" | wc -l
  

• 一覧を絞り込むために --filter や --sort-by を使用してはいけません。gcloud はすべてのページを取得した後にクライアント側で両方を適用するため、上限のない一覧表示と同じくらい時間がかかります。

• 表示名でモデルを検索する場合（アップロードまたは削除の確認など）は、Python SDK を使ってサーバー側でフィルタリングしてください。

python3 - <<'PY'
from google.cloud import aiplatform

aiplatform.init(project='<PROJECT_ID>', location='<LOCATION_ID>')
for m in aiplatform.Model.list(filter='display_name="<DISPLAY_NAME>"'):
    print(m.name, m.display_name, m.create_time)
PY

2. モデルの説明（Tier R）

特定のモデルまたはバージョンの完全なメタデータを取得します。確認は不要です。

gcloud ai models describe $MODEL_ID \
    --region=$LOCATION_ID \
    --project=$PROJECT_ID

特定のバージョンを指定するには：

gcloud ai models describe ${MODEL_ID}@${VERSION_ID} \
    --region=$LOCATION_ID \
    --project=$PROJECT_ID

3. モデルのアップロード（Tier M）

新しいモデルまたは既存モデルの新しいバージョンを登録します。この処理は長時間実行されます。実行前にインライン確認カードによる承認が必要です。

例：カスタムモデルのアップロード

gcloud ai models upload \
    --region=$LOCATION_ID \
    --project=$PROJECT_ID \
    --display-name="<DISPLAY_NAME>" \
    --container-image-uri="<CONTAINER_IMAGE_URI>" \
    [--artifact-uri="<ARTIFACT_URI>"]

重要

これは Tier M の操作です。[安全性と確認のティア] を参照してください。

• ユーザーが「アーティファクト URI なし」と指定した場合は、--artifact-uri を省略してください。
• 既存モデルの新しいバージョンを登録する場合は、--parent-model=$PARENT_MODEL_ID を指定してください。
• <DISPLAY_NAME> は、ユーザーが指定した正確な名前に置き換えてください。

4. モデルの更新（Tier M）

表示名や説明などのメタデータフィールドを更新します。gcloud ai models には update サブコマンドがありません。代わりに、モデルのメタデータ更新は Vertex AI Python SDK （google.cloud.aiplatform.Model）を使用して実行する必要があります。

続行する前に、スクリプトを正確に記載したインライン確認カードが必要です。

python3 -c "
from google.cloud import aiplatform

aiplatform.init(project='$PROJECT_ID', location='$LOCATION_ID')
model = aiplatform.Model('$MODEL_ID')
model.update(display_name='<NEW_DISPLAY_NAME>', description='<NEW_DESCRIPTION>')
print(f'Successfully updated model: {model.resource_name}')
"

重要

これは Tier M の操作です。[安全性と確認のティア] above を参照してください。

• 表示名のみを更新する場合は、 model.update(display_name='<NEW_DISPLAY_NAME>') を渡します。
• 説明のみを更新する場合は、 model.update(description='<NEW_DESCRIPTION>') を渡します。
• 確認カードには、上記の正確な Python コマンドスニペットを表示する必要があります。 Turn 1 では絶対に実行せず、ユーザーから明示的な承認を待ちます。

5. モデルの削除（Tier D）

モデルとそのすべてのバージョンを完全に削除します。続行する前に、明示的なテキスト入力による確認が必要です。

gcloud ai models delete $MODEL_ID \
    --region=$LOCATION_ID \
    --project=$PROJECT_ID

警告

この操作は取り消せません。削除する前に、すべてのモデルバージョンをすべての エンドポイントからデプロイ解除する必要があります。

6. パブリッシャーモデルの検索（Tier R）

インタラクティブなモデル詳細を生成する前に、Model Garden Publisher Models を検索して model_id を確認する必要があります。確認は不要です。

一致するパブリッシャーモデルを検索するには、gcloud ai CLI を使用します。

gcloud ai model-garden models list --model-filter="<model_name_or_query>" --full-resource-name --format=json

一致するモデルの一覧が返されます。結果から正確な name フィールド（例：publishers/google/models/gemma2 または publishers/qwen/models/qwen3-coder）を抽出し、確認済みの model_id として使用します。