管理修訂版本和流量

在 Gemini Enterprise Agent Platform 中，您可以建立代理的不可變更版本或修訂版本。然後將流量分配給不同的有效修訂版本。您可以透過流量拆分功能測試新修訂版本，並逐步增加流量，也可以基於其他目的在修訂版本之間拆分流量。

建立修訂版本的功能一律會啟用。你不需要開啟這項功能，如要瞭解如何建立修訂版本，請參閱「修訂版本和狀態」。

如果您尚未建立任何修訂版本，請先建立修訂版本，再查看修訂版本並設定修訂版本之間的流量，如本頁所述。

目前，修訂版本和流量分配功能可透過 v1beta1 API 使用。

本頁說明如何管理代理程式修訂版本和流量分配。

修訂版本和狀態

修訂版本是代理程式的快照。建立代理程式或更新代理程式的版本化欄位時，系統會建立代理程式的不可變更修訂版本。修訂版本可能處於下列狀態：

  • 有效：修訂版本可供查詢。請注意，視流量設定而定，該版本可能不會收到任何查詢。
  • 已淘汰：無法查詢修訂版本。

您可以透過修訂版本的資源名稱識別修訂版本，資源名稱可透過列出代理程式修訂版本取得。

有版本和無版本的欄位

本節列出已部署代理程式 ReasoningEngineSpec 定義中的欄位，您可以更新這些欄位來建立代理程式修訂版本。

更新版本化欄位時，系統會建立新的修訂版本。

更新未版本化的欄位，或代理程式定義中版本化欄位以外的欄位時，代理程式的所有修訂版本都會更新。

以下是已納入版本控管的欄位：

  • PackageSpec
    • pickleObjectGcsUri
    • dependencyFilesGcsUri
    • requirementsGcsUri
    • pythonVersion
  • DeploymentSpec
    • env[]
    • secretEnv[]
    • firstPartyImageOverride
    • agentServerMode
    • pscInterfaceConfig
    • minInstances
    • maxInstances
    • resourceLimits
    • containerConcurrency
  • classMethods[]
  • agentFramework
  • SourceCodeSpec
    • source
    • languageSpec
  • identityType
  • agentCard[]

列出代理程式修訂版本

您可以列出已部署代理的所有修訂版本，包括有效和已淘汰的版本。

如要找出代理程式的資源 ID，請參閱「取得代理程式資源 ID」。

控制台

  1. 在 Google Agent Platform 中，依序前往「管理」>「部署作業」。

    前往「Deployments」(部署作業)

  2. 按一下代理程式的名稱。

  3. 選取「修訂版本」分頁標籤。

  4. 頁面頂端會顯示修訂版本的相關資訊：

    1. 分割模式：可選擇「手動」或「最新」。詳情請參閱「管理修訂版本的流量」。
    2. 有效修訂版本：有效修訂版本數與修訂版本總數的比較結果。
    3. 最新修訂版本：最新修訂版本的名稱，以及該版本接收的流量百分比。
    4. 主要修訂版本：主要修訂版本的名稱，會接收大部分流量。

  5. 清單會顯示代理的所有修訂版本，包括下列資訊：

    1. 名稱：修訂版本名稱或編號。
    2. 狀態：修訂版本是否已部署或已淘汰。
    3. 流量：導向修訂版本的流量百分比。
    4. 建立時間：修訂版本的建立日期和時間。

Agent Platform SDK

下列程式碼會列出指定已部署代理程式的修訂版本記錄。如要列出修訂版本，請找出代理程式的專屬資源 ID。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revisions = client.agent_engines.runtimes.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

for revision in revisions:
    print(revision)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID

REST

呼叫 reasoningEngineRuntimeRevisions.list 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID。

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "reasoningEngineRuntimeRevisions": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
        "spec": {
          // Revision-specific config attributes (e.g., package specs, requirements)
        },
        "createTime": "2026-05-01T13:26:01Z",
        "state": "ACTIVE"
      }...
    ]
}

取得修訂版本的詳細資料

您可以擷取特定修訂版本的詳細資料。

Agent Platform SDK

下列程式碼會擷取指定已部署代理程式修訂版本的資源詳細資料：

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

print(revision)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

REST

呼叫 reasoningEngineRuntimeRevisions.get 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
  "spec": {
    // Revision-specific config attributes (e.g., package specs, requirements)
  },
  "createTime": "2026-05-06T13:05:24Z",
  "state": "ACTIVE"
}

設定修訂版本之間的流量分配

您可以管理流量在有效修訂版本之間的分配方式。請注意，只有導向根 reasoningEngine 資源的查詢會進行流量分割。直接將查詢導向特定修訂版本資源路徑，會明確略過流量規則。

流量分配方式有兩種：

  • 依百分比：依百分比設定時，指定百分比的流量會導向每個代理程式修訂版本。指定的百分比必須是整數。百分比總和必須等於 100%。即使只有 1 個有效修訂版本，您仍可設定流量分配 (將 100% 的流量重新導向該版本)。

  • 最新修訂版本：所有流量都會導向最新修訂版本。建立新的代理程式修訂版本後，系統會自動將流量導向該版本。

控制台

如要設定流量管理，請按照下列步驟操作：

  1. 依序前往「控管」>「部署作業」。

    前往「Deployments」(部署作業)

  2. 按一下代理程式的名稱。

  3. 前往「修訂版本」分頁。

  4. 在修訂版本詳細資料頁面中，按一下「管理流量」。

  5. 在「分割模式」下方，選取下列任一選項：

    1. 手動：指定要分配給各個修訂版本的流量百分比。
    2. 一律為最新版本：在這種情況下，100% 的流量都會導向最新 (最近建立) 的修訂版本。

  6. 選取「儲存」即可儲存變更。

Agent Platform SDK

下列程式碼範例顯示如何設定以百分比為準的流量分配。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "traffic_config": {
            "trafficSplitManual": {
                "targets": [
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
                        "percent": 50,
                    },
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
                        "percent": 50,
                    },
                ]
            }
        }
    },
)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID_1：第一個修訂版本的修訂版本 ID
  • REVISION_ID_2：第二個修訂版本的 ID

REST

如要設定流量一律導向最新修訂版本 (預設)，請使用 traffic_config 欄位更新 ReasoningEngine 資源，並指定 trafficSplitAlwaysLatest：

{
  "trafficConfig": {
    "trafficSplitAlwaysLatest": {}
  }
}

如要在代理程式的執行階段修訂版本之間分配流量，請使用 traffic_config 欄位更新 ReasoningEngine 資源，並提供流量目標清單和各自的百分比。以下說明如何跨兩個修訂版本設定手動分割。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID_1：第一個修訂版本的修訂版本 ID
  • REVISION_ID_2：第二個修訂版本的 ID
  • TRAFFIC_PERCENTAGE_1：第一個修訂版本所需的流量百分比
  • TRAFFIC_PERCENTAGE_2：您希望第二個修訂版本獲得的流量百分比

HTTP 方法和網址：

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config

JSON 要求主體：

{
  "trafficConfig": {
    "trafficSplitManual": {
      "targets": [
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
            "percent": TRAFFIC_PERCENTAGE_1
          },
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
            "percent": TRAFFIC_PERCENTAGE_2
          }
        ]
      }
    }
}

請展開以下其中一個選項，以傳送要求：

這項要求會啟動長時間執行的作業 (LRO)。一開始你會收到標準作業回應。設定變更完成後，回應會顯示 done 並重複您的設定。 
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

查詢特定修訂版本

您可以透過 SDK 或 API 查詢特定修訂版本。修訂版本必須處於有效狀態，才能查詢。將查詢直接導向特定修訂版本，即可略過流量分配規則。

Agent Platform SDK

下列程式碼會查詢特定有效修訂版本：

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

response = revision.query(
    input={"your_input_key": "your_input_value"},
    config={"class_method": "your_class_method"},
)

print(response)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

REST

呼叫 reasoningEngineRuntimeRevisions.query 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query

請展開以下其中一個選項，以傳送要求：

 

監控修訂版本

在記錄中追蹤修訂版本號碼 (做為中繼資料)，監控活動和問題的修訂版本。如要瞭解如何設定記錄，請參閱「設定記錄」。

更新修訂版本

按照「更新已部署的代理程式」一文中的操作說明，更新已部署的代理程式。您可以更新已版本化或未版本化的欄位。如果更新版本化欄位，系統會建立新的修訂版本。

刪除代理程式修訂版本

如要移除代理程式修訂版本，請將其刪除。您只能刪除未啟用流量管理的修訂版本，因為這些版本已遭淘汰，或未設定為接收流量。如要瞭解如何設定修訂版本是否接收流量，請參閱「設定修訂版本之間的流量分配」一文。

控制台

如要刪除代理程式的修訂版本：

  1. 依序前往「控管」>「部署作業」。

    前往「Deployments」(部署作業)

  2. 按一下代理程式的名稱。

  3. 前往「修訂版本」分頁。

  4. 在修訂版本詳細資料頁面中，按一下「修訂版本名稱」。

  5. 找出要移除的修訂版本所在的列。

  6. 按一下「刪除」(垃圾桶) 圖示。

  7. 系統提示時，請確認要刪除修訂版本。

Agent Platform SDK

以下程式碼會刪除指定的代理程式修訂版本：

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.runtimes.revisions.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

請替換程式碼中的下列變數：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

REST

呼叫 reasoningEngineRuntimeRevisions.delete 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud 專案 ID
  • LOCATION：支援的區域
  • RESOURCE_ID：已部署代理程式的資源 ID
  • REVISION_ID：特定執行階段修訂版本的專屬 ID

HTTP 方法和網址：

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

請展開以下其中一個選項，以傳送要求：

 

限制

  • Agent Gateway 不支援使用修訂版本的 Agent Runtime 代理程式。如果 Agent Gateway 附加至代理程式的設定，您就無法使用版本管理相關功能，例如流量分割設定和依修訂版本查詢。