Model 类

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

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

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

模型构造函数。

模型构造函数用于检索与提供的工作区关联的 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
必需

包含要检索的模型的工作区对象。

name
str

要检索的模型的名称。 返回具有指定名称的最新模型(如果存在)。

默认值: None
id
str

要检索的模型的 ID。 返回具有指定 ID 的模型(如果存在)。

默认值: None
tags

用于筛选返回的结果的可选标记列表。 根据提供的列表筛选结果,按“key”或“[key, value]”搜索。 例如: ['key', ['key2', 'key2 value']]

默认值: None
properties

用于筛选返回的结果的可选属性列表。 根据提供的列表筛选结果,按“key”或“[key, value]”搜索。 例如: ['key', ['key2', 'key2 value']]

默认值: None
version
int

要返回的模型版本。 与 name 参数一起提供时,将返回指定的命名模型的特定版本(如果存在)。 如果省略 version,则返回模型的最新版本。

默认值: None
run_id
str

用于筛选返回的结果的可选 ID。

默认值: None
model_framework
str

用于筛选返回的结果的可选框架名称。 如果指定,则返回与指定的框架匹配的模型的结果。 有关允许的值,请参阅 Framework

默认值: None
workspace
必需

包含要检索的模型的工作区对象。

name
必需
str

要检索的模型的名称。 返回具有指定名称的最新模型(如果存在)。

id
必需
str

要检索的模型的 ID。 返回具有指定 ID 的模型(如果存在)。

tags
必需

用于筛选返回的结果的可选标记列表。 根据提供的列表筛选结果,按“key”或“[key, value]”搜索。 例如: ['key', ['key2', 'key2 value']]

properties
必需

用于筛选返回的结果的可选属性列表。 根据提供的列表筛选结果,按“key”或“[key, value]”搜索。 例如: ['key', ['key2', 'key2 value']]

version
必需
int

要返回的模型版本。 与 name 参数一起提供时,将返回指定的命名模型的特定版本(如果存在)。 如果省略 version,则返回模型的最新版本。

run_id
必需
str

用于筛选返回的结果的可选 ID。

model_framework
必需
str

用于筛选返回的结果的可选框架名称。 如果指定,则返回与指定的框架匹配的模型的结果。 有关允许的值,请参阅 Framework

expand

如果为 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

创建模型的用户。

created_time

创建模型的时间。

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

模型在拉取到本地上下文时是否需要解包(解压缩)。

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

已从此模型派生的模型 ID 的列表。

resource_configuration

此模型的 ResourceConfiguration。 用于分析。

方法

add_dataset_references

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

add_properties

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

add_tags

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

delete

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

deploy

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

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

deserialize

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

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

download

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

get_model_path

返回模型的路径。

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

如果 version 为“无”:

  1. 远程下载到缓存(如果提供了工作区)
  2. 从缓存 azureml-models/$MODEL_NAME/$LATEST_VERSION/ 中加载
  3. ./$MODEL_NAME

如果 version 不为 None:

  1. 从缓存 azureml-models/$MODEL_NAME/$SPECIFIED_VERSION/ 中加载
  2. 远程下载到缓存(如果提供了工作区)
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 :> (DatasetDatasetSnapshot))]

表示数据集用途与数据集对象配对的元组列表。

例外

类型 说明

add_properties

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

add_properties(properties)

参数

名称 说明
properties
必需
dict(<xref:str : str>)

要添加的属性字典。

例外

类型 说明

add_tags

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

add_tags(tags)

参数

名称 说明
tags
必需
dict(<xref:{str : str}>)

要添加的标记字典。

例外

类型 说明

delete

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

delete()

例外

类型 说明

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
必需

要与 Web 服务关联的工作区对象。

name
必需
str

为部署的服务指定的名称。 对于工作区,必须是唯一的,仅包含小写字母、数字或短划线,以字母开头,且长度在 3 到 32 个字符之间。

models
必需

模型对象列表。 可以是空列表。

inference_config

用于确定所需模型属性的 ImageConfig 对象。

默认值: None
deployment_config

用于配置 Web 服务的 WebserviceDeploymentConfiguration。 如果未提供,将基于所需目标使用空配置对象。

默认值: None
deployment_target

要将 Web 服务部署到的 ComputeTarget。 由于 Azure 容器实例没有关联的 ComputeTarget,因此将此参数保留为“无”以部署到 Azure 容器实例。

默认值: None
overwrite

指示如果具有指定名称的服务已存在,是否覆盖现有服务。

默认值: False
show_output

指示是否显示服务部署的进度。

默认值: False

返回

类型 说明

对应于已部署的 Web 服务的 Web 服务对象。

例外

类型 说明

deserialize

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

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

static deserialize(workspace, model_payload)

参数

名称 说明
workspace
必需

将模型注册到的工作区对象。

model_payload
必需

要转换为模型对象的 JSON 对象。

返回

类型 说明

所提供的 JSON 对象的模型表示形式。

例外

类型 说明

download

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

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

参数

名称 说明
target_dir
str

将模型下载到的目录的路径。 默认值为"."

默认值: .
exist_ok

指示是否替换下载的目录/文件(如果存在)。 默认为 False。

默认值: False
exists_ok

已弃用。 使用 exist_ok

默认值: None

返回

类型 说明
str

模型的文件或文件夹的路径。

例外

类型 说明

get_model_path

返回模型的路径。

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

如果 version 为“无”:

  1. 远程下载到缓存(如果提供了工作区)
  2. 从缓存 azureml-models/$MODEL_NAME/$LATEST_VERSION/ 中加载
  3. ./$MODEL_NAME

如果 version 不为 None:

  1. 从缓存 azureml-models/$MODEL_NAME/$SPECIFIED_VERSION/ 中加载
  2. 远程下载到缓存(如果提供了工作区)
static get_model_path(model_name, version=None, _workspace=None)

参数

名称 说明
model_name
必需
str

要检索的模型的名称。

version
int

要检索的模型的版本。 默认为最新版本。

默认值: None
_workspace

要从中检索模型的工作区。 无法远程使用。 如果未指定,则仅搜索本地缓存。

默认值: None

返回

类型 说明
str

模型在磁盘上的路径。

例外

类型 说明

get_sas_urls

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

get_sas_urls()

返回

类型 说明

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

例外

类型 说明

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
必需

要从中检索模型的工作区对象。

name
str

如果提供,则仅返回具有指定名称的模型(如果有)。

默认值: None
tags

将基于提供的列表按“key”或“[key, value]”筛选。 例如: ['key', ['key2', 'key2 value']]

默认值: None
properties

基于提供的列表按“key”或“[key, value]”筛选。 例如: ['key', ['key2', 'key2 value']]

默认值: None
run_id
str

将基于提供的运行 ID 筛选。

默认值: None
latest

如果为 true,则仅返回具有最新版本的模型。

默认值: False
dataset_id
str

将基于提供的数据集 ID 筛选。

默认值: None
expand

如果为 true,将返回填充了所有子属性(例如运行、数据集和试验)的模型。 在许多模型中,将此项设置为 false 可以加速完成 list() 方法。

默认值: True
page_count
int

要在页中检索的项数。 目前支持的最大值为 255。 默认值为 255。

默认值: 255
model_framework
str

如果提供,则仅返回具有指定框架的模型(如果有)。

默认值: None

返回

类型 说明

模型列表(选择性地筛选)。

例外

类型 说明

package

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

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

参数

名称 说明
workspace
必需

要在其中创建包的工作区。

models
必需

要包含在包中的模型对象列表。 可以是空列表。

inference_config

用于配置模型操作的 InferenceConfig 对象。 此项必须包括环境对象。

默认值: None
generate_dockerfile

是否创建可在本地运行的 Dockerfile,而不是生成映像。

默认值: False
image_name
str

生成映像时,生成的映像的名称。

默认值: None
image_label
str

生成映像时,生成的映像的标签。

默认值: None

返回

类型 说明

ModelPackage 对象。

例外

类型 说明

print_configuration

打印用户配置。

static print_configuration(models, inference_config, deployment_config, deployment_target)

参数

名称 说明
models
必需

模型对象列表。 可以是空列表。

inference_config
必需

用于确定所需模型属性的 ImageConfig 对象。

deployment_config
必需

用于配置 Web 服务的 WebserviceDeploymentConfiguration。

deployment_target
必需

要将 Web 服务部署到的 ComputeTarget

例外

类型 说明

profile

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

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

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

参数

名称 说明
workspace
必需

要在其中分析模型的工作区对象。

profile_name
必需
str

分析运行的名称。

models
必需

模型对象列表。 可以是空列表。

inference_config
必需

用于确定所需模型属性的 ImageConfig 对象。

input_dataset
必需

用于分析的输入数据集。 输入数据集应包含单个列,样本输入应采用字符串格式。

cpu

要在最大测试实例上使用的 CPU 核心数。 目前支持的最大值为 3.5。

默认值: None
memory_in_gb

要在最大测试实例上使用的内存量 (GB)。 可以是小数。 目前支持的最大值为 15.0。

默认值: None
description
str

要与分析运行关联的说明。

默认值: None

返回

类型 说明

例外

类型 说明
<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
必需

要将模型注册到的工作区。

model_path
必需
str

模型资产所在的本地文件系统上的路径。 这可以是指向单个文件或文件夹的直接指针。 如果指向文件夹,则 child_paths 参数可用于指定作为模型对象捆绑在一起的各个文件,而不是使用文件夹的整个内容。

model_name
必需
str

用于注册模型的名称。

tags
dict(<xref:{str : str}>)

要分配给模型的键值标记的可选字典。

默认值: None
properties
dict(<xref:{str : str}>)

要分配给模型的键值属性的可选字典。 这些属性在模型创建后无法更改,但是可以添加新的键值对。

默认值: None
description
str

模型的文本说明。

默认值: None
datasets

元组的列表,其中第一个元素描述数据集-模型关系,第二个元素是数据集。

默认值: None
model_framework
str

已注册模型的框架。 使用 Framework 类中系统支持的常量可以简化某些流行框架的部署。

默认值: None
model_framework_version
str

已注册模型的框架版本。

默认值: None
child_paths

如果与文件夹的 model_path 一起提供,则只会将指定的文件捆绑到模型对象。

默认值: None
sample_input_dataset

已注册模型的示例输入数据集。

默认值: None
sample_output_dataset

已注册模型的示例输出数据集。

默认值: None
resource_configuration

用于运行已注册模型的资源配置。

默认值: None

返回

类型 说明

已注册的模型对象。

例外

类型 说明

注解

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

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


   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
必需

要删除的键列表

例外

类型 说明

serialize

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

serialize()

返回

类型 说明

此模型的 JSON 表示形式

例外

类型 说明

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

用于已注册模型的示例输入数据集。 此示例输入数据集将替换现有数据集。

默认值: None
sample_output_dataset

用于已注册模型的示例输出数据集。 此示例输出数据集将替换现有数据集。

默认值: None
resource_configuration

用于运行已注册模型的资源配置。

默认值: None

例外

类型 说明

update_tags_properties

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

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

参数

名称 说明
add_tags
dict(<xref:{str : str}>)

要添加的标记字典。

默认值: None
remove_tags

要删除的标记名称列表。

默认值: None
add_properties
dict(<xref:{str : str}>)

要添加的属性字典。

默认值: None

例外

类型 说明