对环境问题进行故障排除

本文介绍了如何对环境映像生成时可能会遇到的常见问题进行故障排除，并了解 AzureML 环境漏洞。

Azure 机器学习环境

Azure 机器学习环境封装了一个供你在其中进行机器学习训练的环境。 它们指定了基础 Docker 映像、Python 包和有关训练与评分脚本的软件设置。 环境是机器学习工作区中受管理且版本受控的资产，可用于创建跨各种计算目标的可重现、可审核且可移植的机器学习工作流。

环境类型

环境分为三类：特选环境、用户管理的环境和系统管理的环境。

特选环境是由 Azure 机器学习管理的预创建环境，默认可在每个工作区中使用。 其中包含的 Python 包和设置的集合可帮助你开始使用各种机器学习框架，应该按原样使用它们。 这些预先创建的环境还可以加快部署速度。

在用户管理的环境中，你需要负责设置环境，并在计算目标上安装训练脚本所需的每个包。 此外，请确保包含模型部署所需的任何依赖项。

这些类型的环境有两个子类型。 第一种类型是 BYOC（自带容器），你要将现有 Docker 映像引入 Azure 机器学习。 第二种类型是基于 Docker 生成上下文的环境，Azure 机器学习通过你提供的上下文具体化映像。

如果你希望通过 conda 自动管理 Python 环境，请使用系统管理的环境。 Azure 机器学习通过将基础 Docker 映像顶层的 conda 规范具体化，创建新的隔离 conda 环境。 默认情况下，Azure 机器学习会将常见功能添加到派生的映像。 基本映像中存在的任何 Python 包在隔离的 conda 环境中不可用。

创建和管理环境

可以从 Azure 机器学习 Python SDK、Azure 机器学习 CLI、Azure 机器学习工作室 UI、Visual Studio Code 扩展等客户端，创建和管理环境。

当提交试验而不注册或引用已经存在的环境时，“匿名”环境会自动注册到工作区中。 它们未列出，但你可以按版本或标签检索它们。

Azure 机器学习将环境定义生成到 Docker 映像中。 它还在 Azure 容器注册表中缓存与 Azure 机器学习工作区关联的映像，以便在后续的训练作业和服务终结点部署中重用它们。 具有相同定义的多个环境可能生成相同的缓存映像。

远程运行训练脚本需要创建 Docker 映像。

AzureML 环境中的漏洞

可以通过升级到较新版本的依赖项（基础映像、Python 包等）或通过迁移到满足安全要求的其他依赖项来解决漏洞。 缓解漏洞非常耗时且成本高昂，因为可能需要重构代码和基础结构。 随着开放源代码软件的普及以及复杂嵌套依赖项的采用，管理和跟踪漏洞变得非常重要。

有一些方法可以降低漏洞的影响：

• 减少依赖项数量 - 对每个方案使用尽可能少量的依赖项。
• 隔离环境，以便在一个位置确定问题范围和解决问题。
• 了解已标记的漏洞及其与方案的相关性。

扫描漏洞

若要监视和维持环境的清洁状况，可以使用适用于容器注册表的 Microsoft Defender 来帮助扫描映像中的漏洞。

漏洞与可重现性

可重现性是软件开发的基础之一。 开发生产代码时，必须保证重复的操作能产生相同的结果。 在缓解漏洞的过程中，可能会因为更改依赖项而中断可重现性。

Azure 机器学习的首要重点是保证可重现性。 环境分为三类：特选环境、用户管理的环境和系统管理的环境。

特选环境

特选环境是由 Azure 机器学习管理的预创建环境，默认可在预配的每个 Azure 机器学习工作区中使用。 Azure 机器学习发布了新版本以解决漏洞。 是否使用最新映像可能需要在可重现性和漏洞管理之间进行权衡。

特选环境包含 Python 包和设置的集合，有助于开始使用各种机器学习框架。 你应该按原样使用它们。 这些预先创建的环境还可以加快部署速度。

用户管理的环境

在用户管理的环境中，你需要负责设置环境，并在计算目标上安装训练脚本所需的包以及用于部署模型的包。 这些类型的环境有两个子类型：

• BYOC（自带容器）：用户向 Azure 机器学习提供 Docker 映像
• Docker 生成上下文：Azure 机器学习通过用户提供的内容具体化映像

一旦你在 Microsoft 提供的映像之上安装了更多依赖项或者自带基础映像，漏洞管理就由你负责。

系统管理的环境

如果你希望通过 conda 自动管理 Python 环境，请使用系统管理的环境。 Azure 机器学习通过将基础 Docker 映像顶层的 conda 规范具体化，创建新的隔离 conda 环境。 虽然 Azure 机器学习在每个版本中修补基础映像，但是否使用最新映像可能需要在可重现性和漏洞管理之间进行权衡。 因此在使用系统管理的环节时，你要负责选择用于作业或模型部署的环境版本。

漏洞：常见问题

基本 Docker 映像中的漏洞

环境中的系统漏洞通常从基础映像引入。 例如，标记为“Ubuntu”或“Debian”的漏洞来自系统级别的环境�基础 Docker 映像。 如果基础映像来自第三方颁发者，请检查最新版本是否修复了标记的漏洞。 Azure 机器学习中基础映像的最常见源包括：

• Azure 工件注册表 (MAR)，又名 Azure 容器注册表 (mcr.microsoft.com)。
  • 可以从 MAR 主页、调用 目录 API 或 /tags/list 列出映像
  • 可以在 Azure/AzureML-Containers 中找到AzureML 中训练基础映像的源和发行说明
• Nvidia（nvcr.io，或 nvidia 的配置文件）

如果最新版本的基础映像无法解决漏洞，可以安装漏洞扫描推荐的版本，从而解决基础映像漏洞：

apt-get install -y library_name

Python 包中的漏洞

漏洞也可能来自系统管理的基础映像上安装的 Python 包。 应更新 Python 依赖项以解决这些与 Python 相关的漏洞。 映像中的 Python (pip)漏洞通常来自用户定义的依赖项。

要搜索已知的 Python 漏洞和解决方案，请参阅 GitHub 顾问数据库。 要解决 Python 漏洞，请将包更新为已修复标记问题的版本：

pip install -u my_package=={good.version}

如果正在使用 conda 环境，请更新 conda 依赖项文件中的引用。

在一些情况下，在 conda 设置环境期间，会在基本 Docker 映像上自动安装 Python 包。 这些包的缓解步骤与用户引入的包的缓解步骤相同。 Conda 为其具体化的每个环境都安装了必要的依赖项。 加密、设置工具、wheel 等包将从 conda 的默认通道自动安装。 存在一个已知问题，即默认的 anaconda 通道缺少最新包版本，因此建议优先使用社区维护的 conda-forge 通道。 否则，请显式指定包和版本，即使未在计划在该环境中执行的代码中引用它们时也是如此。

缓存问题

有一个用作容器映像缓存的 Azure 容器注册表实例与你的 Azure 机器学习工作区相关联。 任何具体化的映像都会推送到容器注册表，并在为相应环境触发试验或部署时使用。 Azure 机器学习不会从容器注册表中删除任何映像，你要负责在不同的时间评估需要维护的映像。

对环境映像生成进行故障排除

了解如何排查环境映像生成和包安装问题。

环境定义问题

环境名称问题

不允许使用特选前缀

当自定义环境的名称使用仅为特选环境保留的字词时，可能会发生此问题。 特选环境是 Azure 维护的环境。 自定义环境是由你创建和维护的环境。

可能的原因：

• 环境名称以 Microsoft 或 AzureML 开头

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

更新环境名称以排除当前使用的保留前缀

资源

• 创建和管理可重用环境

环境名称太长

可能的原因：

• 环境名称长度超过 255 个字符

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

将环境名称更新为 255 个或更少的字符

Docker 问题

from azureml.core import Environment
myenv = Environment(name="myenv")
# Specify docker steps as a string.
dockerfile = r'''
FROM mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04
RUN echo "Hello from custom container!"
'''

myenv.docker.base_dockerfile = dockerfile

Docker 选项过多

可能的原因：

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

选择要用于生成环境的 Docker 选项。 然后将所有其他指定的选项设置为 None。

from azureml.core import Environment
myenv = Environment(name="myEnv")
dockerfile = r'''
FROM mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04
RUN echo "Hello from custom container!"
'''
myenv.docker.base_dockerfile = dockerfile
myenv.docker.base_image = "pytorch/pytorch:latest"

# Having both base dockerfile and base image set will cause failure. Delete the one you won't use.
myenv.docker.base_image = None

缺少 Docker 选项

可能的原因：

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

选择要用于生成环境的 Docker 选项，然后在环境定义中填充该选项。

from azureml.core import Environment
myenv = Environment(name="myEnv")
myenv.docker.base_image = "pytorch/pytorch:latest"

env_docker_image = Environment(
    image="pytorch/pytorch:latest",
    name="docker-image-example",
    description="Environment created from a Docker image.",
)
ml_client.environments.create_or_update(env_docker_image)

资源

容器注册表凭据缺少用户名或密码

可能的原因：

• 已在环境定义中为容器注册表指定用户名或密码，但不能同时指定两者

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

myEnv.docker.base_image_registry.username = "username"

from azureml.core import Workspace
ws = Workspace.from_config()
ws.set_connection("connection1", "ACR", "<URL>", "Basic", "{'Username': '<username>', 'Password': '<password>'}")

az ml connection create --file connection.yml --resource-group my-resource-group --workspace-name my-workspace

资源

基础映像注册表存在多个凭据

可能的原因：

• 为基础映像注册表指定了多个凭据集

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

from azureml.core import Workspace
ws = Workspace.from_config()
ws.list_connections()
ws.delete_connection("myConnection2")

myEnv.docker.base_image_registry.registry_identity = None

资源

基础映像注册表中的机密

可能的原因：

• 在环境定义中指定了凭据

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

不再支持在环境定义中指定凭据。 从环境定义中删除凭据，并改用工作区连接。

from azureml.core import Workspace
ws = Workspace.from_config()
ws.set_connection("connection1", "ACR", "<URL>", "Basic", "{'Username': '<username>', 'Password': '<password>'}")

az ml connection create --file connection.yml --resource-group my-resource-group --workspace-name my-workspace

资源

Dockerfile 长度超过限制

可能的原因：

• 指定的 Dockerfile 超过了最大大小（100 KB）

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

请缩短 Dockerfile，使其低于此限制

资源

• 请参阅最佳做法

Docker 生成上下文问题

缺少 Docker 生成上下文位置

可能的原因：

• 未在环境定义中提供生成上下文目录的路径

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

资源

• 了解生成上下文

缺少 Dockerfile 路径

当 Azure 机器学习找不到 Dockerfile 时，则可能发生此问题。 默认情况下，除非指定 Dockerfile 路径，否则 Azure 机器学习将在生成上下文目录的根目录中查找名为“Dockerfile”的 Dockerfile。

可能的原因：

• Dockerfile 不在生成上下文目录的根目录中，并且/或者名称不是“Dockerfile”，并且你未提供其路径

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

资源

• 了解生成上下文

基础映像问题

基础映像已弃用

可能的原因：

• 你使用了已弃用的基础映像
  • Azure 机器学习无法为使用已弃用映像的失败生成提供故障排除支持
  • Azure 机器学习不会更新或维护这些映像，因此它们面临漏洞风险

以下基础映像已弃用：

• azureml/base
• azureml/base-gpu
• azureml/base-lite
• azureml/intelmpi2018.3-cuda10.0-cudnn7-ubuntu16.04
• azureml/intelmpi2018.3-cuda9.0-cudnn7-ubuntu16.04
• azureml/intelmpi2018.3-ubuntu16.04
• azureml/o16n-base/python-slim
• azureml/openmpi3.1.2-cuda10.0-cudnn7-ubuntu16.04
• azureml/openmpi3.1.2-ubuntu16.04
• azureml/openmpi3.1.2-cuda10.0-cudnn7-ubuntu18.04
• azureml/openmpi3.1.2-cuda10.1-cudnn7-ubuntu18.04
• azureml/openmpi3.1.2-cuda10.2-cudnn7-ubuntu18.04
• azureml/openmpi3.1.2-cuda10.2-cudnn8-ubuntu18.04
• azureml/openmpi3.1.2-ubuntu18.04
• azureml/openmpi4.1.0-cuda11.0.3-cudnn8-ubuntu18.04
• azureml/openmpi4.1.0-cuda11.1-cudnn8-ubuntu18.04

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

将基础映像升级到受支持的映像的最新版本

• 查看可用的基础映像

无标记或摘要

可能的原因：

• 未在指定的基础映像中包含版本标记或摘要
• 如果没有这些说明符中的任何一个，环境将无法重现

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

在基础映像上至少包含以下说明符中的一项

• 版本标记
• 摘要
• 请参阅具有不可变标识符的映像

Python 问题

缺少 Python 版本

可能的原因：

• 尚未在环境定义中指定 Python 版本

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

from azureml.core.environment import CondaDependencies

myenv = Environment(name="myenv")
conda_dep = CondaDependencies()
conda_dep.add_conda_package("python==3.8")
env.python.conda_dependencies = conda_dep

如果对 conda 规范使用 YAML，请将 Python 作为依赖项包括在内

name: project_environment
dependencies:
  - python=3.8
  - pip:
      - azureml-defaults
channels:
  - anaconda

多个 Python 版本

可能的原因：

• 已在环境定义中指定了多个 Python 版本

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

myenv.python.conda_dependencies.remove_conda_package("python=3.8")

如果对 conda 规范使用 YAML，请仅包含一个 Python 版本作为依赖项

Python 版本不受支持

可能的原因：

• 你已指定一个 Python 版本，该版本到达或接近其生命周期结束日期，不再受支持

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

请指定尚未到达且未接近其生命周期结束日期的 Python 版本

不建议的 Python 版本

可能的原因：

• 你已指定一个 Python 版本，该版本到达或接近其生命周期结束日期

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

请指定尚未到达且未接近其生命周期结束日期的 Python 版本

无法验证 Python 版本

可能的原因：

• 你指定的 Python 版本语法不正确或格式不正确

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

myenv.python.conda_dependencies.add_conda_package("python=3.8")

使用正确的语法通过 conda YAML 指定 Python 版本

name: project_environment
dependencies:
  - python=3.8
  - pip:
      - azureml-defaults
channels:
  - anaconda

资源

• 请参阅 conda 包固定

Conda 问题

缺少 conda 依赖项

可能的原因：

• 你尚未在环境定义中提供 conda 规范，并且 user_managed_dependencies 设置为 False（默认）

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

env.python.user_managed_dependencies = True

from azureml.core.environment import CondaDependencies

env = Environment(name="env")
conda_dep = CondaDependencies()
conda_dep.add_conda_package("python==3.8")
env.python.conda_dependencies = conda_dep

资源

• 请参阅如何手动创建 conda 文件

无效的 conda 依赖项

可能的原因：

• 环境定义中指定的 conda 依赖项的格式不正确

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

"condaDependencies": {
    "channels": [
    "anaconda",
        "conda-forge"
    ],
    "dependencies": [
        "python=3.8",
        {
            "pip": [
                "azureml-defaults"
            ]
        }
    ],
    "name": "project_environment"
}

from azureml.core.environment import CondaDependencies

env = Environment(name="env")
conda_dep = CondaDependencies()
conda_dep.add_conda_package("python==3.8")
env.python.conda_dependencies = conda_dep

缺少 conda 通道

可能的原因：

• 尚未在环境定义中指定 conda 通道

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

为使环境可重现，请指定要从中拉取依赖项的通道。 如果未指定 conda 通道，conda 会使用可能会更改的默认值。

from azureml.core.environment import CondaDependencies

env = Environment(name="env")
conda_dep = CondaDependencies()
conda_dep.add_channel("conda-forge")
env.python.conda_dependencies = conda_dep

如果对 conda 规范使用 YAML，请包含要使用的 conda 通道

name: project_environment
dependencies:
  - python=3.8
  - pip:
      - azureml-defaults
channels:
  - anaconda
  - conda-forge

资源

不建议的基本 conda 环境

可能的原因：

• 在环境定义中指定了基础 conda 环境

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

不完整的环境更新可能导致依赖项冲突和/或意外的运行时错误，因此不建议使用基础 conda 环境。

from azureml.core.environment import CondaDependencies

env = Environment(name="env")
env.python.base_conda_environment = None
conda_dep = CondaDependencies()
conda_dep.add_conda_package("python==3.8")
env.python.conda_dependencies = conda_dep

资源

已取消固定的依赖项

可能的原因：

• 未在 conda 规范中为某些包指定版本

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

如果未指定依赖项版本，conda 包解析程序可能会在同一环境的后续版本上选择包的不同版本。 这会破坏环境的可重现性，并可能导致意外错误。

from azureml.core.environment import CondaDependencies

conda_dep = CondaDependencies()
conda_dep.add_conda_package("numpy==1.24.1")

如果为 conda 规范使用 YAML，请为依赖项指定版本

name: project_environment
dependencies:
  - python=3.8
  - pip:
      - numpy=1.24.1
channels:
  - anaconda
  - conda-forge

资源

• 请参阅 conda 包固定

Pip 问题

未指定 Pip

可能的原因：

• 未在 conda 规范中将 pip 指定为依赖项

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

为了可重现性，应在 conda 规范中指定并将 pip 固定为依赖项。

env.python.conda_dependencies.add_conda_package("pip==22.3.1")

如果对 conda 规范使用 YAML，请将 pip 作为依赖项包括在内

name: project_environment
dependencies:
  - python=3.8
  - pip=22.3.1
  - pip:
      - numpy=1.24.1
channels:
  - anaconda
  - conda-forge

资源

• 请参阅 conda 包固定

Pip 未固定

可能的原因：

• 未在 conda 规范中为 pip 指定版本

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

如果未指定 pip 版本，可以在同一环境的后续生成中使用其他版本。 如果不同版本的 pip 以不同的方式解析包，此行为可能会导致可重现性问题和其他意外错误。

env.python.conda_dependencies.add_conda_package("pip==22.3.1")

如果对 conda 规范使用 YAML，请指定 pip 的版本

name: project_environment
dependencies:
  - python=3.8
  - pip=22.3.1
  - pip:
      - numpy=1.24.1
channels:
  - anaconda
  - conda-forge

资源

• 请参阅 conda 包固定

其他环境问题

R 节已弃用

可能的原因：

• 在环境定义中指定了 R 节

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

适用于 R 的 Azure 机器学习 SDK 将在 2021 年底弃用，以便为使用 Azure CLI v2 改进 R 训练和部署体验让路

env.r = None

请参阅示例存储库，以开始使用 Azure CLI v2 训练 R 模型

环境不存在定义

可能的原因：

• 指定了不存在或尚未注册的环境
• 指定环境名称或环境版本时出现拼写错误或语法错误

受影响的区域（故障表现）：

• 注册环境失败

故障排除步骤

确保指定正确的环境名称以及正确的版本

• path-to-resource:version-number

应以其他方式指定环境的“最新”版本

• path-to-resource@latest

映像生成问题

ACR 问题

ACR 不可访问

当访问工作区的关联 Azure 容器注册表 (ACR) 资源失败时，可能会发生此问题。

可能的原因：

• 工作区的 ACR 位于虚拟网络 (VNet)（专用终结点或服务终结点）后面，并且你没有使用计算群集来生成映像。
• 工作区的 ACR 位于虚拟网络 (VNet)（专用终结点或服务终结点）后面，用于生成映像的计算群集无权访问工作区的 ACR。

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。
• 管道作业失败。
• 模型部署失败。

故障排除步骤

• 验证计算群集的 VNet 是否有权访问工作区的 ACR。
• 确保计算群集是基于 CPU 的。

资源

• 启用 Azure 容器注册表 (ACR)
• 如何使用环境

意外的 Dockerfile 格式

当 Dockerfile 格式不正确时，可能会出现此问题。

可能的原因：

• Dockerfile 包含无效语法
• Dockerfile 包含与 UTF-8 不兼容的字符

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于将在第一步隐式生成环境，所以运行作业失败。

故障排除步骤

• 确保 Dockerfile 格式正确且采用 UTF-8 编码

资源

• Dockerfile 格式

Docker 拉取问题

无法拉取 Docker 映像

如果在映像生成期间 Docker 映像拉取失败，则可能会发生此问题。

可能的原因：

• 容器注册表的路径名称不正确
• 虚拟网络后面的容器注册表使用了不受支持区域中的专用终结点
• 你尝试引用的映像在指定的容器注册表中不存在
• 你尚未提供你要从中拉取映像的专用注册表的凭据，或者提供的凭据不正确

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

检查容器注册表的路径名称是否正确

• 对于带有标记 3.2 的注册表 my-registry.io 和映像 test/image，有效的映像路径是 my-registry.io/test/image:3.2
• 请参阅注册表路径文档

如果你的容器注册表是在虚拟网络后面，或者在不受支持的区域中使用专用终结点

• 在门户中使用服务终结点配置容器注册表（公共访问），然后重试
• 将容器注册表置于虚拟网络后面之后，请运行 Azure 资源管理器模板，使工作区可以与容器注册表实例通信

如果你尝试引用的映像在指定的容器注册表中不存在

• 检查你是否使用了正确的标记，以及是否已将 user_managed_dependencies 设为 True。 将 user_managed_dependencies 设置为 True 会禁用 conda 并使用用户的已安装包

如果你尚未提供你要从中拉取映像的专用注册表的凭据，或者提供的凭据不正确

• 如果需要，请为容器注册表设置工作区连接

资源

• 工作区连接 v1

I/O 错误

当 Docker 映像拉取因网络问题而失败时，可能会发生此问题。

可能的原因：

• 网络连接问题可能是暂时的
• 防火墙阻止连接
• 无法访问 ACR，且存在网络隔离。 有关详细信息，请参阅 ACR 不可访问。

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

将主机添加到防火墙规则

• 请参阅配置入站和出站网络流量，了解如何将 Azure 防火墙用于 VNet 后面的工作区和资源

评估工作区设置。 你使用的是否是虚拟网络，或者你在映像生成期间尝试访问的资源是否在虚拟网络背后？

• 请确保自己遵循关于使用虚拟网络保护工作区的文章中所述的步骤
• Azure 机器学习需要对公共 Internet 进行入站和出站访问。 如果虚拟网络设置出现问题，那么在映像生成期间，可能会在访问所需的某些存储库时出现问题

如果未使用虚拟网络，或者已正确配置虚拟网络

• 尝试重新生成映像。 如果超时是由于网络问题造成的，则问题可能是暂时性的，且能通过重新生成来解决问题

生成期间出现的 Conda 问题

错误的规范

当 conda 规范中列出的包无效或 conda 命令执行不正确时，可能会出现此问题。

可能的原因：

• conda 规范中使用的语法不正确
• 错误地执行了 conda 命令

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

错误地使用 conda create 命令时，可能会发生 conda 规范错误

• 请阅读文档并确保使用有效的选项和语法
• conda env create 与 conda create 方面存在已知的混淆。 可在此处详细了解 conda 的响应和其他用户的已知解决方法

为了确保成功生成，请确保在 conda yaml 中使用正确的语法和有效的包规范

• 请参阅包匹配规范以及如何手动创建 conda 文件

通信错误

如果与要从其下载 conda 规范中列出的包的实体通信失败，则可能会发生此问题。

可能的原因：

• 无法与 conda 通道或包存储库通信
• 这些故障可能是暂时性网络故障造成的

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

确保 conda 规范中使用的 conda 通道/存储库正确

• 检查它们是否存在以及拼写是否正确

如果 conda 通道/存储库正确

• 尝试重新生成映像 - 故障可能是暂时性的，重新生成可能会解决问题
• 检查并确保 conda 规范中列出的包存在于指定的通道/存储库中

编译错误

当因为编译器错误而未能生成 conda 环境所需的包时，可能会出现此问题。

可能的原因：

• 包拼写错误，因此无法识别
• 编译器出现问题

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

如果使用编译器

• 确保你正在使用的编译器能被识别
• 如果需要，请将安装步骤添加到 Dockerfile
• 验证编译器的版本，并检查所使用的所有命令或选项是否与编译器版本兼容
• 如有必要，请升级编译器版本

确保已正确拼写列出的所有包，并且已正确固定版本

资源

• 有关运行命令的 Dockerfile 参考
• 示例编译器问题

缺少命令

在映像生成期间或在指定的 Python 包要求中无法识别命令时，可能会出现此问题。

可能的原因：

• 命令拼写错误
• 无法执行命令，因为未安装所需的包

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保命令拼写正确
• 确保已安装执行该命令所需的包
• 如果需要，请将安装步骤添加到 Dockerfile

资源

• 有关运行命令的 Dockerfile 参考

Conda 超时

如果 conda 包解析需要太长时间才能完成，则可能会发生此问题。

可能的原因：

• conda 规范中列出了大量的包，并且包含不必要的包
• 尚未固定依赖项（包含了 tensorflow 而不是 tensorflow=2.8）
• 列出了没有解决方案的包（包含了包 X=1.3 和 Y=2.8，但 X 的版本与 Y 的版本不兼容）

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 从 conda 规范中删除任何不必要的包
• 固定包 - 环境解析速度会更快
• 如果仍有问题，请查看了解和改进 conda 的性能一文获取深入信息

内存不足

如果 conda 包解析由于可用内存耗尽而失败，则可能会发生此问题。

可能的原因：

• conda 规范中列出了大量的包，并且包含不必要的包
• 尚未固定依赖项（包含了 tensorflow 而不是 tensorflow=2.8）
• 列出了没有解决方案的包（包含了包 X=1.3 和 Y=2.8，但 X 的版本与 Y 的版本不兼容）

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 从 conda 规范中删除任何不必要的包
• 固定包 - 环境解析速度会更快
• 如果仍有问题，请查看了解和改进 conda 的性能一文获取深入信息

找不到包

如果在通道/存储库中找不到规范中列出的一个或多个 conda 包，则可能会发生此问题。

可能的原因：

• conda 规范中未正确列出包的名称或版本
• 该包存在于某个 conda 通道中，但你未在 conda 规范中列出该包

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保包拼写正确且存在指定的版本
• 确保目标通道上存在包
• 确保通道/存储库列在 conda 规范中，以便在包解析期间正确拉取包

在 conda 规范中指定通道：

channels:
  - conda-forge
  - anaconda
dependencies:
  - python=3.8
  - tensorflow=2.8
Name: my_environment

资源

• 管理通道

缺少 Python 模块

如果 conda 规范中列出的 Python 模块不存在或无效，则可能会发生此问题。

可能的原因：

• 模块拼写错误
• 未识别模块

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保模块拼写正确且存在
• 检查并确保模块与 conda 规范中指定的 Python 版本兼容
• 如果你未在 conda 规范中列出特定的 Python 版本，请确保列出与模块兼容的特定版本，否则可能会使用不兼容的默认值

固定与所用 pip 模块兼容的 Python 版本：

channels:
  - conda-forge
  - anaconda
dependencies:
  - python=3.8
  - pip:
    - dataclasses
Name: my_environment

没有匹配的发行版

如果未找到与指定版本匹配的包，则可能会出现此问题。

可能的原因：

• 包名称拼写错误
• 在指定的通道或源上找不到包和版本
• 指定的版本不存在

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保包拼写正确且存在
• 确保存在指定的包版本
• 确保已指定将从中安装包的通道。 如果未指定通道，则将使用默认值，而默认值不一定具有你要查找的包

如何列出 conda yaml 规范中的通道：

channels:
  - conda-forge
  - anaconda
dependencies:
  - python = 3.8
  - tensorflow = 2.8
Name: my_environment

资源

• 管理通道
• pypi

无法生成 mpi4py

当为 mpi4py 生成轮失败时，可能会出现此问题。

可能的原因：

• 不符合成功安装 mpi4py 的要求
• 选择的安装 mpi4py 的方法存在问题

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

确保具有有效的 MPI 安装（优先选择 MPI-3 支持以及使用共享/动态库生成的 MPI）

• 请参阅 mpi4py 安装
• 若有需要，请遵循生成 MPI 的步骤

确保使用的是兼容的 Python 版本

• 建议使用 Python 3.8+，因为较旧版本的生命周期即将结束
• 请参阅 mpi4py 安装

资源

• mpi4py 安装

已尝试进行交互式身份验证

当 pip 在包安装过程中尝试交互式身份验证时，可能会出现此问题。

可能的原因：

• 你已列出需要身份验证的包，但未提供凭据
• 在映像生成期间，pip 尝试提示你进行身份验证，这导致生成失败，因为你无法在生成期间提供交互式身份验证

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

通过工作区连接提供身份验证

from azureml.core import Workspace
ws = Workspace.from_config()
ws.set_connection("connection1", "PythonFeed", "<URL>", "Basic", "{'Username': '<username>', 'Password': '<password>'}")

az ml connection create --file connection.yml --resource-group my-resource-group --workspace-name my-workspace

资源

禁止的 Blob

尝试访问存储帐户中的 Blob 被拒绝时时，可能会发生此问题。

可能的原因：

• 用于访问存储帐户的授权方法无效
• 你尝试通过共享访问签名 (SAS) 进行授权，但 SAS 令牌已过期或无效

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

阅读以下内容，了解如何授权访问 Azure 门户中的 blob 数据

阅读以下内容，了解如何授权访问 Azure 存储中的数据

如果有兴趣使用 SAS 访问 Azure 存储资源，请阅读以下内容

Horovod 生成

由于 horovod 生成失败而无法创建或更新 conda 环境时，可能会出现此问题。

可能的原因：

• 安装 Horovod 需要使用你尚未安装的其他模块
• 安装 Horovod 需要使用你尚未包括的某些库

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

许多问题都可能导致 horovod 失败，在 horovod 的文档中有一个详尽的列表

• 查看 horovod 故障排除指南
• 查看生成日志，看看在 horovod 生成失败时是否出现了错误消息
• horovod 疑难解答指南可能解释了你遇到的问题，并提供了解决方案

资源

• horovod 安装

找不到 Conda 命令

在 conda 环境创建或更新期间无法识别 conda 命令时，则可能发生此问题。

可能的原因：

• 你尚未在你使用的基础映像中安装 conda
• 尝试执行 conda 命令之前，你还没有通过 Dockerfile 安装 conda
• 尚未将 conda 包含在路径中，或者尚未将其添加到路径

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

在尝试执行任何 conda 命令之前，请确保 Dockerfile 中有 conda 安装步骤

• 请查看此 conda 安装程序列表，以确定相应方案所需的内容

如果已尝试安装 conda 但遇到此问题，请确保已将 conda 添加到路径

• 请查看此示例以获取指导
• 查看如何在 Dockerfile 中设置环境变量

资源

• 所有可用的 conda 发行版都可在 conda 存储库中找到

不兼容的 Python 版本

如果 conda 环境中指定的包与指定的 Python 版本不兼容，则可能发生此问题。

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

请使用与指定的 Python 版本兼容的其他版本的包

或者，使用与指定的包兼容的其他版本的 Python

• 如果要更改 Python 版本，请使用受支持的版本，并且该版本未接近其生命周期结束日期
• 请参阅 Python

资源

• Python 文档（按版本）

Conda 裸重定向

如果你在不使用引号的情况下使用“<”或“>”在命令行上指定包，则可能发生此问题。 此语法可能导致 conda 环境创建或更新失败。

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

在包规范的两侧添加引号

• 例如，将 conda install -y pip<=20.1.1 更改为 conda install -y "pip<=20.1.1"

UTF-8 解码错误

当在 conda 规范中解码字符失败时，则可能发生此问题。 

可能的原因：

• conda YAML 文件包含与 UTF-8 不兼容的字符。

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

生成期间出现的 Pip 问题

无法安装包

当映像生成在 Python 包安装过程中失败时，则可能会出现此问题。

可能的原因：

• 有许多问题可能会导致此错误
• 此消息是通用的，当 Azure 机器学习分析尚未涵盖你遇到的错误时，会显示此消息

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

请查看生成日志，了解有关映像生成失败的详细信息

请留下反馈，以便 Azure 机器学习团队分析你遇到的错误

• 提出问题或建议

无法卸载包

当 pip 无法卸载通过操作系统的包管理器安装的 Python 包时，则可能发生此问题。

可能的原因：

• 现有 pip 问题或 pip 版本有问题
• 未使用隔离环境引起的问题

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

请阅读以下内容，确定失败是否由现有 pip 问题引起

• 创建 Docker 映像时无法卸载
• pip 10 distutils 部分卸载问题
• pip 10 不再卸载 distutils 包

请尝试以下做法

pip install --ignore-installed [package]

请尝试使用 conda 创建单独的环境

运算符无效

当 pip 由于在要求中找到的运算符无效而无法安装 Python 包时，可能会出现此问题。

可能的原因：

• 在 Python 包要求中找到的运算符无效

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保包拼写正确且存在指定的版本
• 确保包版本说明符的格式正确，而且使用的比较运算符有效。 请参阅版本说明符
• 将无效运算符替换为错误消息中建议的运算符

没有匹配的发行版

如果未找到与指定版本匹配的包，则可能会出现此问题。

可能的原因：

• 包名称拼写错误
• 在指定的通道或源上找不到包和版本
• 指定的版本不存在

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保包拼写正确且存在
• 确保存在指定的包版本
• 运行 pip install --upgrade pip，然后再次运行原始命令
• 确保使用的 pip 可以安装所需 Python 版本的包。 请参阅我应该使用 pip 还是 pip3？

资源

• 运行 Pip
• pypi
• 安装 Python 模块

wheel 文件名无效

错误地指定了 wheel 文件时，可能会出现此问题。

可能的原因：

• wheel 文件名拼写错误或使用了不正确的格式
• 找不到指定的 wheel 文件

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保文件名拼写正确且存在
• 确保遵循 wheel 文件名的格式

生成问题

未指定目标且未找到生成文件

如果尚未指定任何目标，并且运行 make 时找不到生成文件，则可能会出现此问题。

可能的原因：

• 生成文件在当前目录中不存在
• 未指定目标

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

• 确保生成文件拼写正确
• 确保生成文件存在于当前目录中
• 如果有自定义生成文件，请使用 make -f custommakefile 指定它
• 在生成文件或命令行中指定目标
• 配置生成并生成生成文件
• 确保已正确设置生成文件的格式，并且已使用制表符进行缩进

资源

• GNU Make

复制问题

找不到文件

当 Docker 无法查找并复制文件时，可能会出现此问题。

可能的原因：

• 在 Docker 生成上下文中找不到源文件
• .dockerignore 排除的源文件

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于将在第一步隐式生成环境，所以运行作业失败。

故障排除步骤

• 确保源文件存在于 Docker 生成上下文中
• 确保源路径和目标路径存在且拼写正确
• 确保源文件未在当前目录和父目录的 .dockerignore 中列出
• 从 COPY 命令所在的同一行中删除任何尾随注释

资源

• Docker COPY
• Docker 生成上下文

Apt-Get 问题

无法运行 apt-get 命令

当 apt-get 无法运行时，可能会出现此问题。

可能的原因：

• 网络连接问题可能是暂时的
• 与在其上运行 apt-get 的包相关的依赖项损坏
• 你没有使用 apt-get 命令的正确权限

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于将在第一步隐式生成环境，所以运行作业失败。

故障排除步骤

• 检查网络连接和 DNS 设置
• 运行 apt-get check 以检查依赖项是否损坏
• 运行 apt-get update，然后再次运行原始命令
• 使用 -f 标志运行命令，这将尝试解决依赖项损坏所带来的问题
• 使用 sudo 权限运行命令，例如 sudo apt-get install <package-name>

资源

• 使用 APT 进行包管理
• Ubuntu Apt-Get
• apt-get 失败时需要执行的操作
• Linux 中的 apt-get 命令和示例

Docker 推送问题

无法存储 Docker 映像

将 Docker 映像推送到容器注册表失败时，可能会出现此问题。

可能的原因：

• 与工作区关联的 ACR 出现暂时性问题
• 虚拟网络后面的容器注册表使用了不受支持区域中的专用终结点

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

如果怀疑此失败是工作区 Azure 容器注册表 (ACR) 的暂时性问题，请重试环境生成

如果你的容器注册表是在虚拟网络后面，或者在不受支持的区域中使用专用终结点

• 在门户中使用服务终结点配置容器注册表（公共访问），然后重试
• 将容器注册表置于虚拟网络后面之后，请运行 Azure 资源管理器模板，使工作区可以与容器注册表实例通信

如果未使用虚拟网络，或者已正确配置该虚拟网络，请通过尝试简单的本地生成来测试凭据是否适用于 ACR

• 从 Azure 门户获取工作区 ACR 的凭据
• 使用 docker login <myregistry.azurecr.cn> -u "username" -p "password" 登录到 ACR
• 对于映像“helloworld”，请通过运行 docker push helloworld 测试到 ACR 的推送
• 请参阅快速入门：使用 Azure 容器注册表任务生成和运行容器映像

未知 Docker 命令

未知的 Docker 指令

当 Docker 无法识别 Dockerfile 中的指令时，可能会出现此问题。

可能的原因：

• Dockerfile 中使用的 Docker 指令未知
• Dockerfile 包含无效语法

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于将在第一步隐式生成环境，所以运行作业失败。

故障排除步骤

• 请确保 Docker 命令有效且拼写正确
• 确保 Docker 命令和参数之间有空格
• 确保 Dockerfile 中没有不必要的空格
• 确保 Dockerfile 格式正确且采用 UTF-8 编码

资源

• Dockerfile 参考

找不到命令

“未能识别命令”

当无法识别运行的命令时，可能会出现此问题。

可能的原因：

• 尝试执行命令之前，你还没有通过 Dockerfile 安装该命令
• 尚未将命令包含在路径中，或者尚未将其添加到路径

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于将在第一步隐式生成环境，所以运行作业失败。

故障排除步骤在尝试执行命令之前，请确保 Dockerfile 中有该命令的安装步骤

• 查看此示例

如果已尝试安装命令但遇到此问题，请确保已将该命令添加到路径

• 查看此示例
• 查看如何在 Dockerfile 中设置环境变量

其他生成问题

生成日志不可用

可能的原因：

• Azure 机器学习无权将生成日志存储在存储帐户中
• 保存生成日志时发生暂时性错误
• 在触发映像生成之前发生系统错误

受影响的区域（故障表现）：

• 已成功生成，但没有可用日志。
• 从 UI、SDK 和 CLI 生成环境失败。
• 由于 Azure 机器学习会在第一步隐式生成环境，因此运行作业失败。

故障排除步骤

如果这是暂时性问题，则重新生成可能会解决此问题

找不到映像

当找不到指定的基础映像时，可能会出现此问题。

可能的原因：

• 未正确指定映像
• 指定的映像不存在于指定的注册表中

受影响的区域（故障表现）：

• 从 UI、SDK 和 CLI 生成环境失败。
• 由于将在第一步隐式生成环境，所以运行作业失败。

故障排除步骤

• 确保基础映像拼写正确且格式正确
• 确保所使用的基础映像存在于指定的注册表中

资源

• Azure 机器学习基础映像