DatabricksのノートブックスコープPythonライブラリ

[Notebook\-scoped Python libraries \| Databricks on AWS](https://docs.databricks.com/libraries/notebooks-python-libraries.html) [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\)](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-library)をご覧下さい。

クラスターにアタッチされているすべてのノートブックにライブラリをインストールするには、[ワークスペースライブラリ](https://qiita.com/taka_yayoi/items/b1668be2ebb6a7841bd0)、[クラスターライブラリ](https://qiita.com/taka_yayoi/items/9407356caadea3dfb47c)を使用します。

:::note warn
**重要！**
[\`dbutils\.library\.install\`](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-library-install)や[\`dbutils\.library\.installPyPI\`](https://docs.databricks.com/dev-tools/databricks-utils.html#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設定](https://qiita.com/taka_yayoi/items/8d951b660cd87c6c5f18#spark%E3%81%AE%E8%A8%AD%E5%AE%9A)`spark.databricks.conda.condaMagic.enabled`を`true`に設定します。

Databricks Runtime 7.4 ML以下、あるいはDatabricks Runtime 7.4 for Genomics以下が動作しているハイコンカレンシークラスターにおいては、ノートブックスコープライブラリは[テーブルアクセスコントロール](https://docs.databricks.com/security/access-control/table-acls/index.html)や[クレディンシャルパススルー](https://docs.databricks.com/security/credential-passthrough/index.html)と互換性がありません。代替案として、Databricksランタイムクラスター上で[ライブラリユーティリティ\(dbutils\.library\)](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-library)を使うか、クラスターをDatabricks Runtime 7.5 ML以降、あるいは、Databricks Runtime 7.5 for Genomics以降にアップグレードします。

[Databricks Connect](https://qiita.com/taka_yayoi/items/a9781c0a871a5a4fcf2e)でノートブックスコープライブラリを使用するには、[ライブラリユーティリティ\(dbutils\.library\)](https://docs.databricks.com/dev-tools/databricks-utils.html#dbutils-library)を使用しなくてはなりません。


## ドライバーノード

ノートブックスコープライブラリのインストールは、クラスタ上の全ワーカーノードにライブラリをインストールするため、ドライバーノードにおいて多くのトラフィックが発生する場合があります。

10以上のノードを持つクラスターを構成する際には、ドライバーノードが以下のスペックを満たすことをお勧めしています。

- 100CPUノードのクラスターの場合、`i3.8xlarge`をお使いください
- 10GPUノードのクラスターの場合、`p2.xlarge`をお使いください

# `%pip`を用いたノートブックスコープライブラリのインストール

:::note warn
**重要！**
- ノートブックの一番最初に`%pip`を記述してください。`%pip`が実行された後に、ノートブックの内部状態がリセットされます。ノートブックでPythonメソッドあるいは変数を宣言した後に`%pip`を実行するとそれらは消去されてしまいます。
- `%pip`を用いて(IPythonのような)コアのPythonパッケージをアップグレード、修正、アンインストールすると、いくつかの機能が期待した通りに動作しなくなる場合があります。例えば、IPython 7.21以降はDatabricks Runtime 8.1と互換性がありません。このような問題に直面した際、ノートブックをデタッチ、再アタッチするか、クラスターを再起動することで環境をリセットしてください。
:::

# `%pip`コマンドを用いたライブラリの管理

`%pip`コマンドは、[pip](https://pip.pypa.io/en/stable/user_guide/)コマンドと同じものであり、同様のAPIをサポートしています。以下のセクションでは、ご自身の環境を管理するためにどのように`%pip`コマンドを使用するのかのサンプルを説明します。`pip`によるPythonパッケージのインストールの詳細に関しては、[pip install documentation](https://pip.pypa.io/en/stable/reference/pip_install/)と関連ページをご覧ください。

## `%pip`によるライブラリのインストール

```py:Python
%pip install matplotlib
```

## `%pip`によるwheelパッケージのインストール

```py:Python
%pip install /path/to/my_package.whl
```

## `%pip`によるライブラリのアンインストール

:::note info
**注意**
[Databricksランタイム](https://docs.databricks.com/runtime/dbr.html)に含まれているライブラリ、[クラスターライブラリ](https://qiita.com/taka_yayoi/items/9407356caadea3dfb47c)としてインストールされたライブラリをアンインストールすることはできません。Databricksランタイムあるいはクラスターにインストールされたライブラリと異なるバージョンをインストールした場合、Databricksランタイムのライブラリバージョンあるいはクラスターライブラリのバージョンに戻すために`%pip uninstall`を使用することができますが、Databricksランタイムに含まれるライブラリあるいはクラスターライブラリをアンインストールするために`%pip`コマンドを使用することはできません。
:::

```py:Python
%pip uninstall -y matplotlib
```

`-y`オプションが必要です。

## `%pip`によるバージョン管理システムからのライブラリのインストール

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

バージョンやgitのサブディレクトリを指定するためにURLにパラメータを追加することができます。詳細とバージョン管理システムを用いたサンプルに関しては[VCSのサポート](https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support)をご覧ください。

## `%pip`とDatabricksシークレットで管理される認証情報を用いたプライベートパッケージのインストール

pipでは、[Nexus](https://www.sonatype.com/nexus/repository-pro)や[Artifactory](https://jfrog.com/artifactory/)のようなプライベートバージョンコントロールシステムやプライベートパッケージリポジトリを含むプライベートソースから、basic認証を用いたパッケージのインストールをサポートしています。Databricks Secrets APIを通じてシークレット管理を行うことができ、認証トークンとパスワードを格納することができます。お使いのノートブックからシークレットにアクセスするには[DBUtils API](https://docs.databricks.com/dev-tools/databricks-connect.html#enable-dbutilssecretsget)を使用します。マジックコマンドの中で`$variables`を使えることに注意してください。

プライペートリポジトリからパッケージをインストールするには、`%pip install`に`--index-url`オプションでリポジトリURLを指定するか、`~/.pip/pip.conf`の`pip`設定ファイルに追加します。

```py:Python
token = dbutils.secrets.get(scope="scope", key="key")
```

```bash:Bash
%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/
```

同様に、バージョンコントロールシステムからプライベートパッケージをインストールするために、マジックコマンドでシークレット管理を使用することができます。

```py:Python
token = dbutils.secrets.get(scope="scope", key="key")
```

```bash:Bash
%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>
```

## `%pip`によるDBFSからのパッケージのインストール

DBFSに保存されたプライベートパッケージのインストールに`%pip`を使用することができます。

DBFSにファイルをアップロードすると、自動でファイル名を変更します。スペース、ピリオド、ハイフンをアンダースコアで置き換えます。`pip`はwheelファイルの名前でバージョンの中にピリオド、スペースやアンダースコアの代わりにハイフンを使用することを要求します(例：0.1.0)。`%pip`コマンドでパッケージをインストールするには、これらの要件を満足するように[ファイル名を変更](https://qiita.com/taka_yayoi/items/3717623187859809515d#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0%E3%83%A6%E3%83%BC%E3%83%86%E3%82%A3%E3%83%AA%E3%83%86%E3%82%A3dbutilsfs)する必要があります。

```py:Python
%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl
```

## requirementsファイルにライブラリを保存する

```py:Python
%pip freeze > /dbfs/requirements.txt
```

ファイルパスに含まれるすべてのサブディレクトリがすでに存在している必要があります。`%pip freeze > /dbfs/<new-directory>/requirements.txt`を実行した際、`/dbfs/<new-directory>`が存在しないとコマンドが失敗します。

## ライブラリのインストールにrequirementsファイルを使用する

[requirementsファイル](https://pip.pypa.io/en/stable/user_guide/#requirements-files)には、`pip`を用いてインストールされるパッケージの一覧が含まれています。requirementsファイルの使い方のサンプルは以下のようになります。

```py:Python
%pip install -r /dbfs/requirements.txt
```

`requirements.txt`ファイルの詳細に関しては、[Requirements File Format](https://pip.pypa.io/en/stable/reference/pip_install/#requirements-file-format)をご覧ください。

# `%conda`コマンドによるライブラリの管理

:::note warn
**重要！**
`%conda`は非推奨となっており、Databricks機械学習ランタイム 8.4以降ではサポートされません。ノートブックスコープライブラリの管理には`%pip`を使用することをお勧めします。condaを用いてしかインストールできないPythonライブラリを必要とする場合、必要とするライブラリをプレインストールするために[conda\-based](https://github.com/databricks/containers/tree/master/ubuntu/python-conda) dockerコンテナを使用することができます。

Anaconda, Inc.は2020年9月に[利用規約](https://www.anaconda.com/terms-of-service)をアップデートしています。新たな利用規約によりcommercial licenseが必要になる場合があります。[こちら](https://www.anaconda.com/blog/anaconda-commercial-edition-faq)で詳細を確認してください。Anacondaチャネルの使用は、かれらの[利用規約](https://www.anaconda.com/terms-of-service)の管理下に置かれることになります。

この変更を受けて、Condaパッケージマネージャのデフォルトチャネル設定を削除しています。これは後方互換性のない変更です。

`%conda`コマンドを用いてパッケージをインストール、アップデートするには、`-c`を用いてチャネルを指定する必要があります。また、`-c`を用いてチャネルを指定するために、すべての`%conda install`と`%sh conda install`の使用箇所をアップデートしなくてはなりません。チャネルをしない場合、condaコマンドは`PackagesNotFoundError`で失敗します。
:::

以降は[原文](https://docs.databricks.com/libraries/notebooks-python-libraries.html#manage-libraries-with-conda-commands)を参照ください。

# 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パッケージをインストールするスクリプトを生成します。

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

## ジョブノートブックで`%pip`や`%conda`コマンドを使用することはできますか？

はい

## RやScalaノートブックで`%pip`や`%conda`コマンドを使用することはできますか？

はい、[Pythonマジックセル](https://qiita.com/taka_yayoi/items/dfb53f63aed2fbd344fc#%E3%83%9F%E3%83%83%E3%82%AF%E3%82%B9%E8%A8%80%E8%AA%9E)の中で使用できます。

## `%sh pip`や`!pip`を使うことはできますか？

`%sh`や`!`は、ノートブックでシェルコマンドを実行します。前者はDatabricksの[補助マジックコマンド](https://qiita.com/taka_yayoi/items/dfb53f63aed2fbd344fc#%E3%83%9F%E3%83%83%E3%82%AF%E3%82%B9%E8%A8%80%E8%AA%9E)であり、後者はIPythonの機能です。`%sh pip`や`!pip`は`%pip`の使用と互換性がないため、使用はお勧めしません。

:::note info
**注意**
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以前では、ノートブックスコープライブラリはバッチストリーミングジョブと互換性がありません。代わりに、[クラスターライブラリ](https://qiita.com/taka_yayoi/items/9407356caadea3dfb47c)か[IPython kernel](https://docs.databricks.com/notebooks/ipython-kernel.html)を使うことをお勧めします。

### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)