agent-platform-deploy

Agent Platform Model Garden デプロイ スキル

このスキルでは、Agent Platform Model Garden のオープンモデルをエンドポイントにデプロイし、その後、リソースをクリーンアップするためにデプロイを解除する手順を説明します。

1P チューニング済みモデルのコピーとデプロイ

1P（ファーストパーティ）チューニング済みモデルをソースプロジェクトから別のリージョンまたはプロジェクトにコピーし、新しく作成したエンドポイントにデプロイする必要がある場合は、 1P チューニング済みモデルのコピーとデプロイガイドを参照してください。

安全性と確認のティア（重要）

ユーザーに代わってコマンドを実行する前に、要求されたアクションに応じて、以下の安全性ティアを必ず遵守してください。

1. ティア R：読み取り専用（list、describe、list-deployment-config）
   • ルール：確認は不要です。ユーザーに情報を提供するため、これらのコマンドを直ちに実行できます。
2. ティア M：変更可能かつ取り消し可能（deploy、undeploy-model）

   • ルール：ユーザーによる明示的な確認が必要です。次の内容を含む、明確なドライラン確認カードを必ず提示してください。

     1. 正確な実行予定のgcloudコマンドのコードブロック（gcloud ai model-garden models deploy ... --asynchronous）。
     2. モデル識別子、デプロイ先のプロジェクト ID、対象リージョン。
     3. マシンタイプとアクセラレータの構成。
     4. 推定時間あたりの費用（$/hr）。
     5. エンドポイントの表示名。
     6. 実行前に承認するよう求める、明示的な確認プロンプト。 ユーザーから明示的な確認を得るまで、必ず待機してください。undeploy-modelの場合は、エンドポイントとデプロイ済みモデルが存在することを最初に確認する必要があります。describeまたはlistが404または空の結果を返した場合は、デプロイ解除を試みず、必ず処理を中止してユーザーに通知してください。

   • 同一ターンでの制限：確認プロンプトを提示したターンと同じターンに、コマンドを実行してはいけません。確認を求めたらターンを終了し、ユーザーの返信を待ってください。明示的な承認を得た後にのみ実行してください。プレビューを表示した後、ユーザーが回答する前にツールを呼び出しても、確認を得たことにはなりません。

3. ティア D：破壊的で取り消し不可能（delete）
   • ルール：文字入力による明示的な確認が必要です。エンドポイントまたはモデルの削除が取り消し不可能であることを説明し、削除コマンドを実行する前に「I confirm」または「Yes, delete it」と入力するよう求めるテキストメッセージを必ず出力してください。

重要

完全なテキスト応答を常に出力すること（テキストを空にしないこと）：gcloud ai model-garden models deploy、gcloud ai endpoints delete、gcloud ai endpoints list、ステータス確認など、ツール呼び出しを実行した後は、必ず完全で有益なテキスト応答をユーザーに返してください。操作名、エンドポイント名／ID、エラーメッセージ、またはリソースの一覧を明示的に報告してください。ターンを空のテキストや無言で終了してはいけません。

1. 前提条件

デプロイする前に、正しいプロジェクトとリージョンが設定されていることを確認してください。以下のコマンドでは、プレースホルダー変数PROJECT_IDとLOCATION_IDを使用します。

認証されていることを確認してください：

gcloud auth login
gcloud auth application-default login
gcloud config set project $PROJECT_ID

2. デプロイ可能なモデルを探す

Model Garden で利用可能なモデルを一覧表示し、セルフデプロイ可能かどうかを確認できます。

gcloud ai model-garden models list

特定のモデルでサポートされているマシンタイプとアクセラレータを確認するには、上記の models list の出力から取得した MODEL_ID を渡します。以下の <PUBLISHER>/<FAMILY>@<VERSION-ID> は、カタログの出力にある完全一致の文字列に置き換えてください。このプレースホルダーは、意図的に実在しないモデル ID にしてあります。

gcloud ai model-garden models list-deployment-config \
    --model="<PUBLISHER>/<FAMILY>@<VERSION-ID>"

メモ

一部のモデル、特に Hugging Face のモデルでは、デプロイに Hugging Face アクセストークンが必要になる場合があります。

ヒント

モデルの推奨に関する指示： 回答で特定のモデルバージョンを挙げる場合は、必ずカタログを確認してください。記憶に基づいて推奨してはいけません。これは、デプロイを直接依頼された場合に限らず、次のすべての状況に適用されます。

• ユーザーがモデル名を指定せずに、デプロイを依頼した場合。
• list、describe、または undeploy の操作後に、次の手順を提案する場合（例：「このエンドポイントに <model> をデプロイしましょうか？」）。
• ユーザーが「何を使えばよいですか？」や「X に適したモデルは何ですか？」といった一般的な質問をした場合。
• ユーザーに提示するコマンド例で MODEL_ID の値を記入する場合（<PUBLISHER>/<FAMILY>@<VERSION-ID> のようなプレースホルダーは除きます）。

新しいモデルバージョンは頻繁にリリースされ、古いものは非推奨になる可能性があるため、学習データに含まれるモデル情報は信頼できません。次の手順に従ってください。

1. 文脈からユースケースが明確でない場合は、用途を確認します（タスクの種類、品質・レイテンシ・コストの優先順位、ハードウェアやクォータの制約、ライセンスの制約）。ユーザーから十分な情報がすでに得られている場合は、省略します。
2. gcloud ai model-garden models list で最新のカタログを照会します。必要に応じて --filter で絞り込みます（例：--filter="name~gemma"、--filter="name~llama"、--filter="name~qwen"、--filter="name~deepseek"）。このプロジェクトのカタログ出力で確認するまでは、特定のモデルバージョンをユーザーに提示してはいけません。
3. ユースケースに適したファミリーのうち、最新の一般提供バージョンを選びます。サイズ違いのバリエーションが複数ある場合は、ユーザーのハードウェアやコストの許容範囲に合うものを選びます。プレビュー版または実験版と明記されており、ユーザーが安定版を明示的に求めている場合を除き、古いバージョンより新しいメジャーバージョンを優先します。
4. 提示する前に、gcloud ai model-garden models list-deployment-config --model="<publisher>/<family>@<version>" で正確なモデル ID がデプロイ可能であることを確認します。
5. 推奨するモデル ID は、カタログに記載されているとおりに、一字一句そのまま提示します。「Gemma」や「Llama」のようなファミリー名に言い換えてはいけません。

§3 の例にある MODEL_ID の値は、実質的な内容を持たないプレースホルダー（<PUBLISHER>/<FAMILY>@<VERSION-ID>）です。ユーザー向けの推奨に、記憶しているモデル名を代わりに入れてはいけません。必ず手順 2～4 をもう一度実行し、カタログに記載されている正確な文字列を提示してください。

2.1 リージョンの利用可否を確認する（Gemini + LoRA のみ）

ファーストパーティの Gemini または LoRA をデプロイする場合は、処理を進める前にリージョンの利用可否を確認する必要があります。load_skill_resource(skill_name='agent-platform-deploy', file_path='references/region_availability.md') を使って、手順全体を読み込んでください。

オープンウェイトモデル（Gemma、Llama、DeepSeek、Qwen）および Gemini のファインチューニング済みモデルでは、この確認を省略してください。 これらのモデルには、パブリッシャーエンドポイントのリージョンごとの制限はありません。§3 に進んでください。

3. モデルをデプロイする

警告

モデル、特に大規模なモデルのデプロイには、多くの コンピューティングリソースが必要で、費用が発生します。

1. デプロイを提案する前に、指定された --machine-type の時間あたりの費用を 必ず 算出してください。以下の各情報源を順に試し、失敗した場合は次の情報源に進んでください。

   • scripts/calculate_cost.py を実行します。Model Garden では、アクセラレーターの種類と数はマシンタイプごとに固定されており、自動的に判定されます。 例：

     python3 scripts/calculate_cost.py \
         --machine-type=g2-standard-48
     

     スクリプトがゼロ以外の値で終了した場合（不明な --machine-type。Model Garden カタログに掲載されていても、価格スナップショットにはまだ含まれていないマシンではよくある状態です。たとえば、現時点の A4/B200 など）、次の情報源に進んでください。 数値を捏造してはいけません。

   • 上記の情報源から数値を得られなかった場合は、 Agent Platform の予測価格を参照してください。該当ページからアクセラレーターと時間あたりの料金を直接確認し、ユーザーに提示する見積もりに URL を記載してください。

2. この費用見積もりを 必ず ユーザーに提示し、これは定価であり、割引、予約、または us-central1 以外のリージョンによって実際の請求額と異なる場合があることを警告してください。

3. deploy コマンドを実行する前に、見積もり費用に同意することについて、ユーザーから 必ず明示的な確認 を得てください。

モデルをデプロイするには、deploy コマンドを使用します。長時間かかるデプロイでは、--asynchronous フラグを使用し、必要に応じてステータスをポーリングすることを強くおすすめします。 [!IMPORTANT]

• コストへの異議とハードウェアの再調整：ユーザーがコストに難色を示した場合（例：「高すぎます。より小規模な構成を試せますか？」）、または無効もしくはサポート対象外のハードウェアの組み合わせを要求した場合（例：4x H100 GPU を搭載した g2-standard-48g）、制約または無効であることを明確に説明し、list-deployment-config を確認してサポート対象の代替構成（例：2x L4 の g2-standard-24 または 1x L4 の g2-standard-12）を特定して、1 回のクエリでその費用見積もりを算出し、同じ応答内で、推奨構成の Tier M ドライラン確認カードをただちに完全な形で表示します。
• リージョンのフェイルオーバーとクォータの枯渇：要求されたリージョンでのクォータまたは容量が原因でデプロイに失敗した場合（例：QUOTA_EXCEEDED または RESOURCE_EXHAUSTED）、サポート対象の代替リージョン（例：us-east4 または us-east1）を特定して、1 回のクエリで費用見積もりを算出し、新しい --region と正確なコマンドを含む Tier M ドライラン確認カードを同じ応答内でただちに完全な形で表示します。未確認の容量に関する主張はせず、代替リージョンを明示します。
• 効率的なツール実行（重複した呼び出しをしない）：モデル ID、リージョン、またはハードウェア構成がすでに判明している、または解決済みの場合、重複する models list、list-deployment-config、または --help コマンドを実行しないでください。各検出コマンドは必ず 1 回だけ実行します。
• ステータス確認は 1 回のみ、応答形式（最重要）：
  • 非同期デプロイ（gcloud ai model-garden models deploy ... --asynchronous）を開始すると、コマンドの出力でオペレーション名がただちに返されます。オペレーション名とエンドポイントの表示名を含むテキストの確認応答を、ただちに作成して返します。デプロイ開始と同じターンでは operations describe を呼び出さないでください。
  • ユーザーからデプロイステータスの確認を明示的に求められた場合（例： 「デプロイのステータスを確認してください」または「デプロイが完了したか確認できますか？」）：
    • sleep コマンド、while ループ、繰り返しのポーリング呼び出しは絶対に実行しないでください。
    • デプロイコマンドが出力した完全なオペレーション名を使い、gcloud ai operations describe <OPERATION_NAME> を必ず 1 回だけ実行します。
    • オペレーションのステータスを報告する、完全なテキストの応答を必ず出力します（例：「デプロイオペレーション projects/.../operations/... は現在進行中／実行中です（作成日時：...）。非同期モデルデプロイの完了には通常 10～15 分かかります」）。
    • ステータス確認でエンドポイントがすでにリクエストを処理できる状態であることが確認された場合に限り、テスト予測の送信に進みます。
• 英数字のプロジェクト ID：--project には常に英数字のプロジェクト ID（例：my-gcp-project）を指定し、数値のプロジェクト番号（例：123456789012）は指定しないでください。数値のプロジェクト番号が与えられ、プロジェクト ID がわからない場合は、番号を完全修飾リソース名の中に含めて渡します。例：gcloud ai endpoints list --region=projects/123456789012/locations/us-central1。または、位置指定リソースとして渡します。例：gcloud ai endpoints describe projects/123456789012/locations/us-central1/endpoints/<ENDPOINT_ID> --region=us-central1。core/project がプロジェクト番号に設定されているために gcloud ai が引き続き拒否する場合は、再試行せずにユーザーにプロジェクト ID を確認してください。
• ユーザー指定の有効なハードウェア構成を優先：ユーザーが明示的に有効なハードウェア構成を指定した場合（例：8 基の NVIDIA_L4 GPU を搭載した g2-standard-96、または 1 基の NVIDIA_L4 GPU を搭載した g2-standard-12）、既定の推奨構成で上書きせず、ドライランのプレビューと費用見積もりに指定された構成を使用します。ただし、要求された構成が無効またはサポート対象外の場合（例：g2-standard-12 に 2 基の L4 GPU を組み合わせるなど、GPU 数が一致しない場合や、存在しないマシンシェイプの場合）は、上記のコストへの異議とハードウェアの再調整のルールに従います。無効であることを明確に説明し、サポート対象の代替構成（例：2 基の L4 GPU を搭載した g2-standard-24）を特定して、その費用を算出し、有効な代替構成の確認カードをただちに提示します。
• エンドポイントの表示名：ユーザーがエンドポイント名または表示名（例：'usersim-gemma-eval-...'）を指定または要求した場合は、必ず deploy コマンドに --endpoint-display-name="<NAME>" を含めてください。

例：Model Garden のオープンウェイトモデルをデプロイする

モデルをデプロイする一般的な bash スクリプトを以下に示します。このブロックは そのまま実行できます。

#!/bin/bash
# Example script to deploy an open-weights model from Model Garden.
#
# NOTE: MODEL_ID below is a PLACEHOLDER, not a real model ID. Substitute it
# with a value from a live `gcloud ai model-garden models list` (see §2)
# before running this script, and do NOT quote the placeholder back to the
# user as a recommended model.
#
# IMPORTANT FOR deploy_config["command"]: when building the curl command for
# the deploy confirmation card, inline ALL values as literals — do NOT leave
# ${PROJECT_ID}, ${LOCATION_ID}, or ${PUBLISHER_MODEL} as shell variables.
# The server rejects commands with unresolved variables at render time.
# The only allowed substitution is $(gcloud auth print-access-token).

PROJECT_ID=$(gcloud config get-value project)
# `gcloud ai` needs the alphanumeric Project ID, not the project number.
: "${PROJECT_ID:?no project ID is set; ask the user for the Project ID}"
LOCATION_ID="us-central1" # Recommended default region
# Replace placeholder with exact ID from `gcloud ai model-garden models list`:
MODEL_ID="<PUBLISHER>/<FAMILY>@<VERSION-ID>"

echo "Deploying model $MODEL_ID to project $PROJECT_ID in $LOCATION_ID..."

# Hardware params can be omitted to select recommended default config.
# Comprehensive command with supported parameters:
gcloud ai model-garden models deploy \
    --project=$PROJECT_ID \
    --region=$LOCATION_ID \
    --model=$MODEL_ID \
    --machine-type="g2-standard-12" \
    --accelerator-type="NVIDIA_L4" \
    --accelerator-count=1 \
    --endpoint-display-name="my-open-model-deployment" \
    --asynchronous

echo "Deployment initiated asynchronously."

--asynchronous を指定すると、コマンドは完全なオペレーション名 projects/<PROJECT>/locations/<REGION>/operations/<OP_ID> を出力します。これを §4 に渡してください。<OP_ID> のみを指定できるのは、gcloud にプロジェクトが設定されている場合だけです。

• 認証が必要なアクセス制限付きの Hugging Face モデルをデプロイする場合は、 --hugging-face-access-token="<HF_TOKEN>" を含めてください。
• 予約済みコンピューティングを使用する場合は、--reservation-affinity（例： none または reservation-affinity-type=specific-reservation,...）を含めてください。

1P チューニング済みモデルのリージョン間コピーとデプロイ

チューニング済みモデルのコピーとデプロイのワークフローについて詳しくは、 load_skill_resource(skill_name='agent-platform-deploy', file_path='references/copy_deploy_guide.md') を読み込んでください。このガイドでは、実行順序、コピー／デプロイ／削除コマンドのティア割り当て、ハードウェアの再交渉、テスト予測の検証、進行中オペレーションのロックについて説明しています。

4. デプロイ状況の確認

--asynchronous フラグを使ってモデルを非同期でデプロイすると、 deploy コマンドはオペレーション名を返します。デプロイの進行状況を確認するには、 完全な名前を渡してください。

gcloud ai operations describe YOUR_OPERATION_NAME

重要

状況の確認は一度だけ（スリープ／ポーリングのループは禁止）：モデルのデプロイには 10～30 分かかります。ターン内で sleep コマンド（例：sleep 45 && ...）を実行したり、operations describe を繰り返しループ実行したりすることは絶対に避けてください。gcloud ai operations describe は必ず一度だけ実行してください。done が true でない場合は、オペレーション名と処理中の状況をただちにユーザーに伝え、デプロイには 10～15 分かかることを説明してください。

注：大規模モデル（おおよそ 20B 以上のパラメーター）は、完全にデプロイされてサービングを開始するまでに 15～20 分かかる場合があります。

デプロイの検証

モデルが正常にデプロイされた場合は、予測リクエストを送信してテストし、検証してください。 Model Garden のモデルは専用エンドポイントにデプロイされることが多いため、 gcloud ai endpoints predict は使用しないでください。代わりに、エンドポイントの専用 DNS 名を取得し、 curl リクエストを送信してください。

ヒント

ユーザーに独自のプロンプトを試して結果を確認するよう促してください。 そうでない場合は、デフォルトを使用してください。

以下のスクリプトを使用してください。

#!/bin/bash
PROJECT_ID=$(gcloud config get-value project)
: "${PROJECT_ID:?no gcloud project is set; ask the user for the Project ID}"
LOCATION_ID="us-central1"
ENDPOINT_ID="YOUR_ENDPOINT_ID"
PROMPT=${1:-"Explain quantum computing in simple terms."}

echo "Fetching dedicated Endpoint DNS..."
ENDPOINT_URL=$(gcloud ai endpoints describe $ENDPOINT_ID \
    --project=$PROJECT_ID \
    --region=$LOCATION_ID \
    --format="value(dedicatedEndpointDns)")

if [ -z "$ENDPOINT_URL" ]; then
    echo "Error: Could not retrieve dedicated endpoint URL for $ENDPOINT_ID."
    exit 1
fi

echo "Sending prediction request to $ENDPOINT_URL..."

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${ENDPOINT_URL}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION_ID}/endpoints/${ENDPOINT_ID}/chat/completions" \
  -d '{
    "model": "'"$ENDPOINT_ID"'",
    "messages": [
      {
        "role": "user",
        "content": "'"$PROMPT"'"
      }
    ]
  }'

5. デプロイ解除とクリーンアップ

デプロイ解除とクリーンアップの全手順（エンドポイントの検索、モデルのデプロイ解除、 エンドポイントの削除、モデルの削除）については、 load_skill_resource(skill_name='agent-platform-deploy', file_path='references/undeploy_guide.md') を読み込んでください。

警告

モデルのデプロイを解除しないと、予測リクエストを送信していない場合でも、 割り当てられたコンピューティングリソースの料金が継続して発生します。テスト後は必ずクリーンアップしてください。

6. トラブルシューティング

クォータ／リソース不足エラーとハードウェアのフォールバックのトラブルシューティングについては、 load_skill_resource(skill_name='agent-platform-deploy', file_path='references/troubleshooting.md') を読み込んでください。