部署使用自訂權重的模型

部署具備自訂權重的模型為預先發布版功能。您可以根據預先定義的基本模型微調模型，並在 Gemini Enterprise Agent Platform Model Garden 部署自訂模型。您可以將模型構件上傳至專案中的 Cloud Storage bucket，使用自訂權重匯入功能部署自訂模型，在 Agent Platform 中一鍵即可完成。

VPC Service Controls 支援自訂權重。

支援的模型

下列基礎模型支援使用自訂權重部署模型的公開測試：

模型名稱 版本
Llama
  • Llama-2：7B、13B
  • Llama-3.1：8B、70B
  • Llama-3.2：1B、3B
  • Llama-4：Scout-17B、Maverick-17B
  • CodeLlama-13B
Gemma
  • Gemma-2：9B、27B
  • Gemma-3：1B、4B、3-12B、27B
  • Gemma-4：26B-A4B-it、31B-it、E2B-it、E4B-it
  • Medgemma：4B、27B-text
Qwen
  • Qwen2：1.5B
  • Qwen2.5：0.5B、1.5B、7B、32B
  • Qwen3：0.6B、1.7B、4B、8B、32B、Qwen3-Coder-480B-A35B-Instruct、Qwen3-Next-80B-A3B-Instruct、Qwen3-Next-80B-A3B-Thinking、Qwen3-VL-8B-Instruct
  • Qwen3.5：9B
  • Qwen3.6：27B、35B A3B
Deepseek
  • Deepseek-R1
  • Deepseek-V3
  • DeepSeek-V3.1
Mistral 和 Mixtral
  • Mistral-7B-v0.1
  • Mixtral-8x7B-v0.1
  • Mistral-Nemo-Base-2407
Phi-4
  • Phi-4-reasoning
OpenAI OSS
  • gpt-oss：20B、120B

限制

自訂權重不支援匯入量化模型。

模型檔案

您必須提供 Hugging Face 權重格式的模型檔案。如要進一步瞭解 Hugging Face 權重格式，請參閱「使用 Hugging Face 模型」。

如未提供必要檔案，模型部署作業可能會失敗。

下表列出模型檔案類型，這些類型取決於模型架構：

模型檔案內容 檔案類型
模型設定
  • config.json
模型權重
  • *.safetensors
  • *.bin
權重索引
  • *.index.json
Tokenizer 檔案
  • tokenizer.model
  • tokenizer.json
  • tokenizer_config.json

位置

您可以在所有區域透過 Model Garden 服務部署自訂模型。

必要條件

本節說明如何部署自訂模型。

事前準備

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. 在 Cloud de Confiance 控制台啟用 Cloud Shell。

    啟用 Cloud Shell

    Cloud de Confiance 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

本教學課程假設您使用 Cloud Shell 與 Cloud de Confiance by S3NS互動。如要使用 Cloud Shell 以外的其他殼層，請執行下列額外設定：

  1. 安裝 Google Cloud CLI。

  2. 設定 gcloud CLI，使用您的聯合身分。

    詳情請參閱「 使用聯合身分登入 gcloud CLI」。

  3. 執行下列指令，初始化 gcloud CLI：

    gcloud init

部署自訂模型

本節說明如何部署自訂模型。

如果您使用指令列介面 (CLI)、Python 或 JavaScript，請將下列變數替換為值，程式碼範例才能運作：

  • REGION：您所在的區域。例如：uscentral1。
  • MODEL_GCS：您的 Cloud de Confiance by S3NS 模型。例如：gs://custom-weights-fishfooding/meta-llama/Llama-3.2-1B-Instruct。
  • PROJECT_ID：專案 ID。
  • MODEL_ID：模型 ID。
  • MACHINE_TYPE：機器類型。例如：g2-standard-12。
  • ACCELERATOR_TYPE：加速器類型。例如：NVIDIA_L4。
  • ACCELERATOR_COUNT：加速器數量。

  • PROMPT：文字提示詞。

控制台

下列步驟說明如何使用 Cloud de Confiance 控制台，部署具有自訂權重的模型。

  1. 前往 Cloud de Confiance 控制台的「Model Garden」頁面。

    前往 Model Garden

  2. 按一下「Deploy model with custom weights」(部署模型並自訂權重)。「Deploy a model with custom weights」(部署具有自訂權重的模型) 窗格隨即顯示。

  3. 在「Model source」(模型來源) 部分，執行下列操作：

    1. 按一下「Browse」(瀏覽)，選擇儲存模型的 bucket，然後按一下「Select」(選取)。

    2. (選用) 在「Model name」(模型名稱) 欄位中輸入模型名稱。

  4. 在「Deployment settings」(部署作業設定) 部分，執行下列操作：

    1. 在「Region」(區域) 欄位中選取區域，然後按一下「OK」(確定)。

    2. 在「Machine Spec」(機器規格) 欄位中，選取用於部署模型的機器規格。

    3. 選用：根據預設，「Endpoint name」(端點名稱) 欄位會顯示模型的端點。不過，您可以在欄位中輸入其他端點名稱。

    4. 如果專案強制執行 VPC-SC，或您偏好私人存取權，請在「Endpoint access」(端點存取權) 欄位中選取「Private (Private Service Connect)」(私人 (Private Service Connect))。否則請選取「公開」。

    5. 如果您使用 Private Service Connect，請在「Project IDs」(專案 ID) 欄位中輸入專案 ID，也就是查詢用戶端執行的專案，或按一下「Select project IDs」(選取專案 ID)，顯示包含專案 ID 的對話方塊。

      如果點選「選取專案 ID」，請執行下列操作：

      1. 找出含有嘗試存取模型程式碼的專案。
      2. 按一下專案的核取方塊。
      3. 按一下「選取」。

  5. 點選「Deploy」(部署)。

gcloud CLI

這個指令示範如何將模型部署至特定區域。

gcloud ai model-garden models deploy --model=${MODEL_GCS} --region ${REGION}

這個指令示範如何將模型部署至特定區域，並指定機型、加速器類型和加速器數量。如要選取特定機器設定，則必須設定這三個欄位。

gcloud ai model-garden models deploy --model=${MODEL_GCS} --machine-type=${MACHINE_TYE} --accelerator-type=${ACCELERATOR_TYPE} --accelerator-count=${ACCELERATOR_COUNT} --region ${REGION}

Python

import vertexai
from google.cloud import aiplatform
from vertexai.preview import model_garden

vertexai.init(project=${PROJECT_ID}, location=${REGION})
custom_model = model_garden.CustomModel(
  gcs_uri=GCS_URI,
)
endpoint = custom_model.deploy(
  machine_type="${MACHINE_TYPE}",
  accelerator_type="${ACCELERATOR_TYPE}",
  accelerator_count="${ACCELERATOR_COUNT}",
  model_display_name="custom-model",
  endpoint_display_name="custom-model-endpoint")

endpoint.predict(instances=[{"prompt": "${PROMPT}"}], use_dedicated_endpoint=True)

或者，您不必將參數傳遞至 custom_model.deploy() 方法。

import vertexai
from google.cloud import aiplatform
from vertexai.preview import model_garden

vertexai.init(project=${PROJECT_ID}, location=${REGION})
custom_model = model_garden.CustomModel(
  gcs_uri=GCS_URI,
)
endpoint = custom_model.deploy()

endpoint.predict(instances=[{"prompt": "${PROMPT}"}], use_dedicated_endpoint=True)

curl 


curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}:deploy" \
  -d '{
    "custom_model": {
    "gcs_uri": "'"${MODEL_GCS}"'"
  },
  "destination": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'",
  "model_config": {
     "model_user_id": "'"${MODEL_ID}"'",
  },
}'

或者，您也可以使用 API 明確設定機器類型。


curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}:deploy" \
  -d '{
    "custom_model": {
    "gcs_uri": "'"${MODEL_GCS}"'"
  },
  "destination": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'",
  "model_config": {
     "model_user_id": "'"${MODEL_ID}"'",
  },
  "deploy_config": {
    "dedicated_resources": {
      "machine_spec": {
        "machine_type": "'"${MACHINE_TYPE}"'",
        "accelerator_type": "'"${ACCELERATOR_TYPE}"'",
        "accelerator_count": '"${ACCELERATOR_COUNT}"'
      },
      "min_replica_count": 1
    }
  }
}'

使用 API 部署

VPC Service Controls 僅適用於私人專屬端點。因此，您必須在下列程式碼範例中設定 private_service_connect_config，該範例示範如何使用 API 部署：

curl 

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/YOUR_PROJECT/locations/us-central1:deploy" \
    -d '{
      "custom_model": {
        "model_id": "test-mg-deploy-092301",
        "gcs_uri": "gs://YOUR_GCS_BUCKET"
      },
      "destination": "projects/YOUR_PROJECT/locations/us-central1",
      "endpoint_config": {
        "endpoint_display_name": "psc-ep1",
        "private_service_connect_config": {
          "enablePrivateServiceConnect": true,
          "projectAllowlist": ["YOUR_PROJECT"]
        }
      },
      "deploy_config": {
        "dedicated_resources": {
          "machine_spec": {
            "machine_type": "g2-standard-24",
            "accelerator_type": "NVIDIA_L4",
            "accelerator_count": 2
          },
          "min_replica_count": 1,
          "max_replica_count": 1
        }
      }
    }'

使用 Cloud de Confiance 控制台取得端點 ID 和模型 ID

部署完成後，請按照下列步驟操作：

  1. 前往 Cloud de Confiance 控制台的「Model Garden」頁面。

    前往 Model Garden

  2. 按一下「查看我的端點與模型」。

  3. 在「My endpoints」(我的端點) 表格中，從「Name」(名稱) 欄查看剛才部署的端點。系統隨即會顯示「Details」(詳細資料) 頁面。

  4. 在「Deployed models」(已部署的模型) 表格中，點選模型。

  5. 選取「版本詳細資料」頁面。模型 ID 會顯示在表格的「Environment variables」(環境變數) 列中。

設定 Private Service Connect

您正在新增端點，以便存取 S3NS API。這個端點可在所選虛擬私有雲網路的所有區域中使用。此外，請考量下列事項：

  • 如果網路利用混合式連線連上端點的虛擬私有雲網路，位處其中的用戶端即可存取該端點。詳情請參閱「透過端點存取S3NS API」。
  • 如果是對接虛擬私有雲網路中的用戶端，就無法存取這個端點。

列出端點以取得服務連結

下列程式碼範例示範如何列出端點，以取得服務連結。

curl 

$ curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/YOUR_PROJECT/locations/us-central1/endpoints/YOUR_ENDPOINT_ID"

這是清單端點回應。

  {
  "name": "projects/440968033208/locations/us-central1/endpoints/mg-endpoint-2c6ae2be-1491-43fe-b179-cb5a63e2c955",
  "displayName": "psc-ep1",
  "deployedModels": [
    {
      "id": "4026753529031950336",
      "model": "projects/440968033208/locations/us-central1/models/mg-custom-1758645924",
      "displayName": "null-null-null-1758645933",
      "createTime": "2025-09-23T16:45:45.169195Z",
      "dedicatedResources": {
        "machineSpec": {
          "machineType": "g2-standard-24",
          "acceleratorType": "NVIDIA_L4",
          "acceleratorCount": 2
        },
        "minReplicaCount": 1,
        "maxReplicaCount": 1
      },
      "enableContainerLogging": true,
      "privateEndpoints": {
        "serviceAttachment": "projects/qdb392d34e2a11149p-tp/regions/us-central1/serviceAttachments/gkedpm-fbbc4061323c91c14ab4d961a2f8b0"
      },
      "modelVersionId": "1",
      "status": {
        "lastUpdateTime": "2025-09-23T17:26:10.031652Z",
        "availableReplicaCount": 1
      }
    }
  ],
  "trafficSplit": {
    "4026753529031950336": 100
  },
  "etag": "AMEw9yPIWQYdbpHu6g6Mhpu1_10J062_oR9Jw9txrp8dFFbel7odLgSK8CGIogAUkR_r",
  "createTime": "2025-09-23T16:45:45.169195Z",
  "updateTime": "2025-09-23T17:13:36.320873Z",
  "privateServiceConnectConfig": {
    "enablePrivateServiceConnect": true,
    "projectAllowlist": [
      "ucaip-vpc-s-1605069239-dut-24"
    ]
  }
}

建立 Private Service Connect

如要建立 Private Service Connect (PSC)，請按照下列步驟操作：

  1. 前往 Cloud de Confiance 控制台的「Private Service Connect」頁面。系統隨即會顯示「Connected endpoints」(連結的端點) 頁面。

    前往「Private Service Connect」

  2. 按一下「+ 連結端點」。「Connect endpoint」(連結端點) 頁面隨即顯示。

  3. 從「Target」(目標) 欄位中選取所需選項。您可以選擇「Google APIs」(Google API)，存取大部分 S3NS API 和服務，或選擇「Published service」(已發布的服務)，存取已發布的服務。

  4. 在「Target details」(目標詳細資料) 區段中，從「Scope」(範圍) 清單中選取值，然後從「Bundle type」(套件類型) 清單中選取值。

  5. 在「Endpoint details」(端點詳細資料) 部分，執行下列操作：

    1. 在「Endpoint name」(端點名稱) 欄位輸入名稱。
    2. 從「Network」(網路) 清單中選取值。選取專案中的虛擬私有雲網路。如要在使用主專案內 Shared VPC 虛擬私有雲網路的服務專案建立 PSC 端點，請改用 Google Cloud CLI 或傳送 API 要求。
    3. 從「IP address」(IP 位址) 清單中選取值。

  6. 展開「Service Directory」部分。

  7. 從「Region」(區域) 清單中選取區域。

  8. 從「Namespace」(命名空間) 清單中選取命名空間。

  9. 按一下「新增端點」。「Endpoints」(端點) 表格會更新，並顯示新端點的資料列。

提出查詢

本節說明如何建立公開端點和私人端點。

對公開端點執行查詢

模型部署後，自訂權重會支援公開專屬端點。您可以使用 API 或 SDK 傳送查詢。

傳送查詢前，您必須先取得端點網址、端點 ID 和模型 ID，這些資訊可在 Cloud de Confiance 控制台找到。

請按照下列步驟取得資訊：

  1. 前往 Cloud de Confiance 控制台的「Model Garden」頁面。

    Model Garden

  2. 按一下「查看我的端點與模型」。

  3. 從「Region」(區域) 清單中選取區域。

  4. 如要取得端點 ID 和端點網址，請在「My endpoints」(我的端點) 區段中點選端點。

    端點 ID 會顯示在「Endpoint ID」(端點 ID) 欄位中。

    公開端點網址會顯示在「Dedicated endpoint」(專屬端點) 欄位中。

  5. 如要取得模型 ID，請在「Deployed models」(已部署的模型) 區段中找到您的模型，然後按照下列步驟操作：

    1. 在「Model」(模型) 欄位中，按一下已部署模型的名稱。
    2. 按一下「版本詳細資料」。模型 ID 會顯示在「Model ID」(模型 ID) 欄位中。

取得端點和已部署模型資訊後，請參閱下列程式碼範例，瞭解如何傳送推論要求，或參閱「將線上推論要求傳送至專屬公開端點」。

API

下列程式碼範例示範如何根據用途，以不同方式使用 API。

對話完成 (一元)

這項範例要求會將完整的即時通訊訊息傳送至模型，並在整個回覆生成後，以單一區塊的形式取得回覆。這就像傳送簡訊後，收到一則完整回覆。

  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}/endpoints/${ENDPOINT_ID}/chat/completions" \
    -d '{
    "model": "'"${MODEL_ID}"'",
    "temperature": 0,
    "top_p": 1,
    "max_tokens": 154,
    "ignore_eos": true,
    "messages": [
      {
        "role": "user",
        "content": "How to tell the time by looking at the sky?"
      }
    ]
  }'

對話完成 (串流)

這項要求是一元對話完成要求的串流版本。在要求中加入 "stream": true，模型就會在生成回覆時，逐步傳送回覆。這項功能適合用於在聊天應用程式中，建立即時打字機效果。

  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}/endpoints/${ENDPOINT_ID}/chat/completions" \
    -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "temperature": 0,
    "top_p": 1,
    "max_tokens": 154,
    "ignore_eos": true,
    "messages": [
      {
        "role": "user",
        "content": "How to tell the time by looking at the sky?"
      }
    ]
  }'

預測

這項要求會傳送直接提示，從模型取得推論。這通常用於不一定需要對話的工作，例如文字摘要或分類。

  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}/endpoints/${ENDPOINT_ID}:predict" \
    -d '{
    "instances": [
      {
        "prompt": "How to tell the time by looking at the sky?",
        "temperature": 0,
        "top_p": 1,
        "max_tokens": 154,
        "ignore_eos": true
      }
    ]
  }'

原始預測

這項要求是 Predict 要求的串流版本。這項要求使用 :streamRawPredict 端點並加入 "stream": true，會直接傳送提示，並在模型生成輸出內容時，以連續資料串流的形式接收輸出內容，類似於串流對話完成要求。

  curl -X POST \
    -N \
    --output - \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://${ENDPOINT_URL}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/${ENDPOINT_ID}:streamRawPredict" \
    -d '{
    "instances": [
      {
        "prompt": "How to tell the time by looking at the sky?",
        "temperature": 0,
        "top_p": 1,
        "max_tokens": 154,
        "ignore_eos": true,
        "stream": true
      }
    ]
  }'

SDK

這個程式碼範例會使用 SDK 向模型傳送查詢，並從模型取得回覆。

  from google.cloud import aiplatform

  project_id = ""
  location = ""
  endpoint_id = "" # Use the short ID here

  aiplatform.init(project=project_id, location=location)

  endpoint = aiplatform.Endpoint(endpoint_id)

  prompt = "How to tell the time by looking at the sky?"
  instances=[{"text": prompt}]
  response = endpoint.predict(instances=instances, use_dedicated_endpoint=True)
  print(response.predictions)

查詢私人端點

您可以在允許的專案中使用筆記本或 VM 測試查詢。

這項範例查詢可讓您將變數替換為 IP、專案、端點 ID 和模型 ID (從上述部署步驟取得)

curl

對話完成

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" 'https://YOUR_IP/v1beta1/projects/YOUR_PROJECT_ID/locations/YOUR_LOCATION/endpoints/YOUR_ENDPOINT_ID/chat/completions' -d '{ "model": "YOUR_MODEL_ID", "max_tokens": 300, "messages": [{ "role": "user", "content": "how to tell the time by looking at sky?" }]}'

預測

$ curl -k -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" 'https:/YOUR_IP/v1beta1/projects/YOUR_PROJECT_ID/locations/YOUR_LOCATION/endpoints/YOUR_ENDPOINT_ID:predict' -d '{
  "instances": [
    {
      "prompt": "Summarize Goog stock performance",
      "temperature": 0,
      "top_p": 1,
      "max_tokens": 154,
      "ignore_eos": true
    }
  ]
}'

如需另一個 API 使用範例，請參閱匯入自訂權重筆記本。

進一步瞭解 Gemini Enterprise Agent Platform 中自行部署的模型