Model 类

参考

表示机器学习训练的结果。

模型是 Azure 机器学习训练 Run 或 Azure 外部的其他某种模型训练过程的结果。无论模型的生成方式如何，它都可以在工作区中进行注册，由名称和版本表示。使用模型 Model 类，可以将模型打包，以便与 Docker 一起使用，并将它部署为可用于推理请求的实时终结点。

有关演示如何创建、管理和使用模型的端到端教程，请参阅使用 Azure 机器学习通过 MNIST 数据和 scikit-learn 训练映像分类模型。

模型构造函数。

Model 构造函数用于检索与提供的工作区关联的 Model 对象的云表示形式。必须提供名称或 ID。

继承: builtins.object

Model

构造函数

Model(workspace, name=None, id=None, tags=None, properties=None, version=None, run_id=None, model_framework=None, expand=True, **kwargs)

参数

名称	说明
workspace 必需	Workspace 包含要检索的模型的工作区对象。
name	str 要检索的模型的名称。返回具有指定名称的最新模型（如果存在）。默认值: None
id	str 要检索的模型的 ID。返回具有指定 ID 的模型（如果存在）。默认值: None
tags	list 用于筛选返回的结果的可选标记列表。根据提供的列表筛选结果，按“key”或“[key, value]”搜索。例如： ['key', ['key2', 'key2 value']] 默认值: None
properties	list 用于筛选返回的结果的可选属性列表。根据提供的列表筛选结果，按“key”或“[key, value]”搜索。例如： ['key', ['key2', 'key2 value']] 默认值: None
version	int 要返回的模型版本。与 `name` 参数一起提供时，将返回指定的命名模型的特定版本（如果存在）。如果省略 `version`，则返回模型的最新版本。默认值: None
run_id	str 用于筛选返回的结果的可选 ID。默认值: None
model_framework	str 用于筛选返回的结果的可选框架名称。如果指定，则返回与指定的框架匹配的模型的结果。有关允许的值，请参阅 Framework。默认值: None
workspace 必需	Workspace 包含要检索的模型的工作区对象。
name 必需	str 要检索的模型的名称。返回具有指定名称的最新模型（如果存在）。
id 必需	str 要检索的模型的 ID。返回具有指定 ID 的模型（如果存在）。
tags 必需	list 用于筛选返回的结果的可选标记列表。根据提供的列表筛选结果，按“key”或“[key, value]”搜索。例如： ['key', ['key2', 'key2 value']]
properties 必需	list 用于筛选返回的结果的可选属性列表。根据提供的列表筛选结果，按“key”或“[key, value]”搜索。例如： ['key', ['key2', 'key2 value']]
version 必需	int 要返回的模型版本。与 `name` 参数一起提供时，将返回指定的命名模型的特定版本（如果存在）。如果省略 `version`，则返回模型的最新版本。
run_id 必需	str 用于筛选返回的结果的可选 ID。
model_framework 必需	str 用于筛选返回的结果的可选框架名称。如果指定，则返回与指定的框架匹配的模型的结果。有关允许的值，请参阅 Framework。
expand	bool 如果为 true，将返回填充了所有子属性（例如运行、数据集和试验）的模型。默认值: True

注解

Model 构造函数用于检索与指定工作区关联的模型对象的云表示形式。必须至少提供名称或 ID 才能检索模型，但还可以使用其他选项进行筛选，包括按标记、属性、版本、运行 ID 和框架进行筛选。


   from azureml.core.model import Model
   model = Model(ws, 'my_model_name')

以下示例演示了如何提取模型的特定版本。


   from azureml.core.model import Model
   model = Model(ws, 'my_model_name', version=1)

注册某个模型会为构成该模型的一个或多个文件创建逻辑容器。除了模型文件本身的内容，注册模型还将存储模型元数据（包括模型说明、标记和框架信息），在工作区中管理和部署模型时，这些元数据非常有用。例如，使用标记可以对模型进行分类，并在工作区中列出模型时应用筛选器。注册后，可以下载或部署已注册的模型，以及接收已注册的所有文件和元数据。

以下示例演示如何注册一个指定标签和说明的模型。


   from azureml.core.model import Model

   model = Model.register(model_path="sklearn_regression_model.pkl",
                          model_name="sklearn_regression_model",
                          tags={'area': "diabetes", 'type': "regression"},
                          description="Ridge regression model to predict diabetes",
                          workspace=ws)

完整示例可从 https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/deployment/deploy-to-local/register-model-deploy-local-advanced.ipynb 获取

以下示例演示如何注册指定框架、输入和输出数据集以及资源配置的模型。


   import sklearn

   from azureml.core import Model
   from azureml.core.resource_configuration import ResourceConfiguration


   model = Model.register(workspace=ws,
                          model_name='my-sklearn-model',                # Name of the registered model in your workspace.
                          model_path='./sklearn_regression_model.pkl',  # Local file to upload and register as a model.
                          model_framework=Model.Framework.SCIKITLEARN,  # Framework used to create the model.
                          model_framework_version=sklearn.__version__,  # Version of scikit-learn used to create the model.
                          sample_input_dataset=input_dataset,
                          sample_output_dataset=output_dataset,
                          resource_configuration=ResourceConfiguration(cpu=1, memory_in_gb=0.5),
                          description='Ridge regression model to predict diabetes progression.',
                          tags={'area': 'diabetes', 'type': 'regression'})

   print('Name:', model.name)
   print('Version:', model.version)

“变量”部分列出了云模型对象的本地表示形式的属性。应将这些变量视为只读。更改其值不会反映在对应的云对象中。

变量

名称	说明
created_by	dict 创建模型的用户。
created_time	datetime 创建模型的时间。
azureml.core.Model.description	模型对象的说明。
azureml.core.Model.id	模型 ID。其格式为<模型名称>:<模型版本>。
mime_type	str 模型 mime 类型。
azureml.core.Model.name	模型的名称。
model_framework	str 模型的框架。
model_framework_version	str 模型的框架版本。
azureml.core.Model.tags	模型对象的标记字典。
azureml.core.Model.properties	模型的键值属性字典。这些属性在注册后无法更改，但是可以添加新的键值对。
unpack	bool 模型在拉取到本地上下文时是否需要解包（解压缩）。
url	str 模型的 URL 位置。
azureml.core.Model.version	模型的版本。
azureml.core.Model.workspace	包含模型的工作区。
azureml.core.Model.experiment_name	创建模型的试验的名称。
azureml.core.Model.run_id	创建模型的运行的 ID。
parent_id	str 模型的父模型的 ID。
derived_model_ids	list[str] 已从此模型派生的模型 ID 的列表。
resource_configuration	ResourceConfiguration 此模型的 ResourceConfiguration。用于分析。

方法

add_dataset_references	将提供的数据集与此模型相关联。
add_properties	将键值对添加到此模型的属性字典中。
add_tags	将键值对添加到此模型的标记字典中。
delete	将此模型从其关联的工作区中删除。
deploy	从零个或多个 Model 对象部署 Web 服务。生成的 Web 服务是可用于推理请求实时终结点。模型 `deploy` 函数类似于 Webservice 类的 `deploy` 函数，但不注册模型。如果具有已注册的模型对象，请使用模型 `deploy` 函数。
deserialize	将 JSON 对象转换为模型对象。如果指定的工作区不是模型注册到的工作区，则转换将会失败。
download	将模型下载到本地文件系统的目标目录。
get_model_path	返回模型的路径。该函数将在以下位置搜索模型。如果 `version` 为“无”：远程下载到缓存（如果提供了工作区）从缓存 azureml-models/$MODEL_NAME/$LATEST_VERSION/ 中加载 ./$MODEL_NAME 如果 `version` 不为 None：从缓存 azureml-models/$MODEL_NAME/$SPECIFIED_VERSION/ 中加载远程下载到缓存（如果提供了工作区）
get_sas_urls	返回包含文件名和对应 SAS URL 的键值对字典。
list	使用可选筛选器检索与提供的工作区关联的所有模型的列表。
package	以 Docker 映像或 Dockerfile 生成上下文的形式创建模型包。
print_configuration	打印用户配置。
profile	分析模型以获取资源要求建议。这是一个长期运行的操作，最长可能需要花费 25 分钟，具体取决于数据集的大小。
register	将模型注册到提供的工作区。
remove_tags	从此模型的标记字典中删除指定的键。
serialize	将此模型转换为 JSON 序列化字典。
update	对模型执行就地更新。将替换指定的参数的现有值。
update_tags_properties	对模型的标记和属性执行更新。

add_dataset_references

将提供的数据集与此模型相关联。

add_dataset_references(datasets)

参数

名称	说明
datasets 必需	list[tuple(<xref:str :> (Dataset 或 DatasetSnapshot))] 表示数据集用途与数据集对象配对的元组列表。

例外

类型	说明
WebserviceException

add_properties

将键值对添加到此模型的属性字典中。

add_properties(properties)

参数

名称	说明
properties 必需	dict(<xref:str : str>) 要添加的属性字典。

例外

类型	说明
WebserviceException

add_tags

将键值对添加到此模型的标记字典中。

add_tags(tags)

参数

名称	说明
tags 必需	dict(<xref:{str : str}>) 要添加的标记字典。

例外

类型	说明
WebserviceException

delete

将此模型从其关联的工作区中删除。

delete()

例外

类型	说明
WebserviceException

deploy

从零个或多个 Model 对象部署 Web 服务。

生成的 Web 服务是可用于推理请求实时终结点。模型 deploy 函数类似于 Webservice 类的 deploy 函数，但不注册模型。如果具有已注册的模型对象，请使用模型 deploy 函数。

static deploy(workspace, name, models, inference_config=None, deployment_config=None, deployment_target=None, overwrite=False, show_output=False)

参数

名称	说明
workspace 必需	Workspace 要与 Web 服务关联的工作区对象。
name 必需	str 为部署的服务指定的名称。对于工作区，必须是唯一的，仅包含小写字母、数字或短划线，以字母开头，且长度在 3 到 32 个字符之间。
models 必需	list[Model] 模型对象列表。可以是空列表。
inference_config	InferenceConfig 用于确定所需模型属性的 ImageConfig 对象。默认值: None
deployment_config	WebserviceDeploymentConfiguration 用于配置 Web 服务的 WebserviceDeploymentConfiguration。如果未提供，将基于所需目标使用空配置对象。默认值: None
deployment_target	ComputeTarget 要将 Web 服务部署到的 ComputeTarget。由于 Azure 容器实例没有关联的 ComputeTarget，因此将此参数保留为“无”以部署到 Azure 容器实例。默认值: None
overwrite	bool 指示如果具有指定名称的服务已存在，是否覆盖现有服务。默认值: False
show_output	bool 指示是否显示服务部署的进度。默认值: False

类型	说明
Webservice	对应于已部署的 Web 服务的 Web 服务对象。

例外

类型	说明
WebserviceException

deserialize

将 JSON 对象转换为模型对象。

如果指定的工作区不是模型注册到的工作区，则转换将会失败。

static deserialize(workspace, model_payload)

参数

名称	说明
workspace 必需	Workspace 将模型注册到的工作区对象。
model_payload 必需	dict 要转换为模型对象的 JSON 对象。

类型	说明
Model	所提供的 JSON 对象的模型表示形式。

例外

类型	说明
WebserviceException

download

将模型下载到本地文件系统的目标目录。

download(target_dir='.', exist_ok=False, exists_ok=None)

参数

名称	说明
target_dir	str 将模型下载到的目录的路径。默认值为"." 默认值: .
exist_ok	bool 指示是否替换下载的目录/文件（如果存在）。默认为 False。默认值: False
exists_ok	bool 已弃用。使用 `exist_ok`。默认值: None

类型	说明
str	模型的文件或文件夹的路径。

例外

类型	说明
WebserviceException

get_model_path

返回模型的路径。

该函数将在以下位置搜索模型。

如果 version 为“无”：

远程下载到缓存（如果提供了工作区）
从缓存 azureml-models/$MODEL_NAME/$LATEST_VERSION/ 中加载
./$MODEL_NAME

如果 version 不为 None：

从缓存 azureml-models/$MODEL_NAME/$SPECIFIED_VERSION/ 中加载
远程下载到缓存（如果提供了工作区）

static get_model_path(model_name, version=None, _workspace=None)

参数

名称	说明
model_name 必需	str 要检索的模型的名称。
version	int 要检索的模型的版本。默认为最新版本。默认值: None
_workspace	Workspace 要从中检索模型的工作区。无法远程使用。如果未指定，则仅搜索本地缓存。默认值: None

类型	说明
str	模型在磁盘上的路径。

例外

类型	说明
ModelNotFoundException

get_sas_urls

返回包含文件名和对应 SAS URL 的键值对字典。

get_sas_urls()

类型	说明
dict	包含文件名和对应 SAS URL 的键值对字典

例外

类型	说明
WebserviceException

list

使用可选筛选器检索与提供的工作区关联的所有模型的列表。

static list(workspace, name=None, tags=None, properties=None, run_id=None, latest=False, dataset_id=None, expand=True, page_count=255, model_framework=None)

参数

名称	说明
workspace 必需	Workspace 要从中检索模型的工作区对象。
name	str 如果提供，则仅返回具有指定名称的模型（如果有）。默认值: None
tags	list 将基于提供的列表按“key”或“[key, value]”筛选。例如： ['key', ['key2', 'key2 value']] 默认值: None
properties	list 基于提供的列表按“key”或“[key, value]”筛选。例如： ['key', ['key2', 'key2 value']] 默认值: None
run_id	str 将基于提供的运行 ID 筛选。默认值: None
latest	bool 如果为 true，则仅返回具有最新版本的模型。默认值: False
dataset_id	str 将基于提供的数据集 ID 筛选。默认值: None
expand	bool 如果为 true，将返回填充了所有子属性（例如运行、数据集和试验）的模型。在许多模型中，将此项设置为 false 可以加速完成 list() 方法。默认值: True
page_count	int 要在页中检索的项数。目前支持的最大值为 255。默认值为 255。默认值: 255
model_framework	str 如果提供，则仅返回具有指定框架的模型（如果有）。默认值: None

类型	说明
list[Model]	模型列表（选择性地筛选）。

例外

类型	说明
WebserviceException

package

以 Docker 映像或 Dockerfile 生成上下文的形式创建模型包。

static package(workspace, models, inference_config=None, generate_dockerfile=False, image_name=None, image_label=None)

参数

名称	说明
workspace 必需	Workspace 要在其中创建包的工作区。
models 必需	list[Model] 要包含在包中的模型对象列表。可以是空列表。
inference_config	InferenceConfig 用于配置模型操作的 InferenceConfig 对象。此项必须包括环境对象。默认值: None
generate_dockerfile	bool 是否创建可在本地运行的 Dockerfile，而不是生成映像。默认值: False
image_name	str 生成映像时，生成的映像的名称。默认值: None
image_label	str 生成映像时，生成的映像的标签。默认值: None

类型	说明
ModelPackage	ModelPackage 对象。

例外

类型	说明
WebserviceException

print_configuration

打印用户配置。

static print_configuration(models, inference_config, deployment_config, deployment_target)

参数

名称	说明
models 必需	list[Model] 模型对象列表。可以是空列表。
inference_config 必需	InferenceConfig 用于确定所需模型属性的 ImageConfig 对象。
deployment_config 必需	WebserviceDeploymentConfiguration 用于配置 Web 服务的 WebserviceDeploymentConfiguration。
deployment_target 必需	ComputeTarget 要将 Web 服务部署到的 ComputeTarget。

例外

类型	说明
WebserviceException

profile

分析模型以获取资源要求建议。

这是一个长期运行的操作，最长可能需要花费 25 分钟，具体取决于数据集的大小。

static profile(workspace, profile_name, models, inference_config, input_dataset, cpu=None, memory_in_gb=None, description=None)

参数

名称	说明
workspace 必需	Workspace 要在其中分析模型的工作区对象。
profile_name 必需	str 分析运行的名称。
models 必需	list[Model] 模型对象列表。可以是空列表。
inference_config 必需	InferenceConfig 用于确定所需模型属性的 ImageConfig 对象。
input_dataset 必需	Dataset 用于分析的输入数据集。输入数据集应包含单个列，样本输入应采用字符串格式。
cpu	float 要在最大测试实例上使用的 CPU 核心数。目前支持的最大值为 3.5。默认值: None
memory_in_gb	float 要在最大测试实例上使用的内存量 (GB)。可以是小数。目前支持的最大值为 15.0。默认值: None
description	str 要与分析运行关联的说明。默认值: None

类型	说明
ModelProfile

例外

类型	说明
<xref:azureml.exceptions.WebserviceException>, <xref:azureml.exceptions.UserErrorException>

register

将模型注册到提供的工作区。

static register(workspace, model_path, model_name, tags=None, properties=None, description=None, datasets=None, model_framework=None, model_framework_version=None, child_paths=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None)

参数

名称	说明
workspace 必需	Workspace 要将模型注册到的工作区。
model_path 必需	str 模型资产所在的本地文件系统上的路径。这可以是指向单个文件或文件夹的直接指针。如果指向文件夹，则 `child_paths` 参数可用于指定作为模型对象捆绑在一起的各个文件，而不是使用文件夹的整个内容。
model_name 必需	str 用于注册模型的名称。
tags	dict(<xref:{str : str}>) 要分配给模型的键值标记的可选字典。默认值: None
properties	dict(<xref:{str : str}>) 要分配给模型的键值属性的可选字典。这些属性在模型创建后无法更改，但是可以添加新的键值对。默认值: None
description	str 模型的文本说明。默认值: None
datasets	list[(str, AbstractDataset)] 元组的列表，其中第一个元素描述数据集-模型关系，第二个元素是数据集。默认值: None
model_framework	str 已注册模型的框架。使用 Framework 类中系统支持的常量可以简化某些流行框架的部署。默认值: None
model_framework_version	str 已注册模型的框架版本。默认值: None
child_paths	list[str] 如果与文件夹的 `model_path` 一起提供，则只会将指定的文件捆绑到模型对象。默认值: None
sample_input_dataset	AbstractDataset 已注册模型的示例输入数据集。默认值: None
sample_output_dataset	AbstractDataset 已注册模型的示例输出数据集。默认值: None
resource_configuration	ResourceConfiguration 用于运行已注册模型的资源配置。默认值: None

类型	说明
Model	已注册的模型对象。

例外

类型	说明
WebserviceException

注解

除了模型文件本身的内容，注册模型还将存储模型元数据（包括模型说明、标记和框架信息），在工作区中管理和部署模型时，这些元数据非常有用。例如，使用标记可以对模型进行分类，并在工作区中列出模型时应用筛选器。

以下示例演示如何注册一个指定标签和说明的模型。


   from azureml.core.model import Model

   model = Model.register(model_path="sklearn_regression_model.pkl",
                          model_name="sklearn_regression_model",
                          tags={'area': "diabetes", 'type': "regression"},
                          description="Ridge regression model to predict diabetes",
                          workspace=ws)

完整示例可从 https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/deployment/deploy-to-local/register-model-deploy-local-advanced.ipynb 获取

如果你有一个作为试验运行结果生成的模型，可以直接从运行对象注册它，而无需先将其下载到本地文件。为此，请使用 Run 类中记录的 register_model 方法。

remove_tags

从此模型的标记字典中删除指定的键。

remove_tags(tags)

参数

名称	说明
tags 必需	list[str] 要删除的键列表

例外

类型	说明
WebserviceException

serialize

将此模型转换为 JSON 序列化字典。

serialize()

类型	说明
dict	此模型的 JSON 表示形式

例外

类型	说明
WebserviceException

update

对模型执行就地更新。

将替换指定的参数的现有值。

update(tags=None, description=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None)

参数

名称	说明
tags	dict(<xref:{str : str}>) 用于更新模型的标记字典。这些标记将替换模型的现有标记。默认值: None
description	str 用于模型的新说明。此名称将替换现有名称。默认值: None
sample_input_dataset	AbstractDataset 用于已注册模型的示例输入数据集。此示例输入数据集将替换现有数据集。默认值: None
sample_output_dataset	AbstractDataset 用于已注册模型的示例输出数据集。此示例输出数据集将替换现有数据集。默认值: None
resource_configuration	ResourceConfiguration 用于运行已注册模型的资源配置。默认值: None

例外

类型	说明
WebserviceException

update_tags_properties

对模型的标记和属性执行更新。

update_tags_properties(add_tags=None, remove_tags=None, add_properties=None)

参数

名称	说明
add_tags	dict(<xref:{str : str}>) 要添加的标记字典。默认值: None
remove_tags	list[str] 要删除的标记名称列表。默认值: None
add_properties	dict(<xref:{str : str}>) 要添加的属性字典。默认值: None

例外

类型	说明
WebserviceException

通过