笔记本范围内的 Python 库

笔记本范围内的库允许你创建、修改、保存、重用和共享特定于笔记本的自定义 Python 环境。 安装笔记本范围内的库时,只有当前笔记本以及与该笔记本关联的任何作业有权访问该库。 附加到同一群集的其他笔记本不受影响。

笔记本范围内的库不会跨会话保留。 必须在每个会话开始时或从群集中分离笔记本时,重新安装笔记本范围内的库。

安装笔记本范围内的库有两种方法:

  • 在笔记本中运行 %pip magic 命令。 Databricks Runtime 7.1 及更高版本和 Databricks Runtime 6.4 ML 及更高版本支持 %pip 命令。 Databricks 建议对新的工作负载使用此方法。 本文介绍如何使用这些 magic 命令。
  • 使用 Azure Databricks 库实用工具。 库实用工具仅在 Databricks Runtime 上受支持,而在 Databricks Runtime ML 或用于基因组学的 Databricks Runtime 上不受支持。 请参阅库实用工具 (dbutils.library)

若要为附加到群集的所有笔记本安装库,请使用工作区库或群集安装的库。

要求

默认情况下,可在 Databricks Runtime 7.1(及更高版本)、Databricks Runtime 7.1(及更高版本)和 Databricks Runtime 7.1 for Genomics(及更高版本)中,通过 magic 命令使用笔记本范围的库。

在 Runtime 6.4 ML 至 7.0 ML 和 Databricks Runtime 6.4 for Genomics 至 Databricks Runtime 7.0 for Genomics 中,还可通过配置设置来使用这些库。 将Spark 配置设置为true

在运行 Databricks Runtime 7.4 ML 或用于基因组学的 Databricks Runtime 7.4 或更低版本的高并发群集上,以笔记本为作用域的库与表访问控制凭据直通不兼容。 替代方法是使用 Databricks Runtime 群集上的库实用工具 (dbutils.library),或者将群集升级到 Databricks Runtime 7.5 ML 或者用于基因组学的 Databricks Runtime 7.5 或更高版本。

若要将笔记本范围的库与 Databricks Connect 结合使用,必须使用库实用工具 (dbutils.library)

驱动程序节点

使用笔记本范围内的库可能会导致更多的流量流向驱动程序节点,因为它可使环境在执行程序节点之间保持一致。

当使用包含 10 个或更多个节点的群集时,Databricks 建议驱动程序节点至少满足以下规范:

  • 对于 100 节点 CPU 群集,请使用 Standard_DS5_v2。
  • 对于 10 节点 GPU 群集,请使用 Standard_NC12。

对于更大的群集,请使用更大的驱动程序节点。

使用 %pip 安装笔记本范围内的库

重要

  • 应将所有 %pip 命令放在笔记本的开头。 在修改环境的任何 %pip 命令后,会重置笔记本状态。 如果在笔记本中创建 Python 方法或变量,然后在后面的一个单元格中使用 %pip 命令,则这些方法或变量会丢失。
  • 使用 %pip 升级、修改或卸载核心 Python 包(如 IPython),可能会导致某些功能无法按预期正常工作。 例如,IPython 7.21 及更高版本与 Databricks Runtime 8.1 和更低版本不兼容。 如果遇到此类问题,可以通过拆离并重新附加笔记本或者通过重启群集来重置环境。

使用 %pip 命令管理库

命令 %pip 等效于 %pip 命令,并支持相同的 API。 以下部分介绍如何使用 %pip 命令来管理环境的示例。 有关使用 安装 Python 包的信息 pip ,请参阅 pip 和相关页面。

本节内容:

使用 %pip 安装库

%pip install matplotlib

使用 %pip 安装 wheel 包

%pip install /path/to/my_package.whl

使用 %pip 卸载库

注意

你无法卸载 Databricks Runtime 中包含的库,也无法卸载作为群集库安装的库。 如果你安装的库版本不同于 Databricks Runtime 中包含的版本或在群集上安装的版本,则可以使用 %pip uninstall 将库还原为 Databricks Runtime 中的默认版本或在群集上安装的版本,但不能使用 %pip 命令卸载 Databricks Runtime 中包含的库版本或在群集上安装的库版本。

%pip uninstall -y matplotlib

需要 -y 选项。

使用 %pip 从版本控制系统安装库

%pip install git+https://github.com/databricks/databricks-cli

可以向 URL 添加参数,以指定版本或 Git 子目录等。 有关详细信息 以及使用其他 版本控制系统的示例,请参阅 VCS 支持。

使用 %pip 通过 Databricks 机密管理的凭据安装专用包

Pip 支持通过基本身份验证从专用源安装包,包括专用版本控制系统和专用包存储库,如 NexusArtifactory。 机密管理可通过 Databricks 机密 API 获得,因此可以存储身份验证令牌和密码。 使用 DBUtils API 从笔记本访问机密。 请注意,可以在 magic 命令中使用 $variables

若要从专用存储库安装包,请使用 --index-url 选项指定链接到 %pip install 的存储库 URL,或将其添加到 ~/.pip/pip.conf 中的 pip 配置文件。

token = dbutils.secrets.get(scope="scope", key="key")
%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

同样,可以将机密管理与 magic 命令结合使用,从版本控制系统安装专用包。

token = dbutils.secrets.get(scope="scope", key="key")
%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

使用 %pip 从 DBFS 安装包

可以使用 %pip 安装已保存在 DBFS 上的专用包。

将文件上传到 DBFS 时,它将自动重命名该文件,并使用下划线替换空格、句点和连字符。 pip 要求 wheel 文件的名称在版本(例如 0.1.0)中使用句点和连字符,而不是空格或下划线。 若要使用 命令安装包 %pip ,必须 %pip 这些要求。

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

在要求文件中保存库

%pip freeze > /dbfs/requirements.txt

文件路径中的任何子目录都必须已存在。 运行 %pip freeze > /dbfs/<new-directory>/requirements.txt 时,如果目录 /dbfs/<new-directory> 尚不存在,则该命令会失败。

使用要求文件安装库

要求 文件 包含使用 安装的包的列表 。 以下是使用要求文件的示例:

%pip install -r /dbfs/requirements.txt

有关 文件详细信息, 请参阅要求 文件格式。

使用 %conda 命令管理库

重要

%conda 命令已弃用,在 Databricks Runtime ML 8.4 之后将不再受支持。 Databricks 建议使用 %pip 来管理笔记本范围内的库。 如果需要只能使用 conda 安装的 python 库,可以使用基于 conda 的 docker 容器预先安装所需的库。

Anaconda Inc. 在 2020 年 9 月为 anaconda.org 通道更新了其服务条款。 根据新的服务条款,如果依赖 Anaconda 的打包和分发,则可能需要商业许可证。 有关详细信息,请参阅 Anaconda Commercial Edition 常见问题解答。 对任何 Anaconda 通道的使用都受其服务条款的约束。

由于这一变化,Databricks 已删除 Databricks Runtime ML 8.0 中 Conda 包管理器的默认通道配置。 若要使用 %conda 命令安装或更新包,必须指定通道。

默认的 Anaconda 通道将在 2021 年 5 月 25 日或之后从所有 Databricks Runtime 版本中删除。 这是一项重大更改。 必须更新 和 的所有 %conda install 用法 %sh conda install ,以使用"-c"指定通道。 还必须更新 init-scripts 中 conda 命令的用法,以使用"-c"指定通道。 如果未指定通道,则所有 conda 命令都将失败,并显示 PackagesNotFoundError

命令 %conda 等效于 %conda 命令,支持同一 API,但下面列出了一些限制。 以下部分介绍如何使用 %conda 命令来管理环境的示例。 有关使用 安装 Python 包的信息 conda ,请参阅 conda

请注意,%conda magic 命令在 Databricks Runtime 上不可用。 这些命令仅在 Databricks Runtime ML(最高版本为 Databricks Runtime ML 8.4)和用于基因组学的 Databricks Runtime 上可用。 Databricks 建议使用 pip 来安装库。 有关详细信息,请参阅了解 conda 和 pip

如果你必须 %pip%conda 在笔记本中使用和命令,请参阅 %pip

注意

%conda 一起使用时,不支持以下 conda 命令:

  • activate
  • create
  • init
  • run
  • env create
  • env remove

本节内容:

使用 %conda 安装库

%conda install matplotlib -c conda-forge

使用 %conda 卸载库

%conda uninstall matplotlib

保存并重用或共享环境

将笔记本从群集中分离时,环境不会保存。 若要保存环境以便以后重用或将其与他人共享,请按照以下步骤进行操作。

Databricks 建议仅在运行同一版本的 Databricks Runtime ML 或同一版本的用于基因组学的 Databricks Runtime 的群集之间共享环境。

  1. 将环境另存为 conda YAML 规范。

    %conda env export -f /dbfs/myenv.yml
    
  2. 使用 conda env update 将文件导入到另一个笔记本。

    %conda env update -f /dbfs/myenv.yml
    

列出笔记本的 Python 环境

若要显示与笔记本关联的 Python 环境,请使用 %conda list

%conda list

pipconda 命令之间的交互

若要避免冲突,请在使用 pipconda 安装 Python 包和库时遵循这些准则。

  • 使用 API 或使用 群集 UI 安装的库是使用安装的 。 如果已从 API 或群集 UI 安装了任何库,则在安装笔记本范围内的库时,应仅使用 %pip 命令。
  • 如果在群集上使用以笔记本为作用域的库,则在该群集上运行的初始化脚本可以使用 condapip 命令来安装库。 但是,如果初始化脚本包含 pip 命令,则仅使用笔记本中的 %pip 命令(而不是 %conda)。
  • 最好是专门使用 pip 命令,或专门使用 conda 命令。 如果必须使用 conda 安装一些包,并使用 pip 安装另一些包,请先运行 conda 命令,然后再运行 pip 命令。 有关详细信息,请参阅在 Conda 环境中使用 Pip

常见问题解答 (FAQ)

从群集 UI/API 安装的库如何与笔记本范围内的库交互?

从群集 UI 或 API 安装的库可用于群集上的所有笔记本。 这些库是使用 pip 安装的;因此,如果库是使用群集 UI 安装的,则在笔记本中只能使用 %pip 命令。

使用初始化脚本安装的库如何与以笔记本为作用域的库交互?

使用初始化脚本安装的库可用于群集上的所有笔记本。

如果在运行 Databricks Runtime ML 或用于基因组学的 Databricks Runtime 的群集上使用笔记本范围内的库,则群集上运行的初始化脚本可以使用 condapip 命令来安装库。 但是,如果初始化脚本包含 pip 命令,则仅使用笔记本中的 %pip 命令。

例如,此笔记本代码片段会生成一个脚本,该脚本将在所有群集节点上安装 fast.ai 包。

dbutils.fs.put("dbfs:/home/myScripts/fast.ai", "conda install -c pytorch -c fastai fastai -y", True)

能否在作业笔记本中使用 %pip%conda 命令?

是的。

是否可以在 R 或 Scala 笔记本中使用 %pip%conda 命令?

是的,可以在 Python magic 单元中使用。

能否使用 %sh pip%sh conda

Databricks 不建议使用 %sh pip,因为它与 %pip 用法不兼容。

能否使用 %conda 命令更新 R 包?

错误。

已知问题

  • 在 Databricks Runtime 7.0 ML 及更低版本和用于基因组学的 Databricks Runtime 7.0 及更低版本上,如果注册的 UDF 依赖于使用 %pip%conda 安装的 Python 包,则它不会在 %sql 单元格中工作。 请改用 Python 命令行界面中的 spark.sql
  • 在 Databricks Runtime 7.2 ML 及更低版本和用于基因组学的 Databricks Runtime 7.2 及更低版本上,使用 %conda 更新笔记本环境时,不会在 Python 工作进程上激活新环境。 如果 PySpark UDF 函数调用第三方函数(该函数使用在 Conda 环境中安装的资源),这可能会导致问题。
  • 使用 %conda env update 更新笔记本环境时,不保证包的安装顺序。 这可能会导致 horovod 包出现问题,在这种情况下,需要在 horovod 之前安装 tensorflowtorch,以便分别使用 horovod.tensorflowhorovod.torch。 如果发生这种情况,请卸载 horovod 包,并在确保安装依赖项后重新安装它。