排查批处理终结点问题

项目
09/13/2024

适用范围：Azure CLI ml 扩展 v2（最新版）Python SDK azure-ai-ml v2（最新版）

本文提供有关在 Azure 机器学习中使用批处理终结点进行批量评分时排查常见错误的指南。以下部分介绍如何分析批量评分日志，以确定可能的问题和不受支持的方案。还可以查看建议的解决方案来解决常见错误。

获取批量评分作业的日志

使用 Azure CLI 或 REST API 调用批处理终结点后，批量评分作业将以异步方式运行。有两个选项可用于获取批量评分作业的日志：

选项 1：将作业日志流式传输到本地控制台。仅流式传输 azureml-logs 文件夹中的日志。

运行以下命令将系统生成的日志流式传输到控制台。将 <job_name> 参数替换为批量评分作业的名称：
```
az ml job stream --name <job_name>
```
选项 2：在 Azure 机器学习工作室中查看作业日志。

运行以下命令，获取在工作室中使用的作业链接。将 <job_name> 参数替换为批量评分作业的名称：
```
az ml job show --name <job_name> --query services.Studio.endpoint -o tsv
```
1. 在工作室中打开作业链接。
2. 在作业图中，选择“批量评分”步骤。
3. 在“输出 + 日志”选项卡上，选择要查看的一个或多个日志。

查看日志文件

Azure 机器学习提供了多种类型的日志文件和其他数据文件，可用于帮助对批量评分作业进行故障排除。

批量评分日志的两个顶级文件夹是 azureml-logs 和 logs。启动评分脚本的控制器中的信息存储在 ~/azureml-logs/70_driver_log.txt 文件中。

检查高级信息

批量评分作业的分布式性质会导致日志来自不同的源，但两个组合文件可提供概要信息：

文件	说明
~/logs/job_progress_overview.txt	提供有关已创建的微批（也称为任务）的当前数量以及已处理的微批的当前数量的概要信息。随着微批的处理即将结束，日志会记录作业的结果。如果作业失败，日志会显示错误消息以及开始进行故障排除的位置。
~/logs/sys/master_role.txt	提供运行中作业的主节点（也称为业务流程协调程序）视图。此日志包含有关任务创建、进度监视和作业结果的信息。

查看堆栈跟踪数据是否有误

其他文件提供脚本中可能存在的错误的有关信息：

文件	说明
~/logs/user/error.txt	提供脚本中的错误摘要。
~/logs/user/error/*	提供在加载和运行入口脚本时所引发异常的完整堆栈跟踪。

查看每个节点的进程日志

若要全面了解每个节点如何执行评分脚本，请检查每个节点单独的进程日志。进程日志存储在 ~/logs/sys/node 文件夹中，并按工作器节点分组。

该文件夹包含一个 <ip_address>/ 子文件夹，其中的 <process_name.txt> 文件包含有关每个微批的详细信息。当工作器选择或完成微批时，文件夹内容将更新。对于每个微批，该日志包括以下内容：

工作进程的 IP 地址和进程 ID (PID)。
项总数、成功处理的项数和失败的项数。
开始时间、持续时间、处理时间和运行方法时间。

按节点检查定期检查

还可以查看每个节点的资源使用情况的定期检查结果。日志文件和安装程序文件存储在 ~/logs/perf 文件夹中。

使用 --resource_monitor_interval 参数更改检查间隔（以秒为单位）：

使用默认值：默认间隔为 600 秒（大约 10 分钟）。
停止检查：将值设置为 0 以停止在节点上运行检查。

该文件夹包含有关每个微批的 <ip_address>/ 子文件夹。当工作器选择或完成微批时，文件夹内容将更新。对于每个微批，该文件夹包含以下项：

文件或文件夹	说明
os/	存储有关节点中所有正在运行的进程的信息。一项检查将运行一个操作系统命令，并将结果保存到文件。在 Linux 上，该命令为 `ps`。该文件夹包含以下项： - %Y%m%d%H：包含一个或多个进程检查文件的子文件夹。子文件夹名称是检查的创建日期和时间（年、月、日、小时）。 processes_%M：子文件夹中的文件。该文件显示有关进程检查的详细信息。文件名以相对于检查创建时间的检查时间（分钟）结束。
node_disk_usage.csv	显示节点的磁盘使用情况详细信息。
node_resource_usage.csv	提供节点的资源使用情况概述。
processes_resource_usage.csv	提供每个进程的资源使用情况概述。

将日志记录添加到评分脚本

可以使用 Python 在评分脚本中记录日志。这些日志存储在 logs/user/stdout/<node_id>/process<number>.stdout.txt 文件中。

以下代码演示如何在脚本中添加日志记录：

import argparse
import logging

# Get logging_level
arg_parser = argparse.ArgumentParser(description="Argument parser.")
arg_parser.add_argument("--logging_level", type=str, help="logging level")
args, unknown_args = arg_parser.parse_known_args()
print(args.logging_level)

# Initialize Python logger
logger = logging.getLogger(__name__)
logger.setLevel(args.logging_level.upper())
logger.info("Info log statement")
logger.debug("Debug log statement")

解决常见错误

以下部分介绍在批处理终结点开发和使用期间可能发生的常见错误，以及解决步骤。

没有名为 azureml 的模块

Azure 机器学习批处理部署需要安装中的 azureml-core 包。

记录的消息：“没有名为 azureml 的模块。”

原因：安装中似乎缺少 azureml-core 包。

解决方案：将 azureml-core 包添加到 conda 依赖项文件中。

预测文件中没有输出

批处理部署需要一个空文件夹来存储 predictions.csv 文件。当部署遇到指定文件夹中的现有文件时，该过程不会将文件内容替换为新输出，也不会创建包含结果的新文件。

记录的消息：没有特定的记录消息。

原因：批处理部署无法覆盖现有 predictions.csv 文件。

解决方案：如果过程为预测指定了输出文件夹位置，请确保该文件夹不包含现有的 predictions.csv 文件。

批处理超时

批处理部署使用 timeout 值来确定部署应该等待多长时间才能完成每个批处理过程。当批处理的执行超过指定的超时时间时，批处理部署会中止该过程。

中止的进程将重试，直到达到 max_retries 值中指定的最大尝试次数。如果每次重试尝试时出现超时错误，部署作业将失败。

可以使用 retry_settings 参数为每个部署配置 timeout 和 max_retries 属性。

记录的消息：“[数字] 秒内没有进度更新。此检查中没有进度更新。自上次更新以来等待 [数字] 秒。”

原因：批处理执行超过指定的超时时间和最大重试尝试次数。此操作对应于入口脚本中的 run() 函数失败。

解决方案：增加部署的 timeout 值。默认情况下，timeout 值为 30，max_retries 值为 3。若要确定适合部署的 timeout 值，请考虑要在每个批次中处理的文件数及文件大小。减少要处理的文件数量并生成较小的微批。此方法可加快执行速度。

ScriptExecution.StreamAccess.Authentication 中的异常

若要成功进行批处理部署，计算群集的托管标识必须具有装载数据资产存储的权限。当托管标识没有足够的权限时，脚本会导致异常。此故障还可能导致数据资产存储无法装载。

记录的消息：“ScriptExecutionException 是由 StreamAccessException 引起的。 StreamAccessException 是由 AuthenticationException 引起的。”

原因：运行部署的计算群集无法装载数据资产所在的存储。计算的托管标识无权执行装载。

解决方案：确保与运行部署的计算群集关联的托管标识至少对存储帐户拥有存储 Blob 数据读取者访问权限。只有 Azure 存储帐户所有者可以在 Azure 门户中更改访问级别。

数据集初始化失败，无法装载数据集

批处理部署过程需要数据资产的装载存储。存储未装载时，无法初始化数据集。

记录的消息：“数据集初始化失败: UserErrorException: 消息: 无法装载数据集(ID='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'，名称=“无”，版本=无)。数据集的源不可访问，或者不包含任何数据。”

原因：运行部署的计算群集无法装载数据资产所在的存储。计算的托管标识无权执行装载。

dataset_param 没有指定值或默认值

在批处理部署期间，数据集节点会引用 dataset_param 参数。若要继续部署，该参数必须具有分配的值或指定的默认值。

记录的消息：“数据集节点 [code] 引用了没有指定值或默认值的参数 dataset_param。”

原因：提供给批处理终结点的输入数据资产不受支持。

解决方案：确保部署脚本提供批处理终结点支持的数据输入。

用户程序失败，运行失败

在批处理部署的脚本执行期间，如果 init() 或 run() 函数遇到错误，用户程序或运行可能会失败。可以在生成的日志文件中查看错误详细信息。

记录的消息：“用户程序失败并出现异常：运行失败。请查看日志了解详细信息。可以查看 logs/readme.txt 来了解日志的布局。”

原因：init() 或 run() 函数在执行评分脚本期间生成错误。

解决方案：按照以下步骤查找有关函数失败的详细信息：

在 Azure 机器学习工作室中，转到失败的批处理部署作业运行，然后选择“输出 + 日志”选项卡。
打开文件“logs”>“user”>“error”>“<node_identifier>”>“process<编号>.txt”。
找到由 init() 或 run() 函数生成的错误消息。

ValueError: 没有可连接的对象

若要成功进行批处理部署，微批中的每个文件都必须有效并实现受支持的文件类型。请记住，MLflow 模型仅支持文件类型的子集。有关详细信息，请参阅部署到批量推理时的注意事项。

记录的消息：“ValueError: 没有可连接的对象。”

原因：生成的微批中的所有文件都已损坏或者其文件类型不受支持。

解决方案：按照以下步骤查找有关失败文件的详细信息：

在 Azure 机器学习工作室中，转到失败的批处理部署作业运行，然后选择“输出 + 日志”选项卡。
打开文件“logs”>“user”>“stdout”>“<node_identifier>”>“process<编号>.txt”。
查找描述文件输入失败的条目，例如“ERROR:azureml:Error processing input file”。

如果文件类型不受支持，请查看受支持文件的列表。可能需要更改输入数据的文件类型，或者通过提供评分脚本来自定义部署。有关详细信息，请参阅将 MLflow 模型与评分脚本配合使用。

没有成功的微批

批处理部署过程要求批处理终结点以 run() 函数预期的格式提供数据。如果输入文件已损坏或与模型签名不兼容，run() 函数将无法返回成功的微批。

记录的消息：“run() 未返回成功的微批项。请查看 https://aka.ms/batch-inference-documentation 中的‘response: run()’。”

原因：批处理终结点无法以预期格式向 run() 函数提供数据。此问题的原因可能是读取的文件损坏，或输入数据与模型 (MLflow) 签名不兼容。

解决方案：按照以下步骤查找有关失败微批的详细信息：

在 Azure 机器学习工作室中，转到失败的批处理部署作业运行，然后选择“输出 + 日志”选项卡。
打开文件“logs”>“user”>“stdout”>“<node_identifier>”>“process<编号>.txt”。
查找描述微批的输入文件失败的条目，例如“处理输入文件时出错”。详细信息应描述输入文件无法正确读取的原因。

不允许访问受众或服务

Microsoft Entra 令牌是为标识允许的用户（受众）、服务和资源的特定操作颁发的。批处理终结点 REST API 的身份验证令牌必须将 resource 参数设置为 https://studio.ml.azure.cn。

记录的消息：没有特定的记录消息。

原因：尝试使用为不同受众或服务颁发的令牌调用批处理终结点和部署的 REST API。

解决方案：按照以下步骤解决此身份验证问题：

为批处理终结点 REST API 生成身份验证令牌时，请将 resource 参数设置为 https://studio.ml.azure.cn。

请注意，此资源与你用于从 REST API 管理终结点的资源不同。所有 Azure 资源（包括批处理终结点）都使用资源 https://management.chinacloudapi.cn 来进行管理。
为批处理终结点和部署调用 REST API 时，请务必使用为批处理终结点 REST API 颁发的令牌，不要使用为其他受众或服务颁发的令牌。在每种情况下，请确认使用正确的资源 URI。

如果要同时使用管理 API 和作业调用 API，则需要两个令牌。有关详细信息，请参阅批处理终结点上的授权 (REST)。

没有要路由到的有效部署

若要成功进行批处理部署，批处理终结点必须至少有一个有效的部署路由。标准方法是使用 defaults.deployment_name 参数定义默认批处理部署。

记录的消息：“没有要路由到的有效部署。请检查终结点是否至少有一个具有正权重值的部署，或使用部署特定的标头进行路由。”

原因：未正确设置默认批处理部署。

解决方案：使用以下方法之一来解决路由问题：

确认 defaults.deployment_name 参数定义正确的默认批处理部署。有关详细信息，请参阅更新默认批处理部署。
使用特定于部署的标头定义路由。

限制和不支持的方案

设计依赖于批处理终结点的机器学习部署解决方案时，请记住，某些配置和方案不受支持。以下部分标识了不受支持的工作区和计算资源，以及输入文件的无效类型。

不受支持的工作区配置

批处理部署不支持以下工作区配置：

配置了已启用隔离功能的 Azure 容器注册表的工作区
使用客户管理的密钥的工作区

不支持的计算配置

批处理部署不支持以下计算配置：

Azure ARC Kubernetes 群集
Azure Kubernetes 群集的精细资源请求（内存、vCPU、GPU）（只能请求实例计数）

不支持的输入文件类型

批处理部署不支持以下输入文件类型：

表格数据集 (V1)
文件夹和文件数据集 (V1)
MLtable (V2)

通过