agent-platform-deploy

Agent Platform Model Garden 部署 Skill

本 Skill 提供了将开源模型（Open Models）从 Agent Platform Model Garden 部署到端点，以及后续取消部署以清理资源的详细指南。

1P 微调模型拷贝与部署

如果你需要将 1P（第一方）微调模型 从源项目拷贝到目标区域或项目，并将其部署到新创建的端点，请参考
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）和区域（Region）。以下命令使用了占位符变量 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

要查看特定模型支持哪些机器类型（Machine Types）和加速器（Accelerators），可以传入上面 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（正式发布）版本：在同系列模型中选择合适版本。当存在多种尺寸变体时，挑选符合用户硬件/成本承受能力的那款。除非该版本被标记为预览版/实验版（preview/experimental）且用户明确要求选用稳定版本，否则优先选择较新的主版本。
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 Publisher 端点的区域可用性检查（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 适配器——这两者都需要通过 Publisher 端点进行路由，而 Publisher 端点的区域可用性确实因地区而异。

在对任何指定了特定区域的第一方托管模型（google/gemini-*）或微调后的 Gemini LoRA 适配器的部署请求作出回复前，你必须通过发起实时 API 调用，验证该模型在该区域是否真实可用。切勿依赖 Google 搜索、训练语料知识或官方 Publisher 文档来判断可用性——区域可用性变更频繁，相关固化文档可能已过期或存在偏差。

仅探测用户明确询问的精确模型和区域。切勿探测其他模型作为“对照组”——你无法通过模型 B 的状态去反推模型 A 的可用性，因为另一个模型在参考区域不可用可能是出于完全无关的原因。

对于第一方 Publisher 模型（google/*），使用最简有效载荷发起真实的 :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 标记，必要时再轮询部署状态。

示例：从 Model Garden 部署开源权重模型

以下是部署模型的典型 Bash 脚本。你可以直接运行此代码块：

#!/bin/bash
# 从 Model Garden 部署开源权重模型的示例脚本。
#
# 注意：下方的 MODEL_ID 为【占位符】，并非真实模型 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 "正在将模型 $MODEL_ID 部署到项目 $PROJECT_ID（区域：$LOCATION_ID）..."

# 如果省略硬件参数，Model Garden 可以根据 list-deployment-config 自动选择所需的硬件。
# 以下是包含所有受支持参数的完整命令：
gcloud ai model-garden models deploy \
    --project=$PROJECT_ID \
    --region=$LOCATION_ID \
    --model=$MODEL