本文档介绍了如何解决在部署代理时可能遇到的错误。
预建模板错误
如果您在部署期间遇到 LangchainAgent 模板方面的问题，可能是本部分中所述的某个问题导致的。
内部服务器错误
问题：
您收到类似于以下内容的错误消息：
InternalServerError: 500 Revision XXX is not ready and cannot serve traffic.
遗憾的是，这是容器在运行时出现任何问题的统称错误，可能的原因是可能发生的众多错误之一。
可能的原因：
LangchainAgent上的脏状态。如果在部署代理之前对LangchainAgent调用了.set_up()，则可能会发生这种情况。- 软件包版本不一致。如果开发环境中安装的软件包与 Vertex AI Agent Engine 远程环境中安装的软件包不同，则可能会出现这种情况。
推荐的解决方案：
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 XXX is not ready and cannot serve traffic.
可能的原因：
如果sys_version=与部署代理时的开发环境不同，则可能会发生这种情况。
推荐的解决方案：
部署代理后，考虑从输入实参中移除 sys_version=。
如果您仍然遇到问题，请提交 bug 报告。
Cloud Storage 存储桶错误
如果您在部署时遇到 Cloud Storage 临时存储桶方面的问题（该存储桶用于收集和上传代理），则可能是以下问题之一：
权限错误
推荐的解决方案：
如果您想使用预先存在的存储桶，请确保已通过身份验证以使用 Vertex AI 的主账号（您自己或服务账号）对此存储桶具有 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 错误。）
可能的原因：
这可能是由于 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 边界中缺少必需的入站规则。
推荐的解决方案：
如果您在 VPC-SC 环境中使用 Vertex AI Agent Engine，则必须在边界中创建入站规则，以允许从 Reasoning Engine Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.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 绑定应位于自定义服务账号所在的项目中。
支持资源
如果问题仍未解决，请参阅我们的支持指南以获取帮助。