事前構築済みの Docker イメージ用の Python パッケージの機能拡張 (プレビュー)

2025-03-07

適用対象:Azure Machine Learning SDK v1 for Python

重要

この記事では、Azure Machine Learning SDK v1 の使用に関する情報を提供します。 SDK v1 は 2025 年 3 月 31 日の時点で非推奨となり、サポートは 2026 年 6 月 30 日に終了します。 SDK v1 は、その日付までインストールして使用できます。

2026 年 6 月 30 日より前に SDK v2 に移行することをお勧めします。 SDK v2 の詳細については、「 Azure Machine Learning Python SDK v2 と SDK v2 リファレンスとは」を参照してください。

モデル推論用に事前構築済みの Docker イメージには、一般的な機械学習フレームワーク向けのパッケージが含まれています。 Python パッケージは、次の 2 とおりの方法で、Docker イメージを再構築することなく追加できます。

動的インストール: Docker コンテナーのブート時に、requirements ファイルを使用して Python パッケージを自動的に復元する方法です。

迅速なプロトタイプ作成を目指すのであれば、この方法を検討してください。イメージが起動するときに、requirements.txt ファイルを使用してパッケージが復元されます。この方法ではイメージの起動に伴う処理が増えるため、デプロイが要求を処理できるようになるまでの待ち時間が長くなります。
プレインストール Python パッケージ: プレインストール Python パッケージを含むディレクトリを指定します。デプロイ中、使用するエントリスクリプト (score.py) のコンテナーにこのディレクトリがマウントされます。

この方法は、"運用環境のデプロイ" に使用します。パッケージを格納するディレクトリはイメージにマウントされるため、デプロイにパブリックインターネットアクセスがなくても使用できます。たとえば、セキュリティで保護された Azure Virtual Network にデプロイするケースが考えられます。

重要

Azure Machine Learning での事前構築済み Docker イメージ用 Python パッケージ拡張性の使用は、現在プレビュー段階です。プレビュー機能では、サポートやサービスレベルアグリーメントは保証されず、"現状有姿" で提供されます。詳細については、「Microsoft Azure プレビューの追加使用条件」を参照してください。

前提条件

Azure Machine Learning ワークスペース。ワークスペースの作成に関するチュートリアルについては、Azure Machine Learning の利用開始に関するページを参照してください。
Azure Machine Learning 環境の使い方を熟知していること。
Azure Machine Learning でモデルをデプロイする方法と場所を熟知していること。

動的インストール

この方法では、イメージの起動時に、requirements ファイルを使用して Python パッケージを自動的に復元します。

事前構築済みの Docker コンテナーイメージを requirements.txt を使用して拡張するには、これらの手順に従います。

score.py スクリプトと共に requirements.txt ファイルを作成します。
必要なパッケージをすべて requirements.txt ファイルに追加します。
AZUREML_EXTRA_REQUIREMENTS_TXT 環境変数を、ご使用の Azure Machine Learning 環境における requirements.txt ファイルの場所に設定します。

デプロイ後、スコアスクリプト用にパッケージが自動的に復元されます。

ヒント

プロトタイプの段階であっても、requirements.txt には、各パッケージのバージョンを固定することをお勧めします。たとえば、単に scipy や scipy > 1.2.3 とするのではなく、scipy == 1.2.3 を使用します。バージョンを厳密に固定しないと、scipy の新しいバージョンがリリースされた場合に、スコアリングスクリプトが支障をきたしたり、デプロイやスケーリング中にエラーが発生したりする可能性があります。

AZUREML_EXTRA_REQUIRMENTS_TXT 環境変数を設定する例を次に示します。

from azureml.core import Environment
from azureml.core.conda_dependencies import CondaDependencies 

myenv = Environment(name="my_azureml_env")
myenv.docker.enabled = True
myenv.docker.base_image = <MCR-path>
myenv.python.user_managed_dependencies = True

myenv.environment_variables = {
    "AZUREML_EXTRA_REQUIREMENTS_TXT": "requirements.txt"
}

次のダイアグラムは、動的インストールプロセスを視覚的に表したものです。

動的インストールプロセスのダイアグラム

プレインストール Python パッケージ

この方法では、指定したディレクトリがイメージにマウントされます。このディレクトリにある Python パッケージは、エントリスクリプト (score.py) から使用できるようになります。

事前構築済みの Docker コンテナーイメージをプレインストール Python パッケージを通じて拡張するには、これらの手順に従います。

重要

使用するイメージに応じて、Python 3.8 または 3.8 と互換性のあるパッケージを使用する必要があります。

virtualenv を使用して仮想環境を作成します。
依存関係をインストールします。たとえば、requirements.txt に依存関係のリストが指定されている場合、そのリストを pip install -r requirements.txt で使用してインストールできるほか、pip install で個々の依存関係をインストールすることができます。
AZUREML_EXTRA_PYTHON_LIB_PATH 環境変数を指定する際は、適切なサイトパッケージディレクトリを指定してください。サイトパッケージディレクトリは、実際の環境名と Python バージョンによって異なります。次のコードは、 myenv と Python 3.8 という名前の仮想環境のパスを設定する方法を示しています。
```
from azureml.core import Environment
from azureml.core.conda_dependencies import CondaDependencies 

myenv = Environment(name='my_azureml_env')
myenv.docker.enabled = True
myenv.docker.base_image = <MCR-path>
myenv.python.user_managed_dependencies = True

myenv.environment_variables = {
    "AZUREML_EXTRA_PYTHON_LIB_PATH": "myenv/lib/python3.8/site-packages"
}
```

次のダイアグラムは、プレインストールパッケージのプロセスを視覚的に表したものです。

プレインストールパッケージを使用したプロセスのダイアグラム

一般的な問題

マウントソリューションが正しく機能するのは、myenv サイトパッケージディレクトリにすべての依存関係が格納されている場合だけです。別の場所にインストールされている依存関係をローカル環境で使用した場合、それらをイメージ内で利用することはできません。

この問題の原因となり得るいくつかの事柄を次に示します。

virtualenv では、分離された環境が既定で作成されます。仮想環境をアクティブにした後は、グローバルな依存関係を使用できません。
PYTHONPATH 環境変数がグローバルな依存関係を指している場合、仮想環境に支障が生じる可能性があります。環境をアクティブにした後は、pip list と pip freeze を実行して、不要な依存関係が環境に存在しないことを確認してください。
"Conda 環境と virtualenv 環境は、干渉する場合があります"。 Conda 環境と virtualenv は同時に使用しないでください。

制限事項

Model.package()

Model.package() メソッドを使用すると、Docker イメージまたは Dockerfile ビルドコンテキストの形式でモデルパッケージを作成できます。事前構築済みの推論 Docker イメージで Model.package() を使用すると、非ルートユーザーをルートユーザーに変更する中間イメージビルドがトリガーされます。
Microsoft の Python パッケージ拡張ソリューションを使用することをお勧めします。他の依存関係 (apt パッケージなど) が必要な場合は、推論イメージを拡張する Dockerfile を独自に作成してください。

よく寄せられる質問

requirements.txt を使用した拡張方法では、ファイル名を必ず requirements.txt にしなければならないのですか?
```
myenv.environment_variables = {
    "AZUREML_EXTRA_REQUIREMENTS_TXT": "name of your pip requirements file goes here"
}
```

requirements.txt を使用した方法と "マウントを使用した方法" の違いを簡単に教えてください。

まずは、requirements.txt を使用した方法を試してください。何度か繰り返した後、適切なモデルデプロイに必要なパッケージ (とバージョン) についての確信が得られたら、"マウントによるソリューション" に切り替えます。

詳しい比較を次に示します。

比較項目	requirements.txt (動的インストール)	パッケージマウント
解決策	指定されたパッケージをコンテナーの起動時にインストールする `requirements.txt` を作成します。	すべての依存関係を含んだローカル Python 環境を作成します。そのディレクトリを実行時にコンテナーにマウントします。
パッケージのインストール	追加インストールは不要です (pip が既にインストールされている場合)	仮想環境または conda 環境のインストール。
仮想環境のセットアップ	必要な仮想環境について、特別なセットアップはありません。ユーザーは、`requirements.txt` を作成するために必要に応じて pip freeze を使用し、現在のローカルユーザー環境をプルできます。	クリーンな仮想環境をセットアップする場合は、現在のユーザーのローカル環境に応じて追加の手順が必要になることがあります。
デバッグ	依存関係が明確にリストされているので、サーバーのセットアップとデバッグは簡単です。	仮想環境がクリーンではない場合、サーバーのデバッグ時に問題が生じる可能性があります。たとえば、環境やユーザーコードからエラーが発生するようだとクリアとは言えません。
スケールアウト中の一貫性	外部の PyPi パッケージに依存しており、またその依存関係をユーザーが固定しているため、一貫性がありません。こうした外部ダウンロードは、不具合の原因になる場合があります。	ユーザー環境にのみ依存しているため、一貫性の問題はありません。

requirements.txt とマウントされた依存関係ディレクトリがコンテナーに見つかりません。なぜでしょうか?

ローカルで環境変数が正しく設定されていることを確認してください。次に、指定したパスのスペルが正しいこと、またそのパスが存在することを確認します。 inference config コンストラクターで、ソースディレクトリが正しく設定されているかどうかを確認します。
事前構築済みの推論 Docker イメージに含まれている Python パッケージの依存関係はオーバーライドできますか?

はい。推論イメージに既にインストールされているバージョン以外の Python パッケージを使用したい場合、拡張ソリューションでは、ユーザーによって指定されたバージョンが優先されます。 2 つのバージョン間に競合がないことを確認してください。

ベストプラクティス

登録済みモデルの読み込みに関するドキュメントを参照してください。モデルディレクトリを登録する際は、そのディレクトリにスコアリングスクリプトやマウントされた依存関係ディレクトリ、requirements.txt を含めないでください。
登録済みのモデルまたはローカルモデルを読み込む方法の詳細については、デプロイする場所と方法に関するページを参照してください。

バグの修正

2021-07-26

AZUREML_EXTRA_REQUIREMENTS_TXT と AZUREML_EXTRA_PYTHON_LIB_PATH は、スコアスクリプトのディレクトリに対して常に相対的になるようになりました。たとえば、requirements.txt とスコアスクリプトの両方が my_folder 内にある場合は、AZUREML_EXTRA_REQUIREMENTS_TXT を requirements.txt に設定する必要があります。 AZUREML_EXTRA_REQUIREMENTS_TXT は my_folder/requirements.txt に設定されなくなります。

次のステップ

モデルのデプロイについて詳しくは、モデルのデプロイ方法に関するページを参照してください。

事前構築済み Docker イメージのデプロイをトラブルシューティングする方法については、事前構築済み Docker イメージのデプロイをトラブルシューティングする方法に関するページを参照してください。