管理修訂版本和流量

在 Gemini Enterprise Agent Platform,您可以建立代理的不可變版本,也就是修訂版本。接著,您可以在不同的有效修訂版本之間分配流量。您可以透過流量拆分功能,測試並逐步增加新修訂版本的流量,以及基於其他目的拆分修訂版本之間的流量。

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

如果您尚未建立任何修訂版本,則必須先建立修訂版本,才能查看修訂版本並設定修訂版本之間的流量,如本頁所述。

目前,您可以透過 v1beta1 API 使用修訂版本和流量拆分功能。

本頁面說明如何管理代理修訂版本和流量拆分。

修訂版本和狀態

修訂版本是代理的快照。建立代理或更新其版本欄位時,系統會建立代理的不可變動修訂版本。如果修訂版本可供查詢,則為「Active」。請注意,視流量設定而定,該版本可能不會收到任何查詢。修訂版本一經封存,就會永久停止處理流量,且無法還原。封存的修訂版本僅供參考。

您可以透過資源名稱識別修訂版本,只要列出代理修訂版本,即可找到資源名稱。

修訂版本限制

封存的修訂版本不會再占用修訂版本運算單元。變更 Agent Gateway 繫結會封存所有現有修訂版本 (請參閱「Agent Gateway 和修訂版本」),因此變更繫結會釋出配額,而非消耗配額。封存的修訂版本仍可刪除。

有版本和無版本的欄位

本節列出已部署代理的 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. 在 Agent Platform,依序前往「Govern」>「Deployments」。

    前往「Deployments」(部署作業) 頁面

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

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

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

    1. 分割模式:可設為「手動」或「最新」。詳情請參閱「管理修訂版本的流量」。
    2. 有效修訂版本:有效修訂版本數量與修訂版本總數的比較。
    3. 最新修訂版本:最新修訂版本的名稱,以及該版本接收的流量百分比。
    4. 主要修訂版本:主要修訂版本的名稱,會接收大部分流量。
  5. 清單會顯示代理的所有修訂版本,並包含下列資訊:

    1. 名稱:修訂版本名稱或編號。
    2. State:修訂版本的狀態。
    3. 流量:轉送至修訂版本的流量百分比。
    4. 建立時間:建立修訂版本的日期和時間。

Agent Platform SDK

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revisions = client.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"
      }...
    ]
}

取得修訂版本的詳細資料

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

控制台

  1. 依序前往「Govern」>「Deployments」。

    前往「Deployments」(部署作業) 頁面

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

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

  4. 在修訂版本詳細資料頁面,按一下「Revision name」(修訂版本名稱)。

  5. 這個畫面會顯示修訂版本的相關資訊,包括建立時間和狀態。

Agent Platform SDK

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.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% 重新導向至該版本)。
  • 最新修訂版本:所有流量都會導向最新修訂版本。建立新的代理程式修訂版本後,流量會自動導向該版本。

手動分配只能指定「有效」修訂版本。命名封存的修訂版本會傳回 FAILED_PRECONDITION:

Traffic target revision {revision} is not an active revision of this Agent Engine. Update traffic_config to reference only active revisions.

控制台

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

  1. 依序前往「Govern」>「Deployments」。

    前往「Deployments」(部署作業) 頁面

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

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

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

  5. 在「分割模式」下方,選取下列其中一個選項:

    1. 手動:指定要分配給各修訂版本的流量百分比。
    2. 一律為最新版本:在這種情況下,100% 的流量會導向最新 (最近建立) 的修訂版本。
  6. 選取「儲存」即可儲存變更。

Agent Platform SDK

下列程式碼範例說明如何設定流量分配百分比。

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.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 agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.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

請展開以下其中一個選項,以傳送要求:

 

Agent Gateway 和修訂版本

在代理上附加、變更或卸載 Agent Gateway 繫結,會建立新的修訂版本,並封存變更前存在的所有修訂版本。只有新修訂版本會保持啟用狀態。這項操作無法復原,封存的版本也無法還原。

由於繫結變更會封存所有現有修訂版本,因此只有在所有流量都已位於最新修訂版本時,才允許進行繫結變更。如果設定了任何手動拆分,即使剛好將 100% 的流量分配給最新修訂版本,API 也會拒絕變更。拒絕會傳回 FAILED_PRECONDITION:

Changing spec.deployment_spec.agent_gateway_config archives every existing runtime revision, so it is only allowed while all traffic is on the latest revision. Set traffic_config.traffic_split_always_latest, or clear traffic_config, before changing the Agent Gateway configuration.

如要變更使用手動流量拆分的代理閘道,請按照下列步驟操作:

  1. 設定 traffic_config.traffic_split_always_latest (或清除 traffic_config),切換至一律使用最新版本的轉送方式。請參閱「設定修訂版本之間的流量分配」。
  2. 變更 spec.deployment_spec.agent_gateway_config。系統會建立新修訂版本,並封存所有先前的修訂版本。
  3. 如需再次手動分割,請根據變更繫結後建立的版本進行。

您仍可透過 API 存取封存的修訂版本,且系統會保留完整的 ReasoningEngineSpec。如要建立與封存版本相同的新修訂版本,請取得封存版本的詳細資料,並部署具有相同版本欄位的新修訂版本。重複使用相同的容器映像檔 URI 會重現相同的執行階段;重複使用相同的原始碼位置和類別方法會重現相同的行為。

監控修訂版本

在記錄中將修訂版本編號追蹤為中繼資料,藉此監控修訂版本的活動和問題。如要瞭解如何設定記錄功能,請參閱「設定記錄功能」。

建立新的代理程式修訂版本

如要建立新的修訂版本,請更新已部署代理的版本欄位。如需操作說明,請參閱「更新已部署的代理」。

如果您更新版本欄位,系統會自動建立新修訂版本。如果更新無版本欄位,代理程式的所有現有修訂版本都會更新,不會建立新版本。

管理修訂版本清理作業

Gemini Enterprise Agent Platform 會自動移除舊版本,確保不超過版本數量上限。您也可以手動刪除修訂版本。

自動垃圾收集

根據預設,Gemini Enterprise Agent Platform 會為所有代理啟用自動垃圾收集功能。無法停用。垃圾收集只會在代理程式更新作業中執行,不會做為背景工作執行。

  • 執行時機:如果更新作業嘗試超過設定的版本限制,Gemini Enterprise Agent Platform 會在建立新版本之前,刪除同一作業中符合條件的最舊版本。如果調降上限,Gemini Enterprise Agent Platform 會立即刪除足夠數量的最舊修訂版本,以符合新上限。
  • 符合資格的版本:版本必須符合下列所有條件,才能刪除:
    • 處於 ACTIVE 狀態。
    • 不包含在流量設定中 (接收 0% 流量)。
  • 失敗:如果符合條件的修訂版本數量不足,無法釋出空間,Gemini Enterprise Agent Platform 會拒絕更新作業,並顯示 FAILED_PRECONDITION 錯誤。不會刪除任何修訂版本,也不會建立新的修訂版本。請先從流量設定中移除修訂版本,或提高限制,再重試。

設定限制

這項限制是由代理的 revision_garbage_collection_strategy.keep_n_latest.max_revisions 欄位定義。您可以在建立代理時設定這個欄位,或日後透過更新要求變更。

  • 新代理的預設值:100 個修訂版本。
  • 現有代理的預設值:950 個修訂版本。
  • 允許範圍:1 至 950。系統會拒絕 0 或更低的值。大於 950 的值會遭到拒絕,因為 950 是硬性配額,無法提高。

手動刪除

您可以手動刪除代理修訂版本。您只能刪除未用於流量管理的修訂版本,因為這些版本未設定為接收流量。如要瞭解如何設定修訂版本是否接收流量,請參閱「設定修訂版本之間的流量分配」。

控制台

如要刪除代理的修訂版本,請按照下列步驟操作:

  1. 依序前往「Govern」>「Deployments」。

    前往「Deployments」(部署作業) 頁面

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

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

  4. 在修訂版本詳細資料頁面,按一下「Revision name」(修訂版本名稱)。

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

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

  7. 在系統提示時,確認刪除修訂版本。

Agent Platform SDK

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.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

請展開以下其中一個選項,以傳送要求: