本文档介绍了如何解决在部署代理时可能遇到的错误。
预构建模板错误
如果您在部署期间遇到 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 绑定应位于自定义服务账号所在的项目中。
支持资源
如果问题仍未解决,请参阅我们的支持指南以获取帮助。