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を使うことをお勧めします。