排查联机终结点的部署和评分问题(预览版)

适用于:Azure CLI ml 扩展 v1 v2(预览版)

了解如何解决 Azure 机器学习联机终结点(预览版)的常见部署和评分问题。

本文档采用一种可方便你着手进行故障排除的结构:

  1. 在云中部署之前,请使用本地部署在本地测试和调试模型。
  2. 使用容器日志帮助调试问题。
  3. 了解可能会出现的常见部署错误及其解决方法。

HTTP 状态代码部分解释了在使用 REST 请求为终结点评分时,调用和预测错误如何映射到 HTTP 状态代码。

重要

此功能目前处于公开预览状态。 此预览版在提供时没有附带服务级别协议,不建议将其用于生产工作负荷。 某些功能可能不受支持或者受限。 有关详细信息,请参阅适用于 Azure 预览版的补充使用条款

先决条件

本地部署

本地部署会将模型部署到本地 Docker 环境。 本地部署可用于在部署到云之前进行测试和调试。

提示

使用 Visual Studio Code 在本地测试和调试终结点。 有关详细信息,请参阅在 Visual Studio Code 中以本地方式调试联机终结点

本地部署支持创建、更新和删除本地终结点。 它还允许从终结点调用和获取日志。 若要使用本地部署,请将 --local 添加到相应的 CLI 命令:

az ml online-deployment create --endpoint-name <endpoint-name> -n <deployment-name> -f <spec_file.yaml> --local

在本地部署过程中,将执行以下步骤:

  • Docker 生成新的容器映像,或者从本地 Docker 缓存拉取现有映像。 如果某个现有映像与规范文件的环境部分相匹配,将使用该映像。
  • Docker 启动装载了本地项目(如模型和代码文件)的新容器。

有关详细信息,请参阅使用托管联机终结点(预览版)在本地部署机器学习模型并为其评分

Conda 安装

通常,mlflow 部署问题源于 conda.yaml 文件中指定的用户环境的安装问题。

若要调试 conda 安装问题,请尝试以下操作:

  1. 检查 conda 安装的日志。 如果容器崩溃或启动时间过长,则可能是 conda 环境更新无法正确解析。

  2. 使用命令 conda env create -n userenv -f <CONDA_ENV_FILENAME> 在本地安装 mlflow conda 文件。

  3. 如果本地存在错误,请尝试解析 conda 环境并创建一个功能性环境,然后再重新部署。

  4. 如果即使在本地解析,容器也会崩溃,则用于部署的 SKU 大小可能太小。

    1. Conda 包安装在运行时进行,因此如果 SKU 太小而无法容纳 conda.yaml 环境文件中详述的所有包,则容器可能会崩溃。
    2. Standard_F4s_v2 VM 是一个很好的启动 SKU 大小,但可能需要更大的 SKU,具体取决于 conda 文件中指定的依赖项。

获取容器日志

无法直接访问部署了模型的 VM。 但是,可以从该 VM 上运行的某些容器获取日志。 信息量取决于部署的预配状态。 如果指定的容器已启动且正在运行,则你会看到其控制台输出,否则会收到一条请你稍后重试的消息。

若要查看容器的日志输出,请使用以下 CLI 命令:

az ml online-deployment get-logs -e <endpoint-name> -n <deployment-name> -l 100

    az ml online-deployment get-logs --endpoint-name <endpoint-name> --name <deployment-name> --lines 100

如果尚未通过 az configure 设置 --resource-group--workspace-name 参数,请将这些参数添加到上述命令。

若要查看有关如何设置这些参数的信息并确定是否已设置当前值,请运行:

az ml online-deployment get-logs -h

默认情况下,日志是从推理服务器拉取的。 日志包括来自推理服务器的控制台日志,其中包含“score.py”代码中的 print/log 语句。

注意

如果使用 Python 日志记录,请确保为要发布到日志中的消息使用正确的日志记录级别顺序。 例如 INFO。

还可以通过传递 –-container storage-initializer 从存储初始化表达式容器获取日志。 这些日志包含有关代码和模型数据是否已成功下载到容器的信息。

添加 --help 和/或 --debug 命令以查看更多信息。

请求跟踪

有三个受支持的跟踪标头:

  • x-request-id 保留用于服务器跟踪。 我们重写此标头以确保它是有效的 GUID。

    注意

    为失败的请求创建支持票证时,请附加失败的请求 ID 以加快调查。

  • x-ms-request-idx-ms-client-request-id 可用于客户端跟踪方案。 我们清理这些标头以删除非字母数字符号。 这些标头被截断为 72 个字符。

常见部署错误

下面是作为部署操作状态的一部分报告的常见部署错误列表。

错误:ImageBuildFailure

生成环境(docker 映像)时返回此错误。 可以检查生成日志,了解有关失败的更多详细信息。 生成日志位于 Azure 机器学习工作区的默认存储中。 确切位置作为错误的一部分返回。 例如,“可在路径“/azureml/ImageLogs/your-image-id/build.log”下的工作区 blob 存储“storage-account-name”中找到生成日志”。 在这种情况下,“azureml”是存储帐户中 blob 容器的名称。

如果在生成日志中没有发现明显的错误,并且最后一行是 Installing pip dependencies: ...working...,则错误可能是由依赖项引起的。 在 conda 文件中固定版本依赖项可以解决此问题。

我们还建议使用本地部署在本地测试和调试模型,然后再部署到云中。

错误:OutOfQuota

下面列出了使用 Azure 服务时可能用尽配额的常见资源:

CPU 配额

在部署模型之前,需有足够的计算配额。 此配额定义每个订阅、每个工作区、每个 SKU 和每个区域可用的虚拟核心数。 每次部署都会扣减可用配额,删除部署后,会根据 SKU 的类型重新增加配额。

一种可能的缓解措施是检查能否删除未使用的部署。 或者,可以提交配额提高请求

磁盘配额

如果模型的大小大于可用磁盘空间,并且无法下载模型,则会出现此问题。 尝试一个具有更多磁盘空间的 SKU。

内存配额

当模型的内存占用大于可用内存时,就会发生此问题。 尝试使用具有更多内存的托管联机端点 SKU 列表

角色分配配额

尝试删除此订阅中某些未使用的角色分配。 可以在 Azure 门户的“访问控制”菜单中检查所有角色分配。

终结点配额

尝试删除此订阅中某些未使用的终结点。

Kubernetes 配额

无法满足请求的 CPU 或内存。 调整你的请求或此群集。

其他配额

为了运行在部署过程中提供的 score.py,Azure 将创建一个包含 score.py 所需全部资源的容器,并在该容器上运行评分脚本。

如果容器无法启动,这意味着可能无法评分。 可能是容器请求的资源数量超过了 instance_type 可以支持的数量。 如果是这样,请考虑更新联机部署的 instance_type

若要获取确切的错误原因,请运行:

az ml online-deployment get-logs -e <endpoint-name> -n <deployment-name> -l 100

错误:OutOfCapacity

由于 Azure 机器学习容量不足,无法预配指定的 VM 大小。 请稍后重试,或尝试部署到其他区域。

错误:BadArgument

下面列出了可能遇到此错误的原因:

资源请求数大于限制

资源的请求数必须小于或等于限制。 如果你未设置限制,我们会在你将计算附加到 Azure 机器学习工作区时设置默认值。 可以通过 Azure 门户或 az ml compute show 命令来检查限制。

授权错误

预配计算资源之后,在部署创建过程中,Azure 会尝试从工作区专用 Azure 容器注册表 (ACR) 拉取用户容器映像,并将用户模型和代码项目从工作区存储帐户装载到用户容器中。

首先,检查是否存在访问 ACR 的权限问题。

为了拉取 Blob,Azure 将使用托管标识访问存储帐户。

  • 如果使用 SystemAssigned 创建了关联的终结点,则系统会自动授予 Azure 基于角色的访问控制 (RBAC) 权限,此时不需要任何进一步的权限。

  • 如果使用 UserAssigned 创建了关联的终结点,则用户的托管标识必须对工作区存储帐户拥有“存储 Blob 数据读取者”权限。

无法下载用户容器映像

可能找不到用户容器。 请检查容器日志以获取更多详细信息。

请确保该容器映像在工作区 ACR 中可用。

例如,如果映像为 testacr.azurecr.cn/azureml/azureml_92a029f831ce58d2ed011c3c42d35acb:latest,请使用 az acr repository show-tags -n testacr --repository azureml/azureml_92a029f831ce58d2ed011c3c42d35acb --orderby time_desc --output table 检查存储库。

无法下载用户模型或代码项目

可能找不到用户模型或代码项目。 请检查容器日志以获取更多详细信息。

确保将模型和代码项目注册到部署所在的同一工作区。 使用 show 命令显示工作区中模型或代码项目的详细信息。

  • 例如:

    az ml model show --name <model-name>
    az ml code show --name <code-name> --version <version>
    

    还可以检查 Blob 是否存在于工作区存储帐户中。

  • 例如,如果 Blob 为 https://foobar.blob.core.windows.net/210212154504-1517266419/WebUpload/210212154504-1517266419/GaussianNB.pkl,则可使用以下命令检查它是否存在:

    az storage blob exists --account-name foobar --container-name 210212154504-1517266419 --name WebUpload/210212154504-1517266419/GaussianNB.pkl --subscription <sub-name>

错误:ResourceNotReady

为了运行在部署过程中提供的 score.py,Azure 将创建一个包含 score.py 所需全部资源的容器,并在该容器上运行评分脚本。 在这种场景下发生的错误表现为此容器在运行时崩溃,这意味着无法评分。 出现以下情况时会发生此错误:

  • score.py 中有错误。 使用 get-logs 来帮助诊断常见问题:
    • 包已导入,但不在 conda 环境中。
    • 语法错误。
    • init() 方法失败。
  • 如果 get-logs 未生成任何日志,通常意味着容器启动失败。 若要调试此问题,请改为尝试进行本地部署
  • 未正确设置就绪状态或运行情况探测。
  • 容器的环境设置有错误,例如缺少依赖项。

错误:ResourceNotFound

当 Azure 资源管理器找不到所需资源时,将发生此错误。 例如,如果引用了存储帐户,但在指定的路径上找不到该帐户,则将收到此错误。 请务必仔细检查可能已通过精确路径或其名称拼写提供的资源。

有关详细信息,请参阅解决找不到资源的错误

错误:OperationCancelled

Azure 操作具有一定的优先级,并按从最高到最低的顺序执行。 如果你的操作被另一个优先级较高的操作替代,则会发生此错误。 重试该操作可能可以在不取消的情况下执行操作。

错误:InternalServerError

尽管我们会尽最大努力提供稳定可靠的服务,但有时事情不会按计划进行。 如果收到此错误,表示我们这一端出现了问题,我们需要予以修复。 请提交客户支持票证并随附所有相关信息,我们将解决问题。

自动缩放问题

如果在自动缩放时遇到问题,请参阅排查 Azure 自动缩放问题

带宽限制问题

托管联机终结点对于每个终结点都有带宽限制。 可以在这里的管理和增大 Azure 机器学习资源的配额中找到限制配置。 如果带宽使用量超出限制,则会延迟你的请求。 监视带宽延迟的步骤:

  • 使用“网络字节数”指标来了解当前带宽使用情况。 有关详细信息,请参阅监视托管联机终结点
  • 如果强制带宽限制,将返回两个响应尾部:
    • ms-azureml-bandwidth-request-delay-ms:请求流传输所用的延迟时间(以毫秒为单位)。
    • ms-azureml-bandwidth-response-delay-ms:响应流传输所用的延迟时间(以毫秒为单位)。

HTTP 状态代码

使用 REST 请求访问联机终结点时,返回的状态代码将遵守 HTTP 状态代码标准。 下面详述了终结点调用和预测错误如何映射到 HTTP 状态代码。

状态代码 原因短语 返回此代码的可能原因
200 确定 已在延迟范围内成功执行了模型。
401 未授权 你无权执行请求的操作(如评分),或者令牌已过期。
404 未找到 URL 不正确。
408 请求超时 模型执行所用的时间超过了在模型部署配置的 request_settings 下的 request_timeout_ms 中提供的超时。
424 模型错误 如果模型容器返回非 200 响应,则 Azure 将返回 424。 有关详细信息,请查看响应头 ms-azureml-model-error-statuscodems-azureml-model-error-reason
429 速率限制 每秒尝试向终结点发送的请求数超过 100 个。
429 挂起的请求太多 模型收到的请求数超过了它可以处理的数量。 在任意时间,我们允许 2 * max_concurrent_requests_per_instance * instance_count 个请求。 更多的请求将被拒绝。 可以在模型部署配置中的 request_settingsscale_settings 下确认这些设置。 如果使用自动缩放,则模型接收请求的速度比系统纵向扩展的速度更快。 使用自动缩放时,可以尝试通过指数退避来重新发送请求。 这样做可以让系统有时间做出调整。
500 内部服务器错误 Azure ML 预配的基础结构发生故障。

后续步骤