预生成 Docker 映像的 Python 包扩展性（预览版）

适用于：Python SDK azureml v1

用于模型推理的预生成 Docker 映像包含常用机器学习框架的包。 可使用两种方法来添加 Python 包，而无需重新生成 Docker 映像：

• 动态安装：当 Docker 容器启动时，此方法使用一个 requirements 文件自动还原 Python 包。

  若要进行快速原型制作，请考虑使用此方法。 映像启动时，将使用 requirements.txt 文件还原包。 此方法会增加映像启动时间，你必须等待更长的时间，然后部署才能处理请求。

• 预安装的 Python 包：提供包含预安装的 Python 包的目录。 在部署过程中，此目录将装载到容器中，供入口脚本 (score.py) 使用。

  此方法可用于生产部署。 由于包含包的目录已装载到映像中，因此即使部署无法访问公共 Internet，也可以使用该目录。 例如，在已部署到受保护 Azure 虚拟网络的情况下。

先决条件

• Azure 机器学习工作区。 有关创建工作区的教程，请参阅 Azure 机器学习入门。
• 熟悉 Azure 机器学习环境的用法。
• 熟悉在 Azure 机器学习中的何处以及如何部署模型。

动态安装

当映像启动时，此方法使用一个 requirements 文件自动还原 Python 包。

若要通过 requirements.txt 扩展预生成的 Docker 容器映像，请执行以下步骤：

1. 连同 score.py 脚本一起创建 requirements.txt 文件。
2. 将全部所需的包添加到 requirements.txt 文件。
3. 将 Azure 机器学习环境中的 AZUREML_EXTRA_REQUIREMENTS_TXT 环境变量设置为 requirements.txt 文件的位置。

部署后，系统会自动为评分脚本还原包。

以下示例演示如何设置 AZUREML_EXTRA_REQUIRMENTS_TXT 环境变量：

from azureml.core import Environment
from azureml.core.conda_dependencies import CondaDependencies 

myenv = Environment(name="my_azureml_env")
myenv.docker.enabled = True
myenv.docker.base_image = <MCR-path>
myenv.python.user_managed_dependencies = True

myenv.environment_variables = {
    "AZUREML_EXTRA_REQUIREMENTS_TXT": "requirements.txt"
}

下图是动态安装过程的视觉表示形式：

预安装的 Python 包

此方法将你提供的目录装载到映像中。 然后，此目录中的 Python 包可供入口脚本 (score.py) 使用。

若要通过预安装的 Python 包扩展预生成的 Docker 容器映像，请执行以下步骤：

1. 使用 virtualenv 创建虚拟环境。

2. 安装依赖项。 例如，如果在 requirements.txt 中包含了依赖项列表，则可以使用该列表通过 pip install -r requirements.txt 进行安装，或者只是使用 pip install 安装单个依赖项。

3. 指定 AZUREML_EXTRA_PYTHON_LIB_PATH 环境变量时，请确保指向正确的站点包目录，该目录因环境名称和 Python 版本而异。 以下代码演示如何为名为 myenv 的虚拟环境和 Python 3.7 设置路径：

   from azureml.core import Environment
   from azureml.core.conda_dependencies import CondaDependencies 
   
   myenv = Environment(name='my_azureml_env')
   myenv.docker.enabled = True
   myenv.docker.base_image = <MCR-path>
   myenv.python.user_managed_dependencies = True
   
   myenv.environment_variables = {
       "AZUREML_EXTRA_PYTHON_LIB_PATH": "myenv/lib/python3.7/site-packages"
   }
   

下图是预安装包过程的视觉表示形式：

常见问题

仅当 myenv 站点包目录包含所有依赖项时，装载解决方案才起作用。 如果本地环境使用安装在其他位置的依赖项，则这些依赖项不会在映像中提供。

下面是可能导致此问题的一些因素：

• virtualenv 默认创建一个隔离的环境。 激活虚拟环境后，无法使用全局依赖项。
• 如果某个 PYTHONPATH 环境变量指向全局依赖项，它可能会干扰虚拟环境。 激活环境后，运行 pip list 和 pip freeze 以确保环境中没有不需要的依赖项。
• Conda 和 virtualenv 环境可能会相互干扰。 确保不要同时使用 Conda 环境和 virtualenv。

限制

Model.package()

• Model.package() 方法可让你创建 Docker 映像形式的模型包，或者在 Dockerfile 生成上下文中创建模型包。 对预生成的推理 Docker 映像使用 Model.package() 会触发中间映像生成，这会将非 root 用户更改为 root 用户。

• 建议使用我们的 Python 包扩展性解决方案。 如果需要其他依赖项（如 apt 包），请创建自己的从推理映像扩展的 Dockerfile。

常见问题

• 在 requirements.txt 扩展性方法中，文件名是否必须为 requirements.txt？

  myenv.environment_variables = {
      "AZUREML_EXTRA_REQUIREMENTS_TXT": "name of your pip requirements file goes here"
  }
  

• 你们是否可以总结一下 requirements.txt 方法与装载方法相比较的信息？

  一开始请使用 requirements.txt 方法进行原型制作。 经过一定次数的迭代后，如果你确信哪些包（和版本）能够成功完成模型部署，请切换到“装载解决方案”。

  下面是详细的比较。

  比较项	Requirements.txt（动态安装）	包装载
  解决方案	创建一个 requirements.txt 以用于在容器启动时安装指定的包。	创建具有所有依赖项的本地 Python 环境。 在运行时将此目录装载到容器中。
  包安装	无需额外安装（假设已安装 pip）	虚拟环境或 Conda 环境安装。
  虚拟环境设置	无需额外设置虚拟环境，因为用户可以按需使用 pip freeze 拉取当前本地用户环境来创建 requirements.txt。	需要设置干净的虚拟环境，这可能需要执行额外的步骤，具体取决于当前的用户本地环境。
  调试	易于设置和调试服务器，因为依赖项已明确列出。	在调试服务器时，不干净的虚拟环境可能导致问题。 例如，可能无法明确知道错误是来源于环境还是用户代码。
  横向扩展期间的一致性	不一致，因为此方法依赖于外部 PyPi 包以及用户是否固定了其依赖项。 这些外部下载可能会导致异常行为。	仅依赖于用户环境，因此不会出现一致性问题。

• 为何在容器中找不到我的 requirements.txt 和已装载的依赖项目录？

  在本地验证是否正确设置了环境变量。 接下来，验证指定的路径是否拼写正确，以及这些路径是否存在。 检查是否在推理配置构造函数中正确设置了源目录。

• 是否可以在预生成的推理 Docker 映像中替代 Python 包依赖项？

  是的。 如果你要使用已在推理映像中安装的其他 Python 包版本，我们的扩展性解决方案将遵循你的版本。 请确保这两个版本之间没有冲突。

最佳实践

• 请参阅加载已注册的模型文档。注册模型目录时，请不要在该目录中包含你的评分脚本、已装载的依赖项目录或 requirements.txt。

• 有关如何加载已注册模型或本地模型的详细信息，请参阅在何处以及如何部署。

Bug 修复

2021-07-26

• AZUREML_EXTRA_REQUIREMENTS_TXT 和 AZUREML_EXTRA_PYTHON_LIB_PATH 现在始终相对于评分脚本的目录。 例如，如果 requirements.txt 和评分脚本都位于 my_folder 中，然后需要将 AZUREML_EXTRA_REQUIREMENTS_TXT 设置为 requirements.txt。 不再将 AZUREML_EXTRA_REQUIREMENTS_TXT 设置为 my_folder/requirements.txt。

后续步骤

若要详细了解如何部署模型，请参阅如何部署模型。

若要了解如何排查预生成 Docker 映像部署的问题，请参阅如何排查预生成 Docker 映像部署的问题。