排查代理部署问题

本文档介绍了如何解决在将代理部署到 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

推荐的解决方案：

通过在部署代理时指定 requirements=，在两个环境（例如本地开发环境和远程部署的代理）中部署相同版本的 cloudpickle。

内部服务器错误

问题：

您收到类似于以下内容的错误消息：

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

可能的原因：

如果在部署代理时，sys_version= 与开发环境不同，则可能会发生这种情况。

推荐的解决方案：

部署代理后，请考虑从输入参数中移除 sys_version=。如果您仍然遇到问题，请提交 bug 报告。

Cloud Storage 存储桶错误

如果在部署时用于收集和上传代理的 Cloud Storage 暂存存储桶出现问题，则可能存在以下问题之一：

权限错误

推荐的解决方案：

如果您想使用预先存在的存储桶，请确保为使用 Agent Platform 而进行身份验证的主账号（您自己或某个服务账号）对此存储桶具有 Storage Admin 访问权限，并向服务账号授予权限。

或者，您可以在部署代理时指定新存储桶，SDK 将创建具有必要权限的存储桶。

如果您仍然遇到问题，请提交 bug 报告。

Cloud Storage 存储桶子目录未创建

问题：

您收到类似于以下内容的错误消息：

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

在终端中运行以下命令，以验证您是否在使用 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 边界中缺少必需的入站流量规则。

推荐的解决方案：

如果您在 VPC-SC 环境中使用 Agent Platform，则必须在边界中创建入站流量规则，以允许从 Reasoning Engine Service Agent (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 组织政策，您也可能会遇到此错误。

如需查看此场景所需配置的完整列表，请参阅跨项目自定义服务账号。

推荐的解决方案：

确保您在使用预期的服务账号。检查您是否拥有此服务账号的 Service Account User (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 Service Agent 不拥有自定义服务账号的 iam.serviceAccounts.getAccessToken 权限，则可能会发生这种情况。

如需查看此场景所需配置的完整列表，请参阅跨项目自定义服务账号。

推荐的解决方案：

请让管理员向代理项目的 AI Platform Reasoning Engine Service Agent 授予自定义服务账号的 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色。

AI Platform Reasoning Engine Service Agent 应位于您用于部署代理的同一项目中。角色授予的 IAM 绑定应位于自定义服务账号所在的项目中。

资源耗尽或速率限制错误（错误 429）

问题：

部署失败，状态为 Error 429 或 RESOURCE_EXHAUSTED。

可能的原因：

项目已超出其 API 速率限制或并发请求配额。

推荐的解决方案：

• 在部署脚本中实现指数退避算法和重试策略。
• 在 Cloud de Confiance “Agent Platform API”的“配额”页面中，对照限额验证当前用量。
• 降低并发部署的频率。

区域暂时已达容量上限

问题：

部署失败，状态为 429、RESOURCE_EXHAUSTED，并显示一条消息，指出该区域的内存或 CPU 总允许量暂时已满。

可能的原因：

一个区域中的智能体部署会利用 Agent Runtime 代您管理的服务容量池，该容量池由该区域中的所有客户共享。当池耗尽时，该区域中的新部署会失败，直到容量释放。

此限制不属于项目的配额。它不会显示在Cloud de Confiance “配额”页面上，也无法通过申请增加配额来提高。

推荐的解决方案：

• 部署到其他受支持的区域。这是解除部署屏蔽的最快方法。
• 用户可以稍后重试。区域容量不足是一个临时问题，通常会自行解决。
• 为智能体请求更少的内存或 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 中指定的 Secret ID 或版本 ID 在 Secret Manager 中不存在（与所部署智能体位于同一项目中），或者包含拼写错误。
• DESTROYED 或 DISABLED：Secret Manager 中引用的 Secret 版本处于销毁或停用状态。
• PERMISSION_DENIED：代理使用的服务账号对引用的 Secret 没有 Secret Manager Secret Accessor 角色 (roles/secretmanager.secretAccessor)。

推荐的解决方案：

• 对于 NOT_FOUND、DESTROYED 或 DISABLED：
  1. 在您要部署代理的项目的 Secret Manager 页面中，验证 secret_env 中引用的每个 SECRET_ID 和 VERSION_ID 是否存在且处于已启用状态。
  2. 如果引用的版本已停用或销毁，请启用有效版本或更新 secret_env 以引用已启用的版本。
• 对于 PERMISSION_DENIED：向提取 Secret 的服务账号授予 Secret（或包含 Secret 的项目）的 Secret Manager Secret Accessor 角色 (roles/secretmanager.secretAccessor)：
  • 默认服务账号：向 AI Platform Reasoning Engine Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com) 授予该角色。
  • 自定义服务账号：将角色授予在代理上配置的自定义服务账号。

容器映像构建超时

问题：

部署失败，状态为 504、DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT)，并显示一条消息，指出智能体的容器映像未及时完成构建。

可能的原因：

当您从源文件部署时，Agent Runtime 会构建一个容器映像，用于安装您的代码及其依赖项。如果构建在允许的时间用尽时仍在运行，则部署会失败。由于安装的依赖项，构建通常需要很长时间，例如：

• requirements 中包含一长串软件包，其中包括代理不使用的软件包。
• 没有针对构建环境的预构建轮子的软件包，这些软件包在构建期间从源代码编译。
• 未固定或松散固定的版本，这会减慢依赖项解析速度。

推荐的解决方案：

• 查看错误元数据的 logs_url 字段中关联的构建日志，了解构建停止时正在运行哪个步骤。
• 移除不必要的依赖项，并固定所有必需软件包的版本。
• 优先考虑发布预构建 wheel 的软件包和版本，以便在构建期间不编译任何内容。
• 重试部署。由于与代码无关的原因，构建运行时间有时可能会比平时长。

容器未及时启动

问题：

部署失败，状态为 504、DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT)，并显示一条消息，指出代理的容器未及时开始传送。

可能的原因：

构建映像后，Agent Runtime 会启动智能体的容器，并等待其准备好处理请求。如果容器在允许的时间用尽时仍在启动，则部署会失败。常见原因可能包括：

• 导入时工作缓慢，例如在导入代理模块时加载大型模型或文件。
• 代理的 set_up() 方法中存在缓慢或阻塞的工作，例如等待无法访问的服务响应的网络调用。

推荐的解决方案：

• 检查错误元数据的 logs_url 字段中关联的容器日志，查看启动停滞的位置。
• 将耗时的初始化操作移出模块导入时间，并尽可能减少 set_up() fast 中的步骤数。推迟处理第一个请求不需要的工作。
• 确保代理在启动期间调用的任何服务都可以从代理访问，并对这些调用设置超时，以便它们不会无限期地阻止启动。
• 如果容器日志显示代理正常启动，请重试部署。由于与代码无关的原因，启动有时可能需要比平时更长的时间。

支持资源

如果问题仍未解决，请参阅我们的支持指南以获取帮助。