本文档介绍了如何解决在将代理部署到 Agent Runtime 时可能遇到的错误。其中涵盖了各种常见问题，包括序列化失败、权限错误和 VPC-SC 边界违规。
注意：如需搜索和过滤代理错误日志，请使用 Logs Explorer，将 RESOURCE TYPE 选择为“Vertex AI Reasoning Engine”，然后选择相应的 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.) 到 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 速率限制或并发请求配额。
推荐的解决方案：
- 在部署脚本中实现指数退避算法和重试策略。
- 在“Agent Platform API”的 Google Cloud “配额”页面中，将当前使用量与限值进行比较。
- 降低并发部署的频率。
相应地区暂时已达容量上限
问题：
部署失败，并显示 429、RESOURCE_EXHAUSTED 状态以及一条消息，指出相应区域的内存或 CPU 总允许量暂时已达到上限。
可能的原因：
区域中的代理部署会使用 Agent Runtime 代表您管理的并由该区域中的所有客户共享的提供容量池。当池耗尽时，该区域中的新部署会失败，直到容量释放为止。
此限制不是项目的配额之一。它不会显示在Google Cloud “配额”页面上，也无法通过申请增加配额来提高。
推荐的解决方案：
- 部署到其他受支持的区域。这是解除部署阻塞的最快方式。
- 用户可以稍后重试。区域容量已满是一个暂时性问题，通常会自动解决。
- 为代理请求较少的内存或 CPU。较小的部署可能适合剩余容量。
- 如果某个区域中的部署一直以这种方式失败，请与支持团队联系。虽然我们无法提高此限额，但您的报告有助于我们根据需求分配容量。
不适用的解决方案：
- 删除现有代理不会释放此限制的容量，因为容量并非仅由您的项目使用。
- 申请增加配额无效，因为此限制不是项目配额。
支持资源
如果问题仍未解决，请参阅我们的支持指南以获取帮助。