Snowflake Model Registry¶

所需权限¶

若要创建模型，您必须拥有创建模型的架构，或者拥有其 CREATE MODEL 权限。要使用模型，您必须拥有该模型，或者具备该模型的 USAGE 或 READ 权限。

1. USAGE 权限允许被授权方使用模型或仓库进行推理，但无法查看其任何内部组件。

2. READ 权限允许授权对象使用模型进行 SPCS 推理，还可以查看其元数据，例如其注释、标签和指标。

要授予用户架构中所有现有模型的 USAGE 访问权限，请使用 GRANT USAGE ON ALL MODELS IN SCHEMA <schema> TO ROLE <role>; 您还可以通过 GRANT USAGE ON FUTURE MODELS IN SCHEMA <schema> TO ROLE <role>; 向用户授予对在架构中自动创建的未来模型的访问权限。

同样，您可以使用相同的语法，向用户提供对架构中所有现有或未来模型的 READ 访问权限，但要将 USAGE 替换为 READ。

如果用户的角色对模型具有 OWNER、USAGE 或 READ 权限，则该角色会显示在 Snowsight模型注册表页面 中。有关权限如何在 Snowflake 中起作用的详细信息，请参阅 访问控制权限。

当前限制¶

以下限制适用于模型和模型版本：

打开 Snowflake Model Registry¶

模型是一级 Snowflake 对象，可以与其他 Snowflake 对象一起组织到数据库和架构内。Snowflake Model Registry 提供了一个 Python 类来在架构内管理模型。因此，任何 Snowflake 架构均可用作注册表。不必为此目的初始化或准备架构。Snowflake 建议为此目的创建一个或多个专用架构，例如 ML.REGISTRY。您可以使用 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 task, 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=task.Task.TABULAR_BINARY_CLASSIFICATION)

log_model 的实参说明如下。

必填实参

可选实参

from snowflake.ml.model.volatility import Volatility

options = {
  "embed_local_ml_library": True,
  "relax_version": True,
  "save_location": "/path/to/my/directory",
  "function_type": "TABLE_FUNCTION",
  "volatility": Volatility.IMMUTABLE,
  "method_options": {
    "predict": {
      "case_sensitive": False,
      "max_batch_size": 100,
      "function_type": "TABLE_FUNCTION",
      "volatility": Volatility.VOLATILE,
    },
  }

mv = reg.log_model(
    clf,
    model_name="my_model",
    artifact_repository_map={
        "pip": "snowflake.snowpark.pypi_shared_repository"
    },
    pip_requirements=['scikit-learn'],
    sample_input_data=train_features,
)

from snowflake.ml.model._model_composer.model_manifest import (
    model_manifest
)
model_manifest.ModelManifest._ENABLE_USER_FILES = True

log_model 会返回一个 snowflake.ml.model.ModelVersion 对象，该对象表示已添加到注册表的模型的版本。

在登记之后，模型本身无法修改（不过可以更改其元数据）。要删除模型及其所有版本，请使用注册表的 delete_model 方法。

使用依赖项和目标平台¶

使用模型工件¶

登记模型后，其工件（支持模型的文件，包括其序列化的 Python 对象和各种元数据文件，例如其清单）在内部暂存区上提供。工件无法修改，但您可以查看或下载您拥有的模型的工件。

例如，您可以使用 :doc:`GET 命令 </sql-reference/sql/get>`或 Snowpark Python 中的等效命令 `FileOperation.get <https://docs.snowflake.com/en/developer-guide/snowpark/reference/python/latest/api/snowflake.snowpark.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' file::///tmp/my_model/

或者使用 Snowpark Python 的等效命令：

session.file.get('snow://model/my_model/versions/V3/MANIFEST.yml', 'model_artifacts')

删除模型¶

使用注册表的 delete_model 方法删除模型及其所有版本：

reg.delete_model("mymodel")

从注册表获取模型¶

要获取有关每个模型的信息，请使用 show_models 方法：

model_df = reg.show_models()

show_models 的结果是一个 pandas DataFrame。下面列出了可用的列：

要改为获取注册表中的模型列表（每个模型都作为一个 Model 实例），请使用 models 方法：

model_list = reg.models()

要根据名称从注册表获取对特定模型的引用，请使用注册表的 get_model 方法：

m = reg.get_model("MyModel")

有了对模型的引用后，无论是来自 models 方法返回的列表，还是通过使用 get_model 检索到的列表，都可以使用 其元数据 及 其版本。

查看和更新模型的元数据¶

您可以在注册表中查看和更新模型的元数据属性，包括其名称、注释、标签和指标。

print(m.comment)
m.comment = "A better description than the one I provided originally"

print(m.description)
m.description = "A better description than the one I provided originally"

print(m.show_tags())

m.set_tag("live_version", "v1")

m.get_tag("live_version")

m.unset_tag("live_version")

m.rename("MY_MODEL_TOO")

使用模型版本¶

一个模型可以有无限多个的版本，每个版本都由一个字符串标识。您可以使用自己喜欢的任何版本命名约定。登记模型实际上登记的是模型的 特定版本。要登记模型的其他版本，请再次调用具有相同 model_name 但不同 version_name 的 log_model。

模型的一个版本由 snowflake.ml.model.ModelVersion 类的一个实例表示。

要获取模型的所有版本的列表，请调用模型对象的 versions 方法。结果是 ModelVersion 实例的列表：

version_list = m.versions()

要改为以 DataFrame 的形式获取有关每个模型的信息，请调用模型的 show_versions 方法：

version_df = m.show_versions()

所得的 DataFrame 包含以下列：

m.delete_version("rc1")

default_version = m.default
m.default = "v2"

m = reg.get_model("MyModel")

mv = m.version("v1")
mv = m.default

print(mv.comment)
print(mv.description)

mv.comment = "A model version comment"
mv.description = "Same as setting the comment"

from sklearn import metrics

test_accuracy = metrics.accuracy_score(test_labels, prediction)

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)

metrics = mv.show_metrics()

mv.delete_metric("test_accuracy")

mv.export("~/mymodel/")

mv.export("~/mymodel/", export_mode=ExportMode.FULL)

clf = mv.load()

conda_env = session.file.get("snow://model/<modelName>/versions/<versionName>/runtimes/python_runtime/env/conda.yml", ".")
open("~/conda.yml", "w").write(conda_env)

conda env create --name newenv --file=~/conda.yml
conda activate newenv

clf = mv.load(options={"use_gpu": True})

调用模型方法¶

模型版本可以具有 方法，这些方法是附加的函数，可执行这些函数来执行推理或其他模型操作。模型的版本可以具有不同的方法，这些方法的签名也可以有所不同。

要调用模型版本的方法，请使用 mv.run，其中 mv 是 ModelVersion 对象。指定要调用的函数的名称，并传递包含推理数据的 Snowpark 或 pandas DataFrame，以及任何必需的参数。该方法在 Snowflake 仓库中执行。

该方法的返回值是 Snowpark 或 pandas DataFrame，匹配传入的 DataFrame 的类型。Snowpark DataFrames 采用延迟计算的方式，因此只有在调用 DataFrame 的 collect、show 或 to_pandas 方法时才会运行此类方法。

下面的示例阐释了模型的 predict 方法的运行。除了推理数据（此处的 test_features）之外，此模型的 predict 方法不需要任何参数。如果确实需要，其他参数将作为附加参数在推理数据之后传递。

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 方法的名称。

共享模型¶

Models can both be shared and replicated. The following privileges are grantable to a shared model:

• USAGE: Allows the grantee to use the model for warehouse inference without being able to see any of its internals.

• READ: Allows the grantee to use the model for SPCS inference and also see its metadata. Metadata includes, but isn't limited to, comments, tags, and metrics.

成本注意事项¶

使用 Snowflake Model Registry 会产生标准的基于 Snowflake 用量的成本。这些对象包括：

• 存储模型工件、元数据和函数的成本。有关存储成本的一般信息，请参阅 探索存储成本。

• 在暂存区之间将文件复制到 Snowflake 的成本。请参阅 COPY FILES。

• 通过 Snowsight UI 或者 SQL 接口或 Python 接口进行无服务器模型对象操作的成本，例如显示模型和模型版本，以及更改模型注释、标签和指标。

• 仓库计算成本，具体取决于模型的类型和用于推理的数据量。有关 Snowflake 计算成本的一般信息，请参阅 了解计算成本。以下操作会产生仓库计算成本：

  • 模型和版本创建操作

  • 调用一个模型的方法