本文档介绍了如何解决在部署代理时可能遇到的错误。
预构建模板错误
如果您在部署期间遇到 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推荐的解决方案：
通过在部署代理时指定 requirements=，在两个环境（例如本地开发环境和远程部署的代理）中部署相同版本的 cloudpickle。
内部服务器错误
问题：
您收到类似于以下内容的错误消息：
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 错误。）
可能的原因：
这可能是由于低于 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 环境中使用 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 绑定应位于自定义服务账号所在的项目中。
支持资源
如果问题仍未解决，请参阅我们的支持指南以获取帮助。