agent-platform-deploy

Agent Platform Model Garden Deploy Skill

本 Skill 提供將開放模型（Open Models）從 Agent Platform Model Garden 部署至端點，以及後續解除部署以清理資源的指引說明。

1P 微調模型複製與部署

如果您需要將 **1P（第一方）微調模型（1P Tuned Model）**從來源專案複製至目標區域或專案，並部署到新建立的端點，請參閱 1P 微調模型複製與部署指南。

安全性與確認分級（極重要）

代表使用者執行任何命令之前，您必須根據要求的操作嚴格遵守以下安全性分級：

1. Tier R：唯讀（list、describe、list-deployment-config）
   • 規則：無需確認。您可以立即執行這些命令，為使用者收集資訊。
2. Tier M：變更且可逆（deploy、undeploy-model）
   • 規則：需要使用者明確確認。您必須向使用者展示清晰的確認提示，說明預計執行的命令。您必須等待使用者明確確認後才能執行。針對 undeploy-model，您必須先驗證端點與已部署的模型是否存在；若 describe 或 list 回傳 404 或空結果，您必須停止操作並通知使用者，而非盲目嘗試解除部署。
3. Tier D：破壞性且不可逆（delete）
   • 規則：需要手動輸入文字的明確確認。在執行刪除命令前，您必須輸出一段文字訊息，說明刪除端點或模型具備不可逆性，並要求使用者輸入 "I confirm" 或 "Yes, delete it"。

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>"

[!NOTE] 部分模型（特別是 Hugging Face 模型）在部署時可能需要 Hugging Face 存取權杖（Access Token）。

[!TIP] 模型推薦指引： 每當您準備在回覆中指名特定的模型版本時，切勿憑記憶進行推薦。這適用於以下所有情境——不限於直接部署請求：

• 使用者要求部署模型但未指定具體模型名稱。
• 您在執行 list、describe 或 undeploy 操作後主動提供下一步建議（例如：「您是否希望我將 <model> 部署至此端點？」）。
• 使用者提出一般性的「我該使用什麼？」／「針對 X 需求有哪些好用的模型？」等問題。
• 您在向使用者展示的範例命令中填入 MODEL_ID 值（相較於像 <PUBLISHER>/<FAMILY>@<VERSION-ID> 這樣的預留位置）。

由於新模型版本發布頻繁，而舊版本可能會被廢棄，因此僅憑訓練語料庫記憶的模型資訊並不可靠。請遵守以下程序：

1. 釐清使用情境（若上下文尚未明確，包括任務類型、品質 vs. 延遲 vs. 成本優先順序、硬體／配額限制、授權限制）。若使用者已提供足夠訊號則可跳過。
2. 查詢即時目錄：執行 gcloud ai model-garden models list。必要時使用 --filter 進行過濾（例如 --filter="name~gemma"、--filter="name~llama"、--filter="name~qwen"、--filter="name~deepseek"）。在您親自在該專案的目錄輸出中看到該模型前，切勿向使用者指名特定的模型版本。
3. 選擇該系列中最新正式釋出（GA）的版本且符合使用情境者。當存在多種尺寸變體時，選擇符合使用者硬體／成本承受度的版本。除非標示為預覽版／實驗版且使用者明確要求穩定選項，否則優先選擇較新的主要版本。
4. 驗證確切的模型 ID 是否可部署：在回覆中指名之前，先執行 gcloud ai model-garden models list-deployment-config --model="<publisher>/<family>@<version>" 進行確認。
5. 在推薦中原樣引用模型 ID，完全照目錄中顯示的字串輸出。請勿改寫為系列標籤（如「Gemma」、「Llama」）。

下方 §3 範例中的 MODEL_ID 值均為故意設定的無實質意義預留位置（<PUBLISHER>/<FAMILY>@<VERSION-ID>）。向使用者提供推薦時，切勿用記憶中的模型名稱替換它們——務必先重新執行步驟 2-4，然後引用目錄中的確切字串。

2.1 發布者端點的區域可用性檢查（Gemini + LoRA 基底）

[!NOTE] 若使用者要求部署 Model Garden 的開放權重模型（Gemma、Llama、DeepSeek、Qwen 或任何使用者提供的權重）——即透過 gcloud ai model-garden models deploy 提供服務至專用端點的任何模型，請跳過本節。這些模型沒有個別區域的可用性限制，Model Garden 目錄是全域性的。罕見區域真正的失敗模式為：(a) 要求的加速器／機器類型在該區域未提供，或 (b) 專案沒有配額——這兩者都會在準備配置資源前的部署階段顯示明確錯誤（§3 的成本確認關卡會攔截它們）。請直接跳至 §3。

僅在使用者要求提供第一方代管的 Gemini 模型（google/gemini-*）或微調後的 Gemini LoRA 適配器（adapter）服務時，才適用本節——這兩者均透過區域可用性確實有所差異的發布者端點進行路由。

在回覆任何針對第一方代管模型（google/gemini-*）或微調 Gemini LoRA 適配器指定特定區域的部署請求之前，您必須透過發起即時 API 呼叫，驗證該模型在該區域是否確實可用。切勿依賴 Google 搜尋、訓練語料庫知識或發布者說明文件來斷定可用性——區域可用性變動頻繁，接地文本（grounded text）可能會過期或錯誤。

僅能針對使用者詢問的確切模型與區域進行探測。切勿探測其他模型作為「對照組」——您無法從模型 B 的狀態推斷模型 A 的可用性，因為另一個模型本身可能因無關的原因在參考區域中不可用。

針對第一方發布者模型（google/*），請使用包含最少有效載荷（payload）的真實 :generateContent 呼叫進行探測：

curl -sS -o /dev/null -w "%{http_code}\n" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://${LOCATION_ID}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION_ID}/publishers/google/${MODEL_ID}:generateContent" \
    -d "{\"contents\":{\"role\":\"user\",\"parts\":{\"text\":\"${PROBE_TEXT:-hi}\"}}}"

針對微調 Gemini LoRA 模型（在基底 Gemini 模型之上部署使用者微調的適配器），請使用上述相同的 :generateContent 呼叫，將 ${MODEL_ID} 設定為基底模型（例如若適配器基於 gemini-2.5-flash 進行微調，則設為 gemini-2.5-flash），在目標區域探測基底模型。LoRA 適配器無法在基底模型不可用的區域中提供服務。

解讀探測結果並採取行動：

• 200 — 模型在該區域可用。繼續進行部署。
• 404 — 模型在該區域不可用。停止操作。明確告訴使用者該模型在該區域未提供服務，並列出可用的區域（透過執行不帶 --region 的 gcloud ai model-garden models list --filter="name~$MODEL_NAME" 取得）。切勿靜默切換區域。切勿繼續為不支援的區域撰寫部署程式碼或 SDK 初始化邏輯。切勿執行額外的「對照」探測來再次確認 404——目標區域的探測結果具有權威性。
• 任何其他結果（權限不足、配額問題、暫時性失敗等）——請勿擅自斷定模型可用或不可用。請用易懂的語言說明背後原因（例如「您的帳號沒有此專案 Vertex AI API 的存取權限——請在主控台中啟用或切換專案」），並提供具體的下一步行動建議。

3. 部署模型

[!WARNING] 部署模型（特別是大型模型）會消耗大量算力資源並產生費用。

1. 您必須參考 Agent Platform 預測定價，根據要求的 --machine-type 與 --accelerator-type（及數量）計算粗略的估算成本。
2. 您必須向使用者展示此估算成本，並警告此金額為牌價（list price），因潛在的折扣或預留容量，實際帳單金額可能會有所不同。
3. 在執行任何 deploy 命令前，您必須隨時向使用者尋求明確確認，同意估算成本後方可執行。

若要部署模型，請使用 deploy 命令。強烈建議針對耗時較長的部署作業使用 --asynchronous 標記，必要時再輪詢（poll）狀態。

範例：從 Model Garden 部署開放權重模型

以下是部署模型的典型 Bash 腳本。您可以直接執行此區塊。

#!/bin/bash
# 從 Model Garden 部署開放權重模型的範例腳本。
#
# 注意：下方的 MODEL_ID 為預留位置（PLACEHOLDER），非真實模型 ID。在執行此腳本前，
# 請先將其替換為即時 `gcloud ai model-garden models list` 輸出的值（參閱 §2），
# 且切勿將此預留位置直接作為推薦模型回覆給使用者。

PROJECT_ID=$(gcloud config get-value project)
LOCATION_ID="us-central1" # 推薦的預設區域
MODEL_ID="<PUBLISHER>/<FAMILY>@<VERSION-ID>" # 預留位置 — 請替換為 `gcloud ai model-garden models list` 中的確切 ID

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

# 若省略硬體參數，Model Garden 可根據 list-deployment-config 自動選擇所需的硬體。
# 下方為包含所有受支援參數的完整命令：
gcloud ai model-garden models deploy \
    --project=$PROJECT_ID \
    --region=$LOCATION_ID \
    --model=$MODEL

<!-- truncated for translation batch; full body continues in source -->