库实用工具 (dbutils.library)(旧版)

注意

Databricks Runtime 11.0 及更高版本中已移除 dbutils.library.installdbutils.library.installPyPI API。 大多数库实用工具命令已弃用。 大多数库实用工具在 Databricks Runtime ML 中不可用。 有关 dbutils.library.restartPython 的信息,请参阅在 Azure Databricks 上重启 Python 进程

本文档已过时,将来可能不会更新。 本内容中提及的产品、服务或技术不再受支持。

Databricks 强烈建议使用 %pip magic 命令安装笔记本范围的库。 请参阅作用域为笔记本的 Python 库

有关 Databricks 实用工具功能的完整文档,请参阅 Databricks 实用工具 (dbutils) 参考

命令installinstallPyPIlistrestartPythonupdateCondaEnv

可以通过库实用工具安装 Python 库并创建作用域为笔记本会话的环境。 这些库在驱动程序和执行程序上均可用,因此你可以在用户定义的函数中引用它们。 这样做可以实现以下操作:

  • 在笔记本自身中组织笔记本的库依赖项。
  • 具有不同库依赖项的笔记本用户共享群集而不受干扰。

分离笔记本会破坏此环境。 但是,你可以重新创建它,只需在笔记本中重新运行库 install API 命令即可。 请参阅 restartPython API,了解如何才能重置笔记本状态而不失去环境。

默认情况下,库实用工具处于启用状态。 因此,默认情况下会通过使用单独的 Python 可执行文件隔离每个笔记本的 Python 环境,该可执行文件在笔记本附加到群集并继承群集上的默认 Python 环境时创建。 通过 init script 安装到 Azure Databricks Python 环境中的库仍可用。 可以通过将 spark.databricks.libraryIsolation.enabled 设置为 false 来禁用此功能。

此 API 与通过 UI库 API 进行的群集范围的现有库安装兼容。 通过此 API 安装的库的优先级高于群集范围的库。

要列出可用命令,请运行 dbutils.library.help()

install(path: String): boolean -> Install the library within the current notebook session
installPyPI(pypiPackage: String, version: String = "", repo: String = "", extras: String = ""): boolean -> Install the PyPI library within the current notebook session
list: List -> List the isolated libraries added for the current notebook session via dbutils
restartPython: void -> Restart python process for the current notebook session
updateCondaEnv(envYmlContent: String): boolean -> Update the current notebook's Conda environment based on the specification (content of environment

install 命令 (dbutils.library.install)

给定库的路径,在当前笔记本会话中安装该库。 通过调用此命令安装的库仅适用于当前笔记本。

要显示此命令的相关帮助,请运行 dbutils.library.help("install")

此示例在笔记本中安装 .egg.whl 库。

重要

Databricks Runtime 11.0 及更高版本中删除了 dbutils.library.install

Databricks 建议将所有库安装命令放入笔记本的第一个单元,在该单元的末尾调用 restartPython。 在运行 restartPython 后会重置 Python 笔记本状态;笔记本会丢失所有状态,包括但不限于本地变量、导入的库和其他临时状态。 因此,建议在第一个笔记本单元中安装库并重置笔记本状态。

接受的库源是 dbfsabfssadlwasbs

dbutils.library.install("abfss:/path/to/your/library.egg")
dbutils.library.restartPython() # Removes Python state, but some libraries might not work without calling this command.
dbutils.library.install("abfss:/path/to/your/library.whl")
dbutils.library.restartPython() # Removes Python state, but some libraries might not work without calling this command.

注意

可以使用 %pip 直接安装自定义 wheel 文件。 在以下示例中,我们假设你已将库 wheel 文件上传到 DBFS:

%pip install /dbfs/path/to/your/library.whl

pip 不支持 Egg 文件,而 wheel 文件被认为是 Python 构建和二进制打包的标准。 但是,如果想要以与 %pip 兼容的方式使用 egg 文件,则可以使用以下解决方法:

# This step is only needed if no %pip commands have been run yet.
# It will trigger setting up the isolated notebook environment
%pip install <any-lib>  # This doesn't need to be a real library; for example "%pip install any-lib" would work
import sys
# Assuming the preceding step was completed, the following command
# adds the egg file to the current notebook environment
sys.path.append("/local/path/to/library.egg")

installPyPI 命令 (dbutils.library.installPyPI)

给定 Python Package Index (PyPI) 包,在当前笔记本会话中安装该包。 通过调用此命令安装的库在笔记本中是隔离的。

要显示此命令的相关帮助,请运行 dbutils.library.help("installPyPI")

此示例在笔记本中安装 PyPI 包。 versionrepoextras 是可选的。 使用 extras 参数可指定extras(额外要求)。

dbutils.library.installPyPI("pypipackage", version="version", repo="repo", extras="extras")
dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this command.

重要

Databricks Runtime 11.0 及更高版本中删除了 dbutils.library.installPyPI

versionextras 键不能是 PyPI 包字符串的一部分。 例如,dbutils.library.installPyPI("azureml-sdk[databricks]==1.19.0") 无效。 请使用 versionextras 参数指定版本和额外信息,如下所示:

dbutils.library.installPyPI("azureml-sdk", version="1.19.0", extras="databricks")
dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this command.

注意

dbutils.library.installPyPI 命令替换为 %pip 命令时,Python 解释器将自动重启。 可以按以下方式运行安装命令:

%pip install azureml-sdk[databricks]==1.19.0

此示例在一个笔记本中指定库要求,并通过在另一个笔记本中使用 %run 进行安装。 为此,请首先定义库以便在笔记本中安装。 此示例使用名为 InstallDependencies 的笔记本。

dbutils.library.installPyPI("torch")
dbutils.library.installPyPI("scikit-learn", version="1.19.1")
dbutils.library.installPyPI("azureml-sdk", extras="databricks")
dbutils.library.restartPython() # Removes Python state, but some libraries might not work without calling this command.

然后将它们安装在需要这些依赖项的笔记本中。

%run /path/to/InstallDependencies # Install the dependencies in the first cell.
import torch
from sklearn.linear_model import LinearRegression
import azureml
...

此示例在维护环境时重置 Python 笔记本状态。 此方法仅在 Python 笔记本中可用。 例如,你可以使用此方法重载 Azure Databricks 预安装的不同版本的库:

dbutils.library.installPyPI("numpy", version="1.15.4")
dbutils.library.restartPython()
# Make sure you start using the library in another cell.
import numpy

还可以使用此方法来安装需要在进程启动时加载的库(如 tensorflow):

dbutils.library.installPyPI("tensorflow")
dbutils.library.restartPython()
# Use the library in another cell.
import tensorflow

list 命令 (dbutils.library.list)

列出通过库实用工具为当前笔记本会话添加的独立库。 这不包括附加到群集的库。

要显示此命令的相关帮助,请运行 dbutils.library.help("list")

此示例列出笔记本中安装的库。

dbutils.library.list()

注意

使用 %pip 的此命令的等效项是:

%pip freeze

updateCondaEnv 命令 (dbutils.library.updateCondaEnv)

基于 environment.yml 的内容更新当前笔记本的 Conda 环境。 只有 Conda 上的 Databricks Runtime 支持此方法。

要显示此命令的相关帮助,请运行 dbutils.library.help("updateCondaEnv")

此示例基于所提供规范的内容更新当前笔记本的 Conda 环境。

dbutils.library.updateCondaEnv(
"""
channels:
  - anaconda
dependencies:
  - gensim=3.4
  - nltk=3.4
""")