データブリックス・ジャパン株式会社Notebook-scoped Python libraries | Databricks on AWS [2022/5/24時点]の翻訳です。
ノートブックスコープライブラリを用いることで、ノートブック固有のカスタムPython環境を作成、修正、保存、再利用、共有することが可能となります。ノートブックスコープライブラリをインストールすると、現在のノートブックとそのノートブックに関連づけられているジョブがそのライブラリにアクセスすることができます。同じクラスターにアタッチされている他のノートブックは影響を受けません。
ノートブックスコープライブラリはセッションを超えて永続化されません。セッションごとに、あるいは、クラスターからノートブックがデタッチされた際には、最初にノートブックスコープライブラリをインストールしなくてはなりません。
ノートブックスコープライブラリのインストール方法は2つあります。
- ノートブックで
%pipマジックコマンドを実行します。%pipコマンドはDatabricksランタイム7.1以降、Databricks機械学習ランタイム6.4以降でサポートされています。新たなワークロードに対してはこのアプローチを用いることをお勧めします。本書は、これらのマジックコマンドの使い方を説明します。 - Databricksランタイム10.5以下では、Databricksライブラリユーティリティを使うことができます。このライブラリユーティリティはDatabricksランタイムでのみサポートされており、Databricks機械学習ランタイムやDatabricks Runtime for Genomicsではサポートされていません。Library utility (dbutils.library)をご覧下さい。
クラスターにアタッチされているすべてのノートブックにライブラリをインストールするには、ワークスペースライブラリ、クラスターライブラリを使用します。
重要！
`dbutils.library.install`や`dbutils.library.installPyPI`はDatabricksランタイム11.0で削除されています。
要件
マジックコマンドを用いたノートブックライブラリは、Databricksランタイム7.1以降、Databricks機械学習ランタイム7.1以降、Databricks Runtime 7.1 for Genomics以降ではデフォルトで有効化されています。
Databricks Runtime 6.4 MLから7.0 ML、Databricks Runtime 6.4 for GenomicsからDatabricks Runtime 7.0 for Genomicsでは、設定を行うことでこの機能を使用することができます。Spark設定spark.databricks.conda.condaMagic.enabledをtrueに設定します。
Databricks Runtime 7.4 ML以下、あるいはDatabricks Runtime 7.4 for Genomics以下が動作しているハイコンカレンシークラスターにおいては、ノートブックスコープライブラリはテーブルアクセスコントロールやクレディンシャルパススルーと互換性がありません。代替案として、Databricksランタイムクラスター上でライブラリユーティリティ(dbutils.library)を使うか、クラスターをDatabricks Runtime 7.5 ML以降、あるいは、Databricks Runtime 7.5 for Genomics以降にアップグレードします。
Databricks Connectでノートブックスコープライブラリを使用するには、ライブラリユーティリティ(dbutils.library)を使用しなくてはなりません。
ドライバーノード
ノートブックスコープライブラリのインストールは、クラスタ上の全ワーカーノードにライブラリをインストールするため、ドライバーノードにおいて多くのトラフィックが発生する場合があります。
10以上のノードを持つクラスターを構成する際には、ドライバーノードが以下のスペックを満たすことをお勧めしています。
- 100CPUノードのクラスターの場合、
i3.8xlargeをお使いください - 10GPUノードのクラスターの場合、
p2.xlargeをお使いください
%pipを用いたノートブックスコープライブラリのインストール
重要！
- ノートブックの一番最初に
%pipを記述してください。%pipが実行された後に、ノートブックの内部状態がリセットされます。ノートブックでPythonメソッドあるいは変数を宣言した後に%pipを実行するとそれらは消去されてしまいます。 -
%pipを用いて(IPythonのような)コアのPythonパッケージをアップグレード、修正、アンインストールすると、いくつかの機能が期待した通りに動作しなくなる場合があります。例えば、IPython 7.21以降はDatabricks Runtime 8.1と互換性がありません。このような問題に直面した際、ノートブックをデタッチ、再アタッチするか、クラスターを再起動することで環境をリセットしてください。
%pipコマンドを用いたライブラリの管理
%pipコマンドは、pipコマンドと同じものであり、同様のAPIをサポートしています。以下のセクションでは、ご自身の環境を管理するためにどのように%pipコマンドを使用するのかのサンプルを説明します。pipによるPythonパッケージのインストールの詳細に関しては、pip install documentationと関連ページをご覧ください。
%pipによるライブラリのインストール
%pip install matplotlib
%pipによるwheelパッケージのインストール
%pip install /path/to/my_package.whl
%pipによるライブラリのアンインストール
注意
Databricksランタイムに含まれているライブラリ、クラスターライブラリとしてインストールされたライブラリをアンインストールすることはできません。Databricksランタイムあるいはクラスターにインストールされたライブラリと異なるバージョンをインストールした場合、Databricksランタイムのライブラリバージョンあるいはクラスターライブラリのバージョンに戻すために%pip uninstallを使用することができますが、Databricksランタイムに含まれるライブラリあるいはクラスターライブラリをアンインストールするために%pipコマンドを使用することはできません。
%pip uninstall -y matplotlib
-yオプションが必要です。
%pipによるバージョン管理システムからのライブラリのインストール
%pip install git+https://github.com/databricks/databricks-cli
バージョンやgitのサブディレクトリを指定するためにURLにパラメータを追加することができます。詳細とバージョン管理システムを用いたサンプルに関してはVCSのサポートをご覧ください。
%pipとDatabricksシークレットで管理される認証情報を用いたプライベートパッケージのインストール
pipでは、NexusやArtifactoryのようなプライベートバージョンコントロールシステムやプライベートパッケージリポジトリを含むプライベートソースから、basic認証を用いたパッケージのインストールをサポートしています。Databricks Secrets APIを通じてシークレット管理を行うことができ、認証トークンとパスワードを格納することができます。お使いのノートブックからシークレットにアクセスするにはDBUtils APIを使用します。マジックコマンドの中で$variablesを使えることに注意してください。
プライペートリポジトリからパッケージをインストールするには、%pip installに--index-urlオプションでリポジトリ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/
同様に、バージョンコントロールシステムからプライベートパッケージをインストールするために、マジックコマンドでシークレット管理を使用することができます。
token = dbutils.secrets.get(scope="scope", key="key")
%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>
%pipによるDBFSからのパッケージのインストール
DBFSに保存されたプライベートパッケージのインストールに%pipを使用することができます。
DBFSにファイルをアップロードすると、自動でファイル名を変更します。スペース、ピリオド、ハイフンをアンダースコアで置き換えます。pipはwheelファイルの名前でバージョンの中にピリオド、スペースやアンダースコアの代わりにハイフンを使用することを要求します(例：0.1.0)。%pipコマンドでパッケージをインストールするには、これらの要件を満足するようにファイル名を変更する必要があります。
%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl
requirementsファイルにライブラリを保存する
%pip freeze > /dbfs/requirements.txt
ファイルパスに含まれるすべてのサブディレクトリがすでに存在している必要があります。%pip freeze > /dbfs/<new-directory>/requirements.txtを実行した際、/dbfs/<new-directory>が存在しないとコマンドが失敗します。
ライブラリのインストールにrequirementsファイルを使用する
requirementsファイルには、pipを用いてインストールされるパッケージの一覧が含まれています。requirementsファイルの使い方のサンプルは以下のようになります。
%pip install -r /dbfs/requirements.txt
requirements.txtファイルの詳細に関しては、Requirements File Formatをご覧ください。
%condaコマンドによるライブラリの管理
重要！
%condaは非推奨となっており、Databricks機械学習ランタイム 8.4以降ではサポートされません。ノートブックスコープライブラリの管理には%pipを使用することをお勧めします。condaを用いてしかインストールできないPythonライブラリを必要とする場合、必要とするライブラリをプレインストールするためにconda-based dockerコンテナを使用することができます。
Anaconda, Inc.は2020年9月に利用規約をアップデートしています。新たな利用規約によりcommercial licenseが必要になる場合があります。こちらで詳細を確認してください。Anacondaチャネルの使用は、かれらの利用規約の管理下に置かれることになります。
この変更を受けて、Condaパッケージマネージャのデフォルトチャネル設定を削除しています。これは後方互換性のない変更です。
%condaコマンドを用いてパッケージをインストール、アップデートするには、-cを用いてチャネルを指定する必要があります。また、-cを用いてチャネルを指定するために、すべての%conda installと%sh conda installの使用箇所をアップデートしなくてはなりません。チャネルをしない場合、condaコマンドはPackagesNotFoundErrorで失敗します。
以降は原文を参照ください。
FAQ
クラスターUI/APIからインストールされたライブラリは、ノートブックスコープとどのようにやり取りを行いますか？
クラスターUI/APIからインストールされたライブラリはクラスター上の全てのノートブックで利用することができます。これらのライブラリはpipを用いてインストールされます。このため、ライブラリがクラスターUIを用いてインストールされている場合、ノートブックでは%pipコマンドのみを使用してください。
initスクリプトを用いてインストールされたライブラリは、ノートブックスコープとどのようにやり取りを行いますか？
initスクリプトを用いてインストールされたライブラリはクラスター上の全てのノートブックで利用することができます。
Databricks Runtime MLやDatabricks Runtime for Genomicsが稼働しているクラスターでノートブックスコープライブラリを使う場合、クラスターで実行されるinitスクリプトでは、ライブラリをインストールするためにcondaやpipコマンドを使用することができます。しかし、initスクリプトに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マジックセルの中で使用できます。
%sh pipや!pipを使うことはできますか？
%shや!は、ノートブックでシェルコマンドを実行します。前者はDatabricksの補助マジックコマンドであり、後者はIPythonの機能です。%sh pipや!pipは%pipの使用と互換性がないため、使用はお勧めしません。
注意
Databricksランタイム11.0以降では、%pip、%sh pip、!pipはすべてノートブックスコープPythonライブラリとしてライブラリをインストールします。
%condaコマンドを使用してRパッケージをアップデートすることはできますか？
いいえ
既知の問題
- Databricks Runtime 7.0 ML以前、Databricks Runtime 7.0 for Genomics以前で、登録されたUDFが
%pipや%condaを用いてインストールされたPythonパッケージに依存している場合、%sqlでは動作しません。代わりにPythonコマンドシェルでspark.sqlを使ってください。 - Databricks Runtime 7.2 ML以前、Databricks Runtime 7.2 for Genomics以前で、
%condaを用いてノートブック環境をアップデートした場合、新規環境はワーカーのPythonプロセスではアクティベートされません。これによって、PySpark UDFによるConda環境内にインストールされたリソースを使用するサードパーティ関数の呼び出しによって問題が発生することがあります。 - ノートブック環境をアップデートするために
%conda env updateを使用した際、パッケージのインストール順序は保証されません。これは、horovod.tensorflowやhorovod.torchを使用するために、horovodの前にtensorflowとtorchがインストールされている必要がある、horovodパッケージで問題を引き起こすことがあります。このような場合には、horovodパッケージをアンインストールし、依存ライブラリがインストールされていることを確認した後で再インストールしてください。 - Databricksランタイム10.3以前では、ノートブックスコープライブラリはバッチストリーミングジョブと互換性がありません。代わりに、クラスターライブラリかIPython kernelを使うことをお勧めします。