排查批处理终结点问题

  • 项目

适用范围：Azure CLI ml 扩展 v2（当前版本）Python SDK azure-ai-ml v2（当前版本）

了解如何排查和解决在使用批处理终结点进行批量评分时可能遇到的常见错误。 在本文中，你将了解：

了解批量评分作业的日志

获取日志

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

选项 1：将日志流式传输到本地控制台

可运行以下命令将系统生成的日志流式传输到控制台。 只会流式处理 azureml-logs 文件夹中的日志。

az ml job stream --name <job_name>

选项 2：在工作室中查看日志

若要在工作室中获取运行的链接，请运行：

az ml job show --name <job_name> --query interaction_endpoints.Studio.endpoint -o tsv
  1. 使用上述命令返回的值在工作室中打开作业。
  2. 选择“batchscoring”
  3. 打开“输出 + 日志”选项卡
  4. 选择要查看的日志

了解日志结构

有两个顶级日志文件夹：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/：此文件包含在加载和运行入口脚本时引发的异常的完整堆栈跟踪。

如需全面了解每个节点如何执行评分脚本，请查看每个节点单独的进程日志。 进程日志位于 sys/node 文件夹中，按工作器节点分组：

  • ~/logs/sys/node/<ip_address>/<process_name>.txt：此文件提供有关每个微型批处理在工作器拾取或完成它时的详细信息。 对于每个微型批处理，此文件包括以下内容：

    • 工作进程的 IP 地址和 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>/processNNN.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”的模块

记录的消息：No module named 'azureml'。

原因：Azure 机器学习批处理部署需要安装 azureml-core 包。

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

输出已存在

原因：Azure 机器学习批处理部署无法覆盖输出生成的 predictions.csv 文件。

解决方法：如果指示了预测的输出位置，请确保路径指向一个不存在的文件。

入口脚本中的 run() 函数超时 [number] 次

记录的消息：No progress update in [number] seconds. No progress update in this check. Wait [number] seconds since last update.

原因：可能为批处理部署配置了一个 timeout 值，该值指示在处理单个批之前部署应等待多长时间。 如果批的执行时间超过此类值，则会中止任务。 已中止的任务可以重试最多次数，该次数也可以配置。 如果每次重试时发生 timeout，则部署作业将会失败。 可为每个部署配置这些属性。

解决方法：通过更新部署来增大部署的 timemout 值。 在参数 retry_settings 中配置这些属性。 默认已配置 timeout=30 和 retries=3。 在确定 timeout 的值时，请考虑每批中要处理的文件数，以及其中每个文件的大小。 还可以减少文件，以考虑使用数量更多但大小更小的微批，从而加快执行速度。

ScriptExecution.StreamAccess.Authentication

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

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

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

数据集初始化失败

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

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

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

数据集节点 [code] 引用了没有指定值或默认值的参数 dataset_param

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

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

解决方法：确保批处理终结点支持提供的数据输入。

用户程序失败并出现异常：运行失败，请查看日志了解详细信息

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

原因：运行评分脚本的 init() 或 run() 函数时出错。

解决方法：转到“输出 + 日志”并打开位于 logs > user > error > 10.0.0.X > process000.txt 处的文件。 你会看到 init() 或 run() 方法生成的错误消息。

ValueError: 没有可连接的对象

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

原因：生成的微批中的所有文件都已损坏或者其文件类型不受支持。 请记住，MLflow 模型支持一部分文件类型，如部署到批处理推理时的注意事项中所述。

解决方案：转到文件 logs/usr/stdout/<process-number>/process000.stdout.txt 并查找类似 ERROR:azureml:Error processing input file 的条目。 如果文件类型不受支持，请查看受支持文件的列表。 可能需要更改输入数据的文件类型，或者通过提供评分脚本来自定义部署，如使用具有评分脚本的 MLflow 模型中所述。

run() 未返回成功的微批项

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

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

解决方法：若要了解发生了什么情况，请转到“输出 + 日志”并打开位于 logs > user > stdout > 10.0.0.X > process000.stdout.txt 处的文件。 查找类似于 Error processing input file 的错误条目。 在该文件中应该可以找到有关为何无法正确读取输入文件的详细信息。

不允许 JWT 中的受众

上下文：使用其 REST API 调用批处理端点时。

原因：用于调用端点/部署的 REST API 的访问令牌指示为不同受众/服务颁发的令牌。 Microsoft Entra 令牌是为特定操作颁发的。

解决方案：生成要与批处理端点 REST API 一起使用的身份验证令牌时，请确保将 resource 参数设置为 https://studio.ml.azure.cn。 请注意，此资源与使用 REST API 管理端点所需指示的资源不同。 所有 Azure 资源（包括批处理端点）都使用资源 https://management.chinacloudapi.cn 来管理它们。 确保在每个案例中使用正确的资源 URI. 请注意，如果要同时使用管理 API 和作业调用 API，你需要两个令牌。 有关详细信息，请参阅：批处理终结点上的身份验证 (REST)。

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

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

解决方案：确保正确设置默认批处理部署。 你可能需要更新默认批处理部署

限制以及不支持的方案

设计依赖于批处理终结点的机器学习解决方案时，某些配置和方案可能不受支持。

不支持以下工作区配置：

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

不支持以下计算配置：

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

不支持以下输入类型：

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

后续步骤