排解代理程式部署問題

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

注意：如要搜尋及篩選代理錯誤記錄，請使用 Logs Explorer，將 RESOURCE TYPE 設為「Vertex AI 推論引擎」，然後選取對應的 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 發生問題，導致無法在部署時收集及上傳代理程式，可能是下列原因造成：

權限錯誤

建議解決方案：

如要使用現有 bucket，請確認通過驗證、可使用 Agent Platform 的主體 (您自己或服務帳戶) 具備 bucket 的 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 錯誤)。

可能原因：

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

pip show google-cloud-aiplatform

建議解決方案：

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

pip install google-cloud-aiplatform --upgrade

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

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 perimeter 缺少必要的輸入規則。

建議解決方案：

如果您在 VPC-SC 環境中使用 Agent Platform，必須在 perimeter 建立輸入規則，允許從 推論引擎 服務代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com) 輸入至 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 平台推論引擎服務代理沒有自訂服務帳戶的 iam.serviceAccounts.getAccessToken 權限，就可能發生這種情況。

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

建議解決方案：

請管理員將自訂服務帳戶的服務帳戶權杖建立者 (roles/iam.serviceAccountTokenCreator) 角色，授予代理專案的 AI 平台推論引擎服務代理。

AI 平台推論引擎服務代理應位於您用來部署代理的專案中。角色授權的 IAM 繫結應位於自訂服務帳戶所在的專案中。

資源用盡或頻率限制錯誤 (錯誤 429)

問題：

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

可能原因：

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

建議解決方案：

• 在部署指令碼中，導入指數輪詢和重試策略。
• 請前往「Agent Platform API」的 Cloud de Confiance 「配額」頁面，確認目前用量是否超出限制。
• 降低並行部署作業的頻率。

區域暫時無法處理要求

問題：

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

可能原因：

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

這項限制不屬於專案配額。這項限制不會顯示在Cloud de Confiance 「Quotas」(配額) 頁面，也無法透過要求提高配額來提高。

建議解決方案：

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

不適用的解決方案：

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

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

問題：

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

可能原因：

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

建議解決方案：

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

不適用的解決方案：

• 在專案的「 Cloud de Confiance 配額」頁面要求提高配額不會有任何效果，因為這項限制是在 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 的 Secret Manager Secret 存取者角色 (roles/secretmanager.secretAccessor)。

建議解決方案：

• NOT_FOUND、DESTROYED 或 DISABLED：
  1. 在部署代理的專案中，前往 Secret Manager 頁面，確認 secret_env 參照的每個 SECRET_ID 和 VERSION_ID 都存在，且處於「已啟用」狀態。
  2. 如果參照的版本已停用或刪除，請啟用有效版本，或更新 secret_env 以參照已啟用的版本。
• PERMISSION_DENIED：將 Secret (或包含 Secret 的專案) 的 Secret Manager Secret 存取者角色 (roles/secretmanager.secretAccessor) 授予擷取 Secret 的服務帳戶：
  • 預設服務帳戶：將角色授予 AI 平台 Reasoning Engine 服務代理 (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com)。
  • 自訂服務帳戶：將角色授予代理上設定的自訂服務帳戶。

容器映像檔建構作業逾時

問題：

部署作業失敗，狀態為 504、DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT)，並顯示訊息，指出代理程式的容器映像檔未及時完成建構。

可能原因：

從來源檔案部署時，Agent Runtime 會建構容器映像檔，安裝程式碼和依附元件。如果建構作業在允許的時間內仍未完成，部署作業就會失敗。建構作業通常會因為安裝依附元件而耗費過多時間，例如：

• requirements 中有許多套件，包括代理程式未使用的套件。
• 建構環境沒有預先建構的 wheel，因此在建構期間會從來源編譯。
• 未固定或鬆散固定的版本，會減慢依附元件解析速度。

建議解決方案：

• 請查看錯誤中繼資料 logs_url 欄位連結的建構記錄，瞭解建構作業停止時正在執行的步驟。
• 移除不必要的依附元件，並固定所有必要套件的版本。
• 優先使用發布預建 wheel 的套件和版本，這樣建構期間就不會編譯任何內容。
• 重試部署作業。有時建構作業的執行時間會比平常長，原因與程式碼無關。

容器未及時啟動

問題：

部署作業失敗，狀態為 504、DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT)，並顯示訊息，指出代理程式的容器未及時開始提供服務。

可能原因：

建構映像檔後，Agent Runtime 會啟動代理的容器，並等待容器準備就緒，可以處理要求。如果容器在允許的時間內仍未啟動，部署作業就會失敗。常見原因包括：

• 匯入時作業緩慢，例如匯入代理模組時載入大型模型或檔案。
• 代理程式 set_up() 方法中的工作速度緩慢或遭到封鎖，例如網路呼叫等待無法連線的服務。

建議解決方案：

• 請查看錯誤中繼資料 logs_url 欄位中連結的容器記錄，瞭解啟動作業停滯的位置。
• 請將耗費資源的初始化作業移出模組匯入時間，並盡可能減少 set_up() 快速路徑中的步驟數量。延後處理第一個要求不需要的工作。
• 請確認代理程式在啟動期間呼叫的任何服務，都能從代理程式連線，並為這些呼叫設定逾時，以免無限期封鎖啟動。
• 如果容器記錄顯示代理程式正常啟動，請重試部署作業。有時啟動時間可能比平常長，原因與程式碼無關。

支援資源

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