排解代理程式部署問題

本文說明如何解決將代理程式部署至 Agent Runtime 時可能發生的錯誤。內容涵蓋各種常見問題，包括序列化失敗、權限錯誤和 VPC-SC 邊界違規。

注意：如要搜尋及篩選代理程式錯誤記錄，請使用記錄檔探索器，選取「Vertex AI Reasoning Engine」的 RESOURCE TYPE，然後選取對應的 RESOURCE CONTAINER 值 (即專案編號) 和 REASONING ENGINE ID 值。

預先建構的範本錯誤

如果在部署期間遇到 LangchainAgent 範本問題，可能是因為本節中的其中一個問題。

內部伺服器錯誤

問題：

您會收到類似下列內容的錯誤訊息：

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

很抱歉，這是容器在執行階段發生任何問題時的通用錯誤，可能原因包括許多錯誤。

可能原因：

• LangchainAgent 的髒狀態。如果在部署代理程式之前，對 LangchainAgent 呼叫 .set_up()，就可能發生這種情況。
• 套件版本不一致。如果開發環境中安裝的套件，與 Agent Runtime 遠端環境中安裝的套件不同，就可能發生這種情況。

建議解決方案：

• LangchainAgent 的髒狀態。在部署代理程式前，請建立 LangchainAgent 的新例項，或從程式碼中移除 agent.set_up()。
• 套件規格不一致。請參閱「排解序列化錯誤」一節。

序列化錯誤

一般而言，部署代理程式時，請務必確保「本機」和「遠端」環境同步。如要確保這一點，請在部署服務專員時指定 requirements=。

如果遇到序列化問題 (與「pickle」或「pickling」相關的錯誤等同於「序列化」錯誤)，可能是因為本節所述的其中一個問題。

Pydantic 版本

問題：

您會收到類似下列內容的錯誤訊息：

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

可能原因：

如果您的 pydantic 套件版本早於 2.6.4，就可能發生這種情況。如要查看目前使用的版本，請在終端機中執行下列指令：

pip show pydantic

建議解決方案：

在終端機中執行下列指令，更新套件：

pip install pydantic --upgrade

在終端機中執行下列指令，確認您使用的是 2.6.4 以上版本：

pip show pydantic

如果您位於筆記本執行個體 (例如 Jupyter、Colab 或 Workbench)，可能需要重新啟動執行階段，才能使用更新後的套件。

Cloudpickle 版本

問題：

您會收到類似下列內容的錯誤訊息：

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

可能原因：

如果開發環境和部署環境中的 cloudpickle 套件版本不同，就可能發生這種情況。如要查看開發環境中使用的版本，請在終端機中執行下列指令：

pip show cloudpickle

建議解決方案：

在兩個環境中部署相同版本的 cloudpickle，例如本機開發環境和遠端部署的代理程式，方法是在部署代理程式時指定 requirements=。

內部伺服器錯誤

問題：

您會收到類似下列內容的錯誤訊息：

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

可能原因：

如果sys_version=與部署代理程式時的開發環境不同，就可能發生這種情況。

建議解決方案：

部署代理程式後，請考慮從輸入引數中移除 sys_version=。如果仍遇到問題，請提出錯誤報告。

Cloud Storage bucket 錯誤

如果您在部署時遇到 Cloud Storage 暫存 bucket 的問題，導致無法收集及上傳代理程式，可能是因為下列其中一個問題：

權限錯誤

建議解決方案：

如要使用現有值區，請確認已通過驗證，可使用 Agent Platform 的主體 (您本人或服務帳戶) 具有值區的 Storage Admin 存取權，並將權限授予服務帳戶。

或者，您可以在部署代理程式時指定新的 bucket，SDK 會建立具有必要權限的 bucket。

如果仍遇到問題，請提出錯誤報告。

未建立 Cloud Storage bucket 子目錄

問題：

您會收到類似下列內容的錯誤訊息：

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

(如果系統嘗試複製到不存在的資料夾，就會發生 404 錯誤)。

可能原因：

這可能是因為 1.49.0 之前的 google-cloud-aiplatform 版本發生字串內插問題。這個問題已在後續版本中修正。如要查看目前使用的 google-cloud-aiplatform 版本，請在終端機中執行下列指令：

pip show google-cloud-aiplatform

建議解決方案：

在終端機中執行下列指令，更新套件：

pip install google-cloud-aiplatform --upgrade

在終端機中執行下列指令，確認您使用的是 1.49.0 以上版本的 google-cloud-aiplatform：

pip show google-cloud-aiplatform

如果您使用筆記本執行個體 (例如 Jupyter、Colab 或 Workbench)，可能需要重新啟動執行階段，才能使用更新後的套件。

VPC-SC 違規錯誤

如果 VPC-SC 發生問題，可能的原因如下：

權限錯誤

問題：

您會收到類似下列內容的錯誤訊息：

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

或：

Request is prohibited by organization's policy.

可能原因：

這可能是因為 VPC-SC 範圍缺少必要的輸入規則所致。

建議解決方案：

如果您在 VPC-SC 環境中使用 Agent Platform，請務必在 perimeter 中建立輸入規則，允許從 Reasoning Engine Service Agent ([e-mail]) 輸入至 storage.googleapis.com 服務和 artifactregistry.googleapis.com 服務。

自訂服務帳戶錯誤

如果服務帳戶發生問題，可能的原因如下：

以服務帳戶身分執行動作

問題：

您會收到類似下列內容的錯誤訊息：

You do not have permission to act as service_account.

可能原因：

您可能沒有部署自訂服務帳戶的 iam.serviceAccounts.actAs 權限。請注意，在多代理程式系統中，如果有多個自訂服務帳戶，代理程式作者或部署者可以擔任部分服務帳戶。如果您使用錯誤的服務帳戶，這是預期行為

此外，如果自訂服務帳戶所在的專案與部署代理程式的專案不同，且服務帳戶專案iam.disableCrossProjectServiceAccountUsage強制執行組織政策，您也可能會遇到這項錯誤。

如需這個情境的完整必要設定清單，請參閱「跨專案自訂服務帳戶」。

建議解決方案：

請確認您使用的是預期服務帳戶。確認您是否擁有這個服務帳戶的「服務帳戶使用者」 (roles/iam.serviceAccountUser) 角色。如果沒有，請要求管理員授予您這個服務帳戶的角色。

如果是跨專案情境，請檢查服務帳戶專案是否已強制執行 iam.disableCrossProjectServiceAccountUsage 組織政策。如果是，請要求管理員停用這項政策。

中繼資料伺服器無法使用

問題：

您會收到類似下列內容的錯誤訊息：

ServiceUnavailable: 503 Getting metadata from plugin failed with error

或

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

可能原因：

如果自訂服務帳戶和代理程式位於不同專案，且 AI Platform Reasoning Engine 服務代理程式沒有自訂服務帳戶的 iam.serviceAccounts.getAccessToken 權限，就可能發生這種情況。

如需這個情境的完整必要設定清單，請參閱「跨專案自訂服務帳戶」。

建議解決方案：

請管理員授予代理專案的 AI Platform Reasoning Engine 服務代理，自訂服務帳戶的「服務帳戶權杖建立者」(roles/iam.serviceAccountTokenCreator) 角色。

AI Platform Reasoning Engine 服務代理程式應位於您用來部署代理程式的專案中。角色授權的 IAM 繫結應位於自訂服務帳戶所在的專案中。

資源用盡或超出速率限制錯誤 (錯誤 429)

問題：

部署作業失敗，狀態為 Error 429 或 RESOURCE_EXHAUSTED。

可能原因：

專案已超過 API 頻率限制或並行要求配額。

建議解決方案：

• 在部署指令碼中導入指數輪詢和重試策略。
• 在「Agent Platform API」的「配額」 Google Cloud 頁面中，根據限制驗證目前的使用量。
• 減少並行部署的頻率。

注意： 這些解決方案適用於專案本身的 API 頻率限制。如果區域暫時達到容量上限，或部署的 max_instances 超過其 resource_limits 的區域限制，則會傳回相同的 429、RESOURCE_EXHAUSTED 狀態，但原因和解決方法不同。請參閱「區域暫時達到容量上限」和「執行個體數量上限超出區域限制」。

區域暫時無法處理要求

問題：

部署作業失敗，狀態為 429 或 RESOURCE_EXHAUSTED，並顯示訊息，指出區域的記憶體或 CPU 總允許量暫時已達上限。

可能原因：

區域中的代理部署作業會使用服務容量集區，而 Agent Runtime 會代表您管理該集區，並由該區域中的所有客戶共用。集區用盡後，該區域的新部署作業就會失敗，直到容量釋出為止。

這項限制並非專案配額。這項限制不會顯示在「配額」Google Cloud 頁面，且無法透過要求提高配額來增加。

建議解決方案：

• 部署至其他支援的地區。這是解除部署封鎖最快的方法。
• 請稍後再試一次。區域容量不足是暫時性問題，通常會自行解決。
• 為代理程式要求較少的記憶體或 CPU。較小的部署作業可能適合剩餘容量。
• 如果區域中的部署作業持續發生這類失敗情形，請與支援團隊聯絡。雖然我們無法提高上限，但你的回報有助於我們將容量分配到需要的地方。

不適用的解決方案：

• 刪除現有代理程式不會釋出此限制的容量，因為容量並非僅供專案使用。
• 由於這項限制並非專案配額，因此申請提高配額不會有任何效果。

執行個體數量上限超過區域限制

問題：

部署作業失敗，狀態為 429 或 RESOURCE_EXHAUSTED，並顯示訊息指出 spec.deployment_spec.max_instances 超過區域 resource_limits 中所要求 CPU 或記憶體支援的執行個體數量上限。

可能原因：

部署代理程式時，Agent Runtime 會將每個執行個體的 cpu 和 memory 乘以 spec.deployment_spec.max_instances，並檢查這個單一代理程式的尖峰分配量是否符合基礎服務專案的區域限制。spec.deployment_spec.resource_limits如果未指定 max_instances，Agent Runtime 會套用預設值 (例如 200)，這在限制較低的區域中，乘以設定的每個執行個體 cpu 或 memory 時，可能會超過支援的執行個體數量上限。

建議解決方案：

• 將 spec.deployment_spec.max_instances 設為錯誤訊息中顯示的最大值 (或更低)。
• 在 spec.deployment_spec.resource_limits 中降低每個執行個體的 cpu 或 memory 值。
• 將代理程式部署到支援的地區，並提高限制。

不適用的解決方案：

• 在專案的 Google Cloud 配額頁面 要求提高配額，不會有任何效果，因為這項限制是在 Google 管理的服務專案中強制執行，而不是在您的專案中。
• 刪除專案中的其他代理程式，或在不變更 max_instances 或 resource_limits 的情況下重試，都無法解決這個錯誤，因為檢查會根據靜態限制評估單一部署作業的尖峰分配量。

Secret Manager 存取錯誤

問題：

部署作業失敗，並顯示 400、INVALID_ARGUMENT 狀態 (REASONING_ENGINE_SECRET_ACCESS_DENIED) 和類似下列內容的訊息：

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

可能原因：

• NOT_FOUND：secret_env 中指定的密鑰 ID 或版本 ID 不存在於 Secret Manager 中，且與已部署的代理程式位於相同專案，或含有錯字。
• DESTROYED 或 DISABLED：Secret Manager 中參照的密鑰版本處於已毀損或停用狀態。
• PERMISSION_DENIED：代理程式使用的服務帳戶，在參照的密鑰上沒有 Secret Manager 密鑰存取者角色 (roles/secretmanager.secretAccessor)。

建議解決方案：

• 針對 NOT_FOUND、DESTROYED 或 DISABLED：
  1. 在部署代理程式的專案中，前往 Secret Manager 頁面，確認 secret_env 中參照的每個 SECRET_ID 和 VERSION_ID 都存在，且處於「已啟用」狀態。
  2. 如果參照的版本已停用或毀損，請啟用有效版本，或更新 secret_env 以參照已啟用的版本。
• 適用於 PERMISSION_DENIED： 將「Secret Manager 密鑰存取者」角色 (roles/secretmanager.secretAccessor) 授予擷取密鑰的服務帳戶，該密鑰或包含該密鑰的專案：
  • 預設服務帳戶：將角色授予 AI Platform Reasoning Engine 服務代理 ([e-mail])。
  • 自訂服務帳戶：將角色授予代理程式上設定的自訂服務帳戶。

支援資源

如果問題仍未解決，請參閱支援指南尋求協助。