Snowflakeモデルレジストリ¶
注釈
このトピックで説明するモデルレジストリAPIは、パッケージバージョン1.5.0で一般的に利用可能です。
モデルをトレーニングした後、Snowflakeでモデルを運用して推論を実行するには、Snowflake Model Registryにモデルをログに記録することから始めます。Model Registryを使用すると、オリジンやタイプに関係なく、Snowflakeでモデルとそのメタデータを安全に管理し、推論を簡単に実行することができます。Snowflake Model Registryの主な利点と機能は次のとおりです。
モデル・バージョン、モデル・メトリクス、その他のモデル・メタデータを保存・管理する機能
Python、 SQL、または REST API エンドポイントを使用してモデルを提供し、分散推論をスケールで実行する能力
柔軟なガバナンスオプションでモデルのライフサイクルを管理し、開発環境から生産環境までモデルを扱う能力
Snowflakeを使用したモデルのパフォーマンスとドリフトのモニタリング機能 ML Observability
ロールベースのアクセス制御でモデルアクセスをセキュアに管理する機能
モデルレジストリは、機械学習モデルをSnowflakeのファーストクラスオブジェクトとして格納します。
モデルをログに記録した後、そのメソッド(関数やストアドプロシージャに相当)を呼び出すことで、 推論、Snowflake 仮想ウェアハウス、Snowpark コンテナーサービス GPU-ベースの推論 などのモデル操作を実行することができます。
Snowflake Model Registry には、 組み込みタイプ があり、 scikit-learn、 xgboost、 LightGBM、 PyTorch、 TensorFlow、 Hugging Face パイプライン、および MLFlow pyfunc モデル を含む、最も一般的なモデルタイプをサポートしています。Modeling Registryはまた、独自の学習済みモデルやカスタム処理コードをサポートするのに十分な柔軟性とパワーを備えています。
Tip
これらのモデルタイプとエンドツーエンドのワークフローの例は、 例およびクイックスタート でご覧ください。
Snowflake Model Registry Python API の主なクラスです。
snowflake.ml.registry.Registry: スキーマ内のモデルを管理します。
snowflake.ml.model.Model: モデルを表します。
snowflake.ml.model.ModelVersion: モデルのバージョンを表します。
このトピックでは、 snowflake-ml-python
ライブラリを使用して Python でレジストリ演算子を実行する方法について説明します。また、多くのレジストリ演算子を SQL で実行することもできます。 Model Registry SQL を参照してください。
必要な権限¶
モデルを作成するには、モデルを作成するスキーマを所有するか、そのスキーマに対する CREATE MODEL
権限を持っている必要があります。モデルを使用するには、そのモデルを所有しているか、そのモデルに対する USAGE 権限を持っている必要があります。USAGE権限により、付与対象者はモデルの内部を見ることなく推論を行うことができます。スキーマに存在するすべてのモデルへのアクセスをユーザーに与えるには、 GRANT USAGE ON ALL MODELS IN SCHEMA <schema> TO ROLE <role>;
を使ってください。 また、スキーマに将来作成されるモデルへのアクセスをユーザーに自動的に与えるには、 GRANT USAGE ON FUTURE MODELS IN SCHEMA <スキーマ> TO ROLE <ロール>;
を使ってください。
ユーザーのロールがモデルに USAGE、 Snowsightモデルのレジストリページ に表示されます。Snowflake での権限の仕組みの詳細については、 アクセス制御権限 を参照してください。
注釈
デフォルトでは、モデルは現在複製をサポートしていません。この機能は、 BCR バンドル 2024_08 の一部で、モデルの複製が必要な場合に有効にすることができます。この機能はまもなくデフォルトで有効になります。
現在の制限¶
以下の制限は、モデルおよびモデルのバージョンに適用されます。
モデル |
|
---|---|
モデルのバージョン |
|
Snowflakeモデルレジストリを開く¶
モデルはファーストクラスのSnowflakeオブジェクトであり、他のSnowflakeオブジェクトと一緒にデータベースやスキーマ内に編成することができます。Snowflakeモデルレジストリは、スキーマ内のモデルを管理するためのPythonクラスを提供します。したがって、どのSnowflakeスキーマもレジストリとして使用できます。この目的のために、スキーマを初期化したり準備したりする必要はありません。Snowflakeは、 ML.REGISTRY のように、この目的のために1つ以上の専用スキーマを作成することを推奨しています。スキーマは、 CREATE SCHEMA を使用して作成できます。
レジストリのモデルを作成または変更する前に、レジストリを開く必要があります。レジストリを開くと、そのレジストリへの参照が返され、それを使用して新しいモデルを追加したり、既存のモデルへの参照を取得したりすることができます。
from snowflake.ml.registry import Registry
reg = Registry(session=sp_session, database_name="ML", schema_name="REGISTRY")
モデルおよびバージョンの登録¶
レジストリへのモデルの追加は、モデルの ログ と呼ばれます。レジストリの log_model
メソッドを呼び出してモデルをログします。Pythonオブジェクトであるモデルをシリアル化し、そこからSnowflakeモデルオブジェクトを作成します。説明などのメタデータを log_model
呼び出しで指定されたモデルに追加します。
各モデルは無制限にバージョンを持つことができます。モデルの追加バージョンをログするには、同じ model_name
で異なる version_name
を指定して log_model
を再度呼び出します。
タグがレジストリに追加されている場合は、モデルにタグを追加することはできません。タグはモデルの属性であり、 log_model
は特定のモデルのバージョンを追加し、最初のバージョン追加時にのみモデルを作成するからです。モデルの最初のバージョンをログした後に、 モデルのタグを更新する ことができます。
次の例では、 clf
は、「classifier,」の略で、コード内で既に作成されたPythonのモデルオブジェクトです。ここに示すように、登録時にコメントを追加することができます。名前とバージョンの組み合わせは、スキーマ内で一意にする必要があります。 conda_dependencies
リストを指定します。指定したパッケージはモデルと合わせて展開されます。
from snowflake.ml.model import type_hints
mv = reg.log_model(clf,
model_name="my_model",
version_name="v1",
conda_dependencies=["scikit-learn"],
comment="My awesome ML model",
metrics={"score": 96},
sample_input_data=train_features,
task=type_hints.Task.TABULAR_BINARY_CLASSIFICATION)
ここで log_model
の引数を説明します。
必要な引数
引数 |
説明 |
---|---|
|
サポートされているモデル型のPythonモデルオブジェクト。シリアル化可能(「ピクル化可能」)である必要があります。 |
|
モデルの名前。レジストリでモデルを識別するために |
注釈
モデル名とバージョンの組み合わせは、スキーマ内で一意にする必要があります。
オプションの引数
引数 |
説明 |
---|---|
|
モデルのバージョンを指定する文字列。レジストリでモデルを識別するために |
|
モデルをロードまたは展開する際にインポートするコードディレクトリへのパスのリスト。 |
|
コメント、たとえばモデルの説明など。 |
|
モデルに必要なCondaパッケージのリスト。この引数は Conda形式、つまり |
|
モデルと一緒にピクルする外部モジュールのリスト。scikit-learn、Snowpark ML、 PyTorch、 TorchScript、およびカスタムモデルのサポート。 |
|
モデルバージョンにリンクされたメトリクスを含むディクショナリ。 |
|
モデル作成のオプションを含むディクショナリ。次のオプションはすべてのモデル型で利用できます:
個々のモデル型によっては、追加オプションをサポートしている場合もあります。 組み込みモデルタイプの使用 をご参照ください。 |
|
モデルで必要な PyPI パッケージのパッケージ仕様のリスト。Snowpark Container Servicesで実行されるモデルでのみサポートされます。 |
|
モデルを実行する Python のバージョン。デフォルトは |
|
サンプルの入力データを含む DataFrame 。この DataFrame から、モデルが必要とする特徴量名とその型が抽出されます。Snowpark ML と MLFlow 以外のモデルおよびHugging Faceパイプラインでは、この引数か |
|
メソッド署名を、ターゲットメソッド名から入力と出力の署名へのマッピングとしてモデル化します。Snowpark ML と MLFlow 以外のモデルおよびHugging Faceパイプラインでは、この引数か |
|
モデルが解決しようとする問題を定義するタスク。未指定の場合、モデルクラスからモデルタスクを推測するベストエフォートがなされるか、 |
log_model
は、レジストリに追加されたモデルのバージョンを表す snowflake.ml.model.ModelVersion
オブジェクトを返します。
一度登録されると、モデル自体を変更することはできません(メタデータを変更することはできます)。モデルとそのすべてのバージョンを削除するには、レジストリの delete_model メソッドを使用します。
モデルアーティファクトの操作¶
モデルがログに記録された後、その成果物(シリアライズされたPythonオブジェクトや、マニフェストなどの様々なメタデータファイルを含む、モデルをバックアップするファイル)は内部ステージで利用可能になります。アーティファクトを変更することはできませんが、所有するモデルのアーティファクトを表示またはダウンロードすることはできます。
注釈
モデルのUSAGE権限を持っていても、そのアーティファクトにアクセスすることはできません。
ステージからモデルアーティファクトにアクセスするには、例えば GET コマンド や、Snowpark Pythonの同等のコマンド FileOperation.get を使用します。
しかし、通常のステージパス構文を使ってモデルのアーティファクトを扱うことはできません。代わりに、 snow://
URL、Snowflakeのオブジェクトの位置を指定する、より一般的な方法を使用します。例えば、モデル内のバージョンは、 snow://model/<model_name>/versions/<version_name>/
という形式の URL で指定することができます。
モデルの名前と必要なバージョンを知っていれば、 LIST コマンド を使って、次のようにモデルのアーティファクトを表示することができます。
LIST 'snow://model/my_model/versions/V3/';
出力は似ています。
name size md5 last_modified
versions/V3/MANIFEST.yml 30639 2f6186fb8f7d06e737a4dfcdab8b1350 Thu, 18 Jan 2024 09:24:37 GMT
versions/V3/functions/apply.py 2249 e9df6db11894026ee137589a9b92c95d Thu, 18 Jan 2024 09:24:37 GMT
versions/V3/functions/predict.py 2251 132699b4be39cc0863c6575b18127f26 Thu, 18 Jan 2024 09:24:37 GMT
versions/V3/model.zip 721663 e92814d653cecf576f97befd6836a3c6 Thu, 18 Jan 2024 09:24:37 GMT
versions/V3/model/env/conda.yml 332 1574be90b7673a8439711471d58ec746 Thu, 18 Jan 2024 09:24:37 GMT
versions/V3/model/model.yaml 25718 33e3d9007f749bb2e98f19af2a57a80b Thu, 18 Jan 2024 09:24:37 GMT
これらのアーティファクトを取得するには、 SQL GET コマンドを使用します。
GET 'snow://model/model_my_model/versions/V3/MANIFEST.yml'
あるいはSnowpark Pythonと同等です。
session.file.get('snow://model/my_model/versions/V3/MANIFEST.yml', 'model_artifacts')
注釈
モデルのアーティファクトの名前と構成は、モデルのタイプによって異なり、変更されることがあります。上記のアーティファクトリストの例は、あくまで説明用であり、権威あるものではありません。
モデルの削除¶
レジストリの delete_model
メソッドを使用して、モデルとそのすべてのバージョンを削除します。
reg.delete_model("mymodel")
Tip
DROP MODEL を使用して、SQL のモデルを削除することもできます。
レジストリからのモデルの取得¶
各モデルの情報を得るには、 show_models
メソッドを使用します。
model_df = reg.show_models()
Tip
SQL で、 SHOW MODELS を使ってモデルのリストを取得します。
show_models
の結果は、pandas DataFrame です。利用可能なカラムはこちらです。
列 |
説明 |
---|---|
|
モデルが作成された日時。 |
|
モデルの名前。 |
|
モデルが格納されているデータベース。 |
|
モデルが格納されているスキーマ。 |
|
モデルを所有するロールの名前。 |
|
モデルのコメント。 |
|
モデルのバージョンをリストした JSON 配列。 |
|
バージョンを指定せずにモデルを参照する場合に使用されるモデルのバージョン。 |
代わりにレジストリにあるモデルのリストを、それぞれ Model
インスタンスとして取得するには models
メソッドを使用します。
model_list = reg.models()
レジストリから特定のモデルへの参照を名前で取得するには、レジストリの get_model
メソッドを使用します。
m = reg.get_model("MyModel")
注釈
Model
インスタンスは、ログされた元のPythonモデルオブジェクトのコピーではなく、レジストリ内の基になるモデルオブジェクトへの参照です。
models
メソッドで返されたリストのモデル、または get_model
を使用して取得したモデルへの参照があると、 そのメタデータ と そのバージョン を操作することができます。
モデルのメタデータの表示および更新¶
レジストリ内のモデルのメタデータ属性(名前、コメント、タグ、メトリックなど)を表示したり、更新したりすることができます。
コメントの取得および更新¶
モデルのコメントを取得したり、更新したりするには、モデルの comment
属性を使用します。
print(m.comment)
m.comment = "A better description than the one I provided originally"
注釈
description
属性は、 comment
の同義語です。先のコードもこのように書くことができます。
print(m.description)
m.description = "A better description than the one I provided originally"
Tip
ALTER MODEL を使って、 SQL にモデルのコメントを設定することもできます。
モデル名の変更¶
モデルの名前を変更したり移動したりするには、 rename
メソッドを使用します。モデルを別のデータベースまたはスキーマに移動するには、新しい名前として完全修飾名を指定します。
m.rename("MY_MODEL_TOO")
Tip
ALTER MODEL を使用して、SQL のモデル名を変更することもできます。
モデルバージョンの操作¶
モデルは無制限にバージョンを持つことができ、それぞれが文字列で識別されます。希望するバージョンの命名規則を使用することができます。モデルをログすることは、実際にはモデルの 特定のバージョン をログすることです。モデルの追加バージョンをログするには、同じ model_name
で異なる version_name
を指定して log_model
を再度呼び出します。
Tip
SQL で、モデルのバージョンを見るには SHOW VERSIONS IN MODEL を使います。
モデルのバージョンは、 snowflake.ml.model.ModelVersion
クラスのインスタンスで表されます。
モデルの全バージョンのリストを取得するには、モデルオブジェクトの versions
メソッドを呼び出します。結果は ModelVersion
インスタンスのリストです。
version_list = m.versions()
代わりに DataFrame として各モデルの情報を取得するには、モデルの show_versions
メソッドを呼び出します。
version_df = m.show_versions()
できあがった DataFrame には以下の列が含まれます。
列 |
説明 |
---|---|
|
モデルバージョンが作成された日時 |
|
バージョンの名前。 |
|
バージョンが格納されているデータベース。 |
|
バージョンが格納されているスキーマ。 |
|
このバージョンが属するモデルの名前。 |
|
このバージョンがモデルのデフォルトバージョンであるかどうかを示すブール値。 |
|
このバージョンで使用可能な関数名の JSON 配列。 |
|
JSON メタデータをキーと値のペアとして含むオブジェクト(メタデータが指定されていない場合は |
|
モデル定義マニフェストの |
モデルバージョンの削除¶
モデルの delete_version
メソッドを使用してモデルのバージョンを削除できます。
m.delete_version("rc1")
Tip
ALTER MODEL ... DROP VERSION を使用して、 SQL のモデルバージョンを削除することもできます。
デフォルトバージョン¶
モデルのバージョンをデフォルトモデルとして指定することができます。モデルの default
属性を取得または設定して、現在のデフォルトバージョンを(ModelVersion
オブジェクトとして)取得するか、変更(文字列を使用して)します。
default_version = m.default
m.default = "v2"
Tip
SQL では、 ALTER MODEL を使ってデフォルトのバージョンを設定します。
モデルバージョンのエイリアス¶
SQL ALTER MODEL コマンドを使って、モデルのバージョンにエイリアスを割り当てることができます。PythonやSQLでモデルのバージョンへの参照を取得するときなど、バージョン名が必要な場合はどこでもエイリアスを使うことができます。与えられたエイリアスは、一度に1つのモデル・バージョンにのみ割り当てることができます。
自分で作成したエイリアスに加えて、以下のシステムエイリアスはすべてのモデルで利用可能です。
DEFAULT
は、モデルのデフォルトバージョンを指します。FIRST
は、作成時間が最も古いモデルバージョンを指します。LAST
は、作成時間が最新のモデルバージョンを指します。
作成したエイリアス名は、システムエイリアスを含め、モデル内の既存のバージョン名やエイリアスと同じにできません。
モデルバージョンへの参照の取得¶
モデルの特定バージョンへの参照を ModelVersion
インスタンスとして取得するには、モデルの version
メソッドを使用します。モデルのデフォルトバージョンを取得するには、モデルの default
属性を使用します。
m = reg.get_model("MyModel")
mv = m.version("v1")
mv = m.default
モデルの特定バージョン(この例の変数 mv
など)への参照を取得すると、そのコメントやメトリクスを取得または更新し、以下のセクションで示すようにモデルのメソッド(または関数)を呼び出すことができます。
コメントの取得および更新¶
モデルと同様に、モデルのバージョンはコメントを持つことができ、モデルのバージョンの comment
または description
属性を介してアクセスし、設定することができます。
print(mv.comment)
print(mv.description)
mv.comment = "A model version comment"
mv.description = "Same as setting the comment"
Tip
ALTER MODEL ... MODIFY VERSION を使って、SQL のモデルバージョンのコメントを変更することもできます。
メトリクスの取得および更新¶
メトリクスは、予測精度やその他のモデルバージョンの特性を追跡するために使用されるキーと値のペアです。モデルバージョンの作成時にメトリクスを設定することも、 set_metric
メソッドを使用して設定することもできます。メトリクス値は、数値、文字列、リスト、ディクショナリなど、 JSON にシリアル化できる任意のPythonオブジェクトにすることができます。タグとは異なり、メトリクス名と可能な値を事前に定義する必要はありません。
テスト精度のメトリクスは、sklearnの accuracy_score
を使用して生成される場合があります。
from sklearn import metrics
test_accuracy = metrics.accuracy_score(test_labels, prediction)
混同行列はsklearnを使用して同様に生成できます。
test_confusion_matrix = metrics.confusion_matrix(test_labels, prediction)
そして、これらの値をメトリクスとして設定することができます:
# scalar metric
mv.set_metric("test_accuracy", test_accuracy)
# hierarchical (dictionary) metric
mv.set_metric("evaluation_info", {"dataset_used": "my_dataset", "accuracy": test_accuracy, "f1_score": f1_score})
# multivalent (matrix) metric
mv.set_metric("confusion_matrix", test_confusion_matrix)
モデルバージョンのメトリクスをPythonディクショナリとして取得するには、 show_metrics
を使用します。
metrics = mv.show_metrics()
メトリクスを削除するには、 delete_metric
を呼び出します。
mv.delete_metric("test_accuracy")
Tip
また、 ALTER MODEL ... MODIFY VERSION を使用して、 SQL でモデルバージョンのメトリクス(メタデータとして格納される)を変更することもできます。
モデル説明の取得¶
モデルレジストリは、 Shapley値 を計算することで、モデルの結果を説明し、どの入力機能が予測に最も寄与しているかを伝えることができます。このプレビュー機能は、Snowflake 8.31以降で作成されたすべてのモデルビューで、基本モデルの explain
メソッドを通じてデフォルトで利用できます。Pythonの SQL 、またはモデルビューの run
メソッドから explain
を呼び出せます。
この機能の詳細については、 モデルの説明可能性 をご参照ください。
モデルバージョンのエクスポート¶
モデルのファイルをローカルディレクトリにエクスポートするには、 mv.export
を使用します。ディレクトリが存在しない場合は作成されます。
mv.export("~/mymodel/")
デフォルトでは、エクスポートされるファイルには、コード、モデルをロードする環境、モデルの重みが含まれます。ウェアハウスでモデルを実行するために必要なファイルもエクスポートするには、 export_mode = ExportMode.FULL
を指定します。
mv.export("~/mymodel/", export_mode=ExportMode.FULL)
モデルバージョンの読み込み¶
mv.load
を使って、もともとレジストリに追加されていたオリジナルのPythonモデルオブジェクトを読み込みます。そうすれば、Pythonのコードで定義したのと同じように、推論にそのモデルを使うことができます。
clf = mv.load()
モデルの適切な関数を保証するために、ターゲットのPython環境(すなわち、Pythonインタプリターとすべてのライブラリのバージョン)は、モデルがログに記録された環境と同一でなければなりません。 load
の呼び出しで force=True
を指定すると、環境が異なっていてもモデルを強制的にロードします。
Tip
モデルがホストされている環境と同じであることを確認するために、モデルレジストリからconda環境のコピーをダウンロードします。
conda_env = session.file.get("snow://model/<modelName>/versions/<versionName>/runtimes/python_runtime/env/conda.yml", ".")
open("~/conda.yml", "w").write(conda_env)
そして、このファイルから新しいconda環境を作成します。
conda env create --name newenv --file=~/conda.yml
conda activate newenv
オプションの options
引数は、モデルを読み込むためのオプションの辞書です。現在、この引数は use_gpu
オプションのみをサポートしています。
オプション |
型 |
説明 |
デフォルト |
---|---|---|---|
|
|
GPU 固有のロードロジックを有効にします。 |
|
次の例は、 options
引数の使い方を示しています。
clf = mv.load(options={"use_gpu": True})
モデルメソッドの呼び出し¶
モデルのバージョンは、推論や他のモデル操作を実行するための付属関数である メソッド を持つことができます。モデルのバージョンは異なるメソッドを持つことができ、これらのメソッドの署名も異なる場合があります。
モデルのバージョンのメソッドを呼び出すには、 mv.run
を使います。 mv
は ModelVersion
オブジェクトです。呼び出される関数の名前を指定し、推論データを含む Snowpark または pandas DataFrame と必要なパラメーターを渡します。このメソッドは、Snowflakeウェアハウスで実行されます。
メソッドの戻り値は、渡された DataFrame のタイプにマッチする Snowpark または pandas DataFrame です。Snowpark DataFrames は遅延評価されるため、DataFrame の collect
、 show
、 to_pandas
メソッドが呼び出されたときのみメソッドが実行されます。
注釈
メソッドを起動すると、レジストリへの接続に使用しているセッションで指定されたウェアハウスでメソッドが実行されます。 ウェアハウスサイズの指定 をご参照ください。
次の例は、モデルの predict
メソッドの実行を示しています。このモデルの predict
メソッドは、推論データ(ここでは test_features
)以外にパラメーターを必要としません。必要な場合は、推論データの後に追加の引数として渡されることになります。
remote_prediction = mv.run(test_features, function_name="predict")
remote_prediction.show() # assuming test_features is Snowpark DataFrame
指定されたモデルでどのメソッドが呼び出せるかを確認するには、 mv.show_functions
を呼び出します。このメソッドの返り値は、 ModelFunctionInfo
オブジェクトのリストです。これらの各オブジェクトには以下の属性が含まれます。
name
: Pythonまたは SQL から呼び出せる関数名。target_method
:元のログモデルのPythonメソッド名。
Tip
SQLでモデルメソッドを呼び出すこともできます。 モデルコマンド をご参照ください。
コストの考慮事項¶
Snowflake モデルレジストリを使用すると、標準的なSnowflake消費ベースのコストが発生します。これらには次が含まれます。
モデルのアーティファクト、メタデータ、および関数を格納するためのコスト。ストレージコストに関する一般情報については、 ストレージコストの調査 をご参照ください。
ステージ間のファイルをSnowflakeにコピーするコスト。 COPY FILES をご参照ください。
モデルやモデルのバージョンの表示、モデルのコメント、タグ、メトリクスの変更など、 Snowsight UI や SQL 、Pythonインターフェイスを介したサーバーレスモデルオブジェクト操作のコスト。
ウェアハウスコンピューティングコスト。コストは、モデルの型や学習予測に使用するデータ量によって異なります。Snowflakeのコンピューティングコストに関する一般的な情報については、 コンピューティングコストについて をご参照ください。ウェアハウスのコンピューティングコストは、次のような場合に発生します。
モデルおよびバージョンの作成操作。
モデルのメソッドの呼び出し