笔记本范围内的 Python 库

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

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

Databricks 建议使用 %pip magic 命令安装笔记本范围的 Python 库。

可以在计划为作业的笔记本中使用 %pip。 如果需要在 Scala、SQL 或 R 笔记本中管理 Python 环境,请将 %python magic 命令与 %pip 结合使用。

使用笔记本范围的库安装时,可能会有比较多的流量进入驱动程序节点。 请参阅使用笔记本范围的库时驱动程序节点应有多大?

若要为附加到群集的所有笔记本安装库,请使用群集库。 请参阅群集库

注意

在 Databricks Runtime 10.4 LTS 及更低版本上,可以使用 (旧版) Azure Databricks 库实用工具。 库实用工具仅在 Databricks Runtime 上受支持,而在 Databricks Runtime ML 不受支持。 请参阅库实用工具 (dbutils.library)(旧版)

使用 %pip 命令管理库

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

重要

  • 从 Databricks Runtime 13.0 开始,%pip 命令不会自动重启 Python 进程。 如果安装新包或更新现有包,可能需要使用 dbutils.library.restartPython() 来查看新包。 请参阅在 Azure Databricks 上重启 Python 进程
  • 在 Databricks Runtime 12.2 LTS 及更低版本上,Databricks 建议将所有 %pip 命令放在笔记本的开头。 在修改环境的任何 %pip 命令后,会重置笔记本状态。 如果在笔记本中创建 Python 方法或变量,然后在后面的一个单元格中使用 %pip 命令,则这些方法或变量会丢失。
  • 使用 %pip 升级、修改或卸载核心 Python 包(如 IPython),可能会导致某些功能无法按预期正常工作。 如果遇到此类问题,可以通过拆离并重新附加笔记本或者通过重启群集来重置环境。

使用 %pip 安装库

%pip install matplotlib

使用 %pip 安装 Python 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 安装包

重要

任何工作区用户都可以修改存储在 DBFS 中的文件。 Azure Databricks 建议将文件存储在工作区或 Unity Catalog 卷上。

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

将文件上传到 DBFS 时,它将自动重命名该文件,并使用下划线替换空格、句点和连字符。 对于 Python wheel 文件,pip 要求文件名在版本中使用句点(例如 0.1.0)和连字符,而不能使用空格或下划线,因此这些文件名不会更改。

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

卷安装包%pip

重要

此功能目前以公共预览版提供。

借助 Databricks Runtime 13.3 LTS 及更高版本,可以使用 %pip 安装已保存到卷的专用包。

将文件上传到卷时,它将自动重命名该文件,并使用下划线替换空格、句点和连字符。 对于 Python wheel 文件,pip 要求文件名在版本中使用句点(例如 0.1.0)和连字符,而不能使用空格或下划线,因此这些文件名不会更改。

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

使用 %pip 安装存储为工作区文件的包

通过 Databricks Runtime 11.3 LTS 及更高版本,可以使用 %pip 安装已保存为工作区文件的专用包。

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

在要求文件中保存库

%pip freeze > /Workspace/shared/prod_requirements.txt

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

使用要求文件安装库

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

%pip install -r /Workspace/shared/prod_requirements.txt

有关 requirements.txt 文件的详细信息,请参阅要求文件格式

使用笔记本范围的库时驱动程序节点应有多大?

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

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

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

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

能否使用 %sh pip!pippip? 有何不同?

%sh! 在笔记本中执行 shell 命令;前者是 Databricks 辅助 magic 命令,而后者是 IPython 的一项功能。 pip 是启用 automagic%pip 的简写,这是 Azure Databricks Python 笔记本中的默认设置。

在 Databricks Runtime 11.3 LTS 及更高版本上,%pip%sh pip!pip 都将库安装为笔记本范围的 Python 库。 在 Databricks Runtime 10.4 LTS 及更低版本中,Databricks 建议仅使用 %pippip 来安装笔记本范围的库。 %sh pip!pip 的行为在 Databricks Runtime 10.4 LTS 及更低版本中不一致。

已知问题

  • 在 Databricks Runtime 9.1 LTS 上,笔记本范围的库与批量流式处理作业不兼容。 Databricks 建议改用群集库IPython 内核