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. 预计每小时费用（$/小时）。
     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 Access Token 才能部署。

提示

模型推荐说明： 每当你准备在回复中提及某个特定模型版本时，切勿凭记忆推荐。以下所有情况都适用，不仅限于直接部署请求：

• 用户要求部署模型，但没有指定模型。
• 在执行 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. 在提出部署方案之前，MUST 先计算所请求的 --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. MUST 向用户提供此费用预估，并警告用户这属于标价，由于 可能存在折扣、预留资源或使用非 us-central1 区域等情况，实际账单金额可能 与之不同。

3. 执行任何 deploy 命令之前，MUST ALWAYS 先征求用户明确确认其同意 预估费用。

要部署模型，请使用 deploy 命令。对于运行时间较长的部署，强烈建议使用 --asynchronous 标志，然后在必要时轮询状态。 [!IMPORTANT]

• 成本异议与硬件重新协商：如果用户对成本提出异议（例如：“太贵了，可以尝试更小的配置吗？”），或请求无效或不受支持的硬件组合（例如使用 4 张 H100 GPU 的 g2-standard-48g），请清楚说明限制或无效之处，检查 list-deployment-config 以确定受支持的替代方案（例如使用 2 张 L4 的 g2-standard-24，或使用 1 张 L4 的 g2-standard-12），通过单次查询计算其成本估算，并在同一响应中立即呈现该推荐配置的完整 Tier M 演练确认卡。
• 区域故障转移与配额耗尽：当部署因请求区域的配额或容量不足而失败时（例如 QUOTA_EXCEEDED 或 RESOURCE_EXHAUSTED），请确定一个受支持的替代区域（例如 us-east4 或 us-east1），通过单次查询计算其成本估算，并在同一响应中立即呈现包含新 --region 和准确命令的完整 Tier M 演练确认卡。直接说明替代区域，不要作出未经验证的容量声明。
• 高效执行工具（不重复调用）：如果模型 ID、区域或硬件配置已知或已确定，请勿执行重复的 models list、list-deployment-config 或 --help 命令。每个发现命令严格只运行一次。
• 单次状态检查与响应格式（至关重要）：
  • 启动异步部署时（gcloud ai model-garden models deploy ... --asynchronous），命令输出会立即返回操作名称。请立即组织并返回包含操作名称和端点显示名称的文本确认响应。启动部署的同一轮中不得调用 operations describe。
  • 当用户明确要求检查部署状态时（例如：“请检查部署状态”或“可以检查部署是否已完成吗？”）：
    • 绝不要运行 sleep 命令、while 循环或重复轮询调用。
    • 对部署命令打印的完整操作名称执行 gcloud ai operations describe <OPERATION_NAME>，严格只执行一次。
    • 始终输出完整的文本响应，报告操作状态（例如：“部署操作 projects/.../operations/... 当前正在进行／运行中（创建时间为 ...）。异步模型部署通常需要 10–15 分钟才能完成”）。
    • 只有状态检查确认端点已在提供服务且就绪后，才能发送测试预测。
• 字母数字 Project ID：--project 始终指定字母数字 Project ID（例如 my-gcp-project），而非数字项目编号（例如 123456789012）。如果用户提供的是数字项目编号，且 Project 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。如果 gcloud ai 仍因 core/project 设置为项目编号而拒绝执行，请向用户索取 Project ID，不要重试。
• 优先遵循用户指定的有效硬件配置：当用户指定明确且有效的硬件配置时（例如使用 8 张 NVIDIA_L4 GPU 的 g2-standard-96，或使用 1 张 NVIDIA_L4 GPU 的 g2-standard-12），在演练预览和成本估算中遵循用户请求的配置，而不要用默认推荐配置替代。不过，如果请求的配置无效或不受支持（例如 GPU 数量不匹配，如使用 2 张 L4 GPU 的 g2-standard-12，或不存在的机器规格），请遵循上述成本异议与硬件重新协商规则：清楚说明无效之处，确定受支持的替代方案（例如使用 2 张 L4 GPU 的 g2-standard-24），计算其成本，并立即呈现有效替代方案的确认卡。
• 端点显示名称：如果用户指定或请求了端点名称或显示名称（例如 'usersim-gemma-eval-...'），则部署命令中必须始终包含 --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： 只有在 gcloud 已设置项目时，单独的 <OP_ID> 才能使用。

• 部署需要身份验证的 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

重要

仅检查一次状态（不使用 sleep / 轮询循环）：模型部署操作需要 10–30 分钟。切勿运行 sleep 命令（例如 sleep 45 && ...），也不要在一轮操作中反复循环执行 operations describe。严格来说，只运行一次 gcloud ai operations describe。如果 done 不为 true，请立即向用户返回操作名称和进行中状态，并说明部署需要 10–15 分钟。

注意：大型模型（约 20B+ 参数）可能需要 15–20 分钟才能完成部署并开始提供服务。

验证部署

如果模型已成功部署，请发起预测调用进行测试。由于 Model Garden 模型通常部署到 Dedicated Endpoints，因此不应使用 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')。