Run 类

定义所有 Azure 机器学习试验运行的基类。

运行表示试验的单次试运行。 运行用于监视试用的异步执行、记录指标和存储试用的输出，以及分析结果和访问试用生成的项目。

当提交脚本以在 Azure 机器学习中的许多不同场景（包括 HyperDrive 运行、管道运行和 AutoML 运行）中训练模型时，会创建运行对象。 使用 Experiment 类进行 submit 或 start_logging 时，也会创建运行对象。

若要开始使用试验和运行，请参阅

• 创建和管理用于训练和部署的环境

• 如何管理运行

初始化 Run 对象。

继承

azureml._run_impl.run_base._RunBase

Run

构造函数

Run(experiment, run_id, outputs=None, **kwargs)

参数

名称	说明
experiment 必需	Experiment 包容性试验。
run_id 必需	str 运行的 ID。
outputs	str 要跟踪的输出。 默认值: None
_run_dto 必需	<xref:azureml._restclient.models.run_dto.RunDto> 仅限内部使用。
kwargs 必需	dict 其他配置参数的字典。
experiment 必需	Experiment 包容性试验。
run_id 必需	str 运行的 ID。
outputs 必需	str 要跟踪的输出。
kwargs 必需	dict 其他配置参数的字典。

注解

运行表示试验的单次试运行。 运行对象用于监视试用的异步执行、记录指标和存储试用的输出，以及分析结果和访问试用生成的项目。

在试验代码中使用运行将指标和项目记录到运行历史记录服务。

运行在试验之外用于监视进度以及查询和分析生成的指标和结果。

运行的功能包括：

• 存储和检索指标与数据

• 上传和下载文件

• 使用标记及子层次结构来轻松查找以往的运行

• 将存储的模型文件注册为可操作的模型

• 存储、修改和检索运行的属性

• 使用 get_context 方法从远程环境加载当前运行

• 有效地对文件或目录拍摄快照以实现可重复性

此类在以下情况下与 Experiment 一起使用：

• 通过使用 submit 执行代码来创建运行

• 使用 start_logging 在笔记本中以交互方式创建运行

• 在试验中记录指标和上传项目，例如在使用 log 时

• 在分析试验结果时读取指标和下载项目，例如在使用 get_metrics 时

若要提交运行，请创建一个描述如何运行试验的配置对象。 下面是可以使用的不同配置对象的示例：

• ScriptRunConfig

• azureml.train.automl.automlconfig.AutoMLConfig

• azureml.train.hyperdrive.HyperDriveConfig

• azureml.pipeline.core.Pipeline

• azureml.pipeline.core.PublishedPipeline

• azureml.pipeline.core.PipelineEndpoint

训练实验时可将以下指标添加到运行中。

• Scalar

  • 使用 log 将数值或字符串值记录到具有给定名称的运行中。 在运行中记录某个指标会导致在试验中的运行记录中存储该指标。 可在一次运行中多次记录同一指标，其结果被视为该指标的一个矢量。

  • 示例： run.log("accuracy", 0.95)

• 列表

  • 使用 log_list 将值列表记录到具有给定名称的运行中。

  • 示例： run.log_list("accuracies", [0.6, 0.7, 0.87])

• 行

  • 使用 log_row 创建包含多个列的指标，如 kwargs 中所述。 每个命名的参数会生成一个具有指定值的列。 可调用 log_row 一次，记录一个任意元组，或在一个循环中调用多次，生成一个完整表格。

  • 示例： run.log_row("Y over X", x=1, y=0.4)

• 表

  • 使用 log_table 将字典对象记录到具有给定名称的运行中。

  • 示例： run.log_table("Y over X", {"x":[1, 2, 3], "y":[0.6, 0.7, 0.89]})

• Image

  • 将图像记录到运行记录中。 使用 log_image 在运行中记录图像文件或 matplotlib 图。 运行记录中可显示和比较这些图像。

  • 示例： run.log_image("ROC", path)

方法

add_properties	向运行添加不可变属性。 标签和属性（都是 dict[str, str]）的可变性不同。 属性是不可变的，因此它们将创建一条永久记录用于审核目的。 标记是可变的。 有关使用标记和属性的详细信息，请参阅标记和查找运行。
add_type_provider	存储在运行历史记录中的自定义运行类型的扩展性挂钩。
cancel	将运行标记为已取消。 如果存在设置了 cancel_uri 字段的关联作业，则也会终止该作业。
child_run	创建子运行。
clean	删除与运行配置中指定的目标上的当前运行对应的文件。
complete	等待任务队列得到处理。 然后，运行被标记为已完成。 这通常用于交互式笔记本方案。
create_children	创建一个或多个子运行。
download_file	从存储中下载关联的文件。
download_files	如果未指定前缀，则从给定的存储前缀（文件夹名称）或整个容器中下载文件。
fail	将运行标记为失败。 （可选）使用传递给 error_details 的消息或异常设置运行的 Error 属性。
flush	等待任务队列得到处理。
get	获取此工作区的运行及其运行 ID。
get_all_logs	将运行的所有日志下载到目录。
get_children	获取由指定的筛选器选择的当前运行的所有子级。
get_context	返回当前服务上下文。 使用此方法检索当前服务上下文中的记录指标和上传文件。 如果 allow_offline 为 True（默认值），则针对运行对象的操作将打印到标准输出。
get_detailed_status	提取运行的最新状态。 如果运行的状态为“已排队”，则会显示详细信息。
get_details	获取运行的定义、状态信息、当前日志文件和其他详细信息。
get_details_with_logs	返回运行状态，包括日志文件内容。
get_environment	获取此运行使用的环境定义。
get_file_names	列出与运行关联中存储的文件。
get_metrics	检索记录到运行的指标。 如果 recursive 为 True（默认值为 False），则提取给定运行的子树中运行的指标。
get_properties	从服务中提取运行的最新属性。
get_secret	从运行的上下文中获取机密值。 获取提供的名称的机密值。 机密名称引用存储在与工作区关联的 Azure Key Vault 中的值。 有关使用机密的示例，请参阅在训练运行中使用机密。
get_secrets	获取给定机密名称列表的机密值。 获取所提供名称列表的已找到和未找到机密的字典。 每个机密名称引用存储在与工作区关联的 Azure 密钥保管库中的值。 有关使用机密的示例，请参阅在训练运行中使用机密。
get_snapshot_id	获取最新的快照 ID。
get_status	提取运行的最新状态。 返回的常见值包括“正在运行”、“已完成”和“失败”。
get_submitted_run	已弃用。 使用 get_context。 获取此试验的已提交运行。
get_tags	从服务中提取运行上的最新可变标记集。
list	获取可选筛选器指定的试验中的运行列表。
list_by_compute	获取可选筛选器指定的计算中的运行列表。
log	使用给定名称在运行中记录指标值。
log_accuracy_table	将准确度表记录到项目存储。 准确度表指标是一种多用途的非标量指标，可用于生成多种类型的折线图，这些图在预测概率的空间内持续变化。 这些图的示例包括 ROC、精准率-召回率以及提升曲线。 准确度表的计算类似于 ROC 曲线的计算。 ROC 曲线将真正率和假正率存储在许多不同的概率阈值处。 准确度表将真正、假正、真负和假负的原始数量存储在许多不同的概率阈值处。 有两种方法用于选择阈值：“概率”和“百分位数”。它们的不同之处在于从预测概率空间中采样的方式。 概率阈值是 0 到 1 之间均匀间隔的阈值。 如果 NUM_POINTS 为 5，则概率阈值为 [0.0, 0.25, 0.5, 0.75, 1.0]。 百分位数阈值根据预测概率的分布进行间隔。 每个阈值对应于概率阈值处数据的百分位数。 例如，如果 NUM_POINTS 为 5，则第一个阈值将位于第 0 个百分位数处，第二个阈值位于第 25 个百分位数处，第三个阈值位于第 50 个百分位数处，以此类比。 概率表和百分位数表都是三维列表，其中第一个维度表示类标签，第二个维度表示一个阈值的样本（使用 NUM_POINTS 缩放），第三个维度始终有 4 个值：TP、FP、TN、FN，并且始终按该顺序显示。 混淆值（TP、FP、TN、FN）是使用一对多策略计算的。 请参阅以下链接了解更多详细信息：https://en.wikipedia.org/wiki/Multiclass_classification N = 验证数据集中的样本数（示例中为 200）M = 阈值数 = 从概率空间中获取的样本数（示例中为 5）C = 完整数据集中的类数（示例中为 3） 准确度表的一些不变量： 所有类的所有阈值的 TP + FP + TN + FN = N TP + FN 在任何类的所有阈值处都是相同的 TN + FP 在任何类的所有阈值处都是相同的 概率表和百分位数表的形状为 [C, M, 4] 注意：M 可以是任何值并控制图表的分辨率。这独立于数据集，在计算指标时定义，并占用存储空间、计算时间和分辨率。 类标签应为字符串，混淆值应为整数，阈值应为浮点数。
log_confusion_matrix	将混淆矩阵记录到项目存储。 这会记录围绕 sklearn 混淆矩阵的包装器。 指标数据包含矩阵本身的类标签和二维列表。 有关如何计算指标的更多详细信息，请参阅以下链接：https://scikit-learn.org/stable/modules/generated/sklearn.metrics.confusion_matrix.html
log_image	在运行记录中记录图像指标。
log_list	使用给定名称将指标值的列表记录到运行中。
log_predictions	将预测记录到项目存储。 这会记录指标分数，该分数可用于将真实目标值的分布与回归任务的预测值的分布进行比较。 预测是分箱的，标准偏差是针对折线图上的误差条计算的。
log_residuals	将残差记录到项目存储。 这会记录显示回归任务残差直方图所需的数据。 残差是预测值与实际值之差。 应比计数的数量多一个边。 有关使用计数和边表示直方图的示例，请参阅 numpy 直方图文档。 https://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html
log_row	使用给定名称在运行中记录行指标。
log_table	使用给定名称在运行中记录表格指标。
register_model	注册模型以用于操作化。
remove_tags	删除此运行上可变标记的列表。
restore_snapshot	将快照还原为 ZIP 文件。 返回 ZIP 的路径。
set_tags	在运行上添加或修改一组标记。 未在字典中传递的标记保持不变。 还可以添加简单的字符串标记。 当这些标记作为键出现在标记字典中时，它们的值为“无”。 有关详细信息，请参阅标记和查找运行。
start	将运行标记为已启动。 当运行已由另一个行动者创建时，这通常用于高级方案。
submit_child	提交试验并返回活动子运行。
tag	使用一个字符串键和可选字符串值标记运行。
take_snapshot	保存输入文件或文件夹的快照。
upload_file	将文件上传到运行记录。
upload_files	将文件上传到运行记录。
upload_folder	将指定的文件夹上传到给定的前缀名称。
wait_for_completion	等待此运行完成。 返回等待后的状态对象。

add_properties

向运行添加不可变属性。

标签和属性（都是 dict[str, str]）的可变性不同。 属性是不可变的，因此它们将创建一条永久记录用于审核目的。 标记是可变的。 有关使用标记和属性的详细信息，请参阅标记和查找运行。

add_properties(properties)

参数

名称	说明
properties 必需	dict 存储在运行对象中的隐藏属性。

add_type_provider

存储在运行历史记录中的自定义运行类型的扩展性挂钩。

static add_type_provider(runtype, run_factory)

参数

名称	说明
runtype 必需	str 将为其调用工厂的 Run.type 的值。 示例包括“hyperdrive”或“azureml.scriptrun”，但可以使用自定义类型进行扩展。
run_factory 必需	<xref:function> 具有签名的函数 (Experiment, RunDto) -> 列出运行时要调用的运行。

cancel

将运行标记为已取消。

如果存在设置了 cancel_uri 字段的关联作业，则也会终止该作业。

cancel()

child_run

创建子运行。

child_run(name=None, run_id=None, outputs=None)

参数

名称	说明
name	str 子运行的可选名称，通常为某个“部分”指定。 默认值: None
run_id	str 子级的可选运行 ID，否则会自动生成。 通常未设置此参数。 默认值: None
outputs	str 用于跟踪子级的可选输出目录。 默认值: None

返回

类型	说明
Run	子运行。

注解

这用于将运行的一部分隔离到子部分中。 这可以针对运行的可识别“部分”来完成，这些“部分”有利于分离，或捕获跨子过程交互的独立指标。

如果为子运行设置了输出目录，该目录的内容将在子级完成后上传到子运行记录。

clean

删除与运行配置中指定的目标上的当前运行对应的文件。

clean()

返回

类型	说明
list	已删除文件的列表。

complete

等待任务队列得到处理。

然后，运行被标记为已完成。 这通常用于交互式笔记本方案。

complete(_set_status=True)

参数

名称	说明
_set_status	bool 指示是否发送状态事件进行跟踪。 默认值: True

create_children

创建一个或多个子运行。

create_children(count=None, tag_key=None, tag_values=None)

参数

名称	说明
count	int 要创建的子级的可选数目。 默认值: None
tag_key	str 可选键，用于填充所有创建的子级中的 Tags 条目。 默认值: None
tag_Values 必需	可选值列表，这些值将映射到创建的运行列表的 Tags[tag_key] 上。
tag_values	默认值: None

返回

类型	说明
list[Run]	子运行的列表。

注解

必须指定参数 count 或参数 tag_key 和 tag_values。

download_file

从存储中下载关联的文件。

download_file(name, output_file_path=None, _validate_checksum=False)

参数

名称	说明
name 必需	str 要下载的项目的名称。
output_file_path 必需	str 要存储项目的本地路径。

download_files

如果未指定前缀，则从给定的存储前缀（文件夹名称）或整个容器中下载文件。

download_files(prefix=None, output_directory=None, output_paths=None, batch_size=100, append_prefix=True, timeout_seconds=None)

参数

名称	说明
prefix 必需	str 要从中下载所有项目的容器中的文件路径前缀。
output_directory 必需	str 可选目录，所有项目路径都将其用作前缀。
output_paths 必需	[str] 用于存储下载的项目的可选文件路径。 应是唯一的，并且与路径的长度匹配。
batch_size 必需	int 每批要下载的文件数。 默认值为 100 个文件。
append_prefix 必需	bool 可选标志，确定是否从最终输出文件路径追加指定的前缀。 如果为 False，则从输出文件路径中删除前缀。
timeout_seconds 必需	int 下载文件的超时。

fail

将运行标记为失败。

（可选）使用传递给 error_details 的消息或异常设置运行的 Error 属性。

fail(error_details=None, error_code=None, _set_status=True)

参数

名称	说明
error_details	str 或 BaseException 错误的可选详细信息。 默认值: None
error_code	str 错误分类的错误的可选错误代码。 默认值: None
_set_status	bool 指示是否发送状态事件进行跟踪。 默认值: True

flush

等待任务队列得到处理。

flush(timeout_seconds=300)

参数

名称	说明
timeout_seconds	int 等待处理任务队列的时间（以秒为单位）。 默认值: 300

get

获取此工作区的运行及其运行 ID。

static get(workspace, run_id)

参数

名称	说明
workspace 必需	Workspace 包容性工作区。
run_id 必需	string 运行 ID。

返回

类型	说明
Run	提交的运行。

get_all_logs

将运行的所有日志下载到目录。

get_all_logs(destination=None)

参数

名称	说明
destination	str 用于存储日志的目标路径。 如果未指定，则会在项目目录中创建一个名为运行 ID 的目录。 默认值: None

返回

类型	说明
list	已下载日志的名称列表。

get_children

获取由指定的筛选器选择的当前运行的所有子级。

get_children(recursive=False, tags=None, properties=None, type=None, status=None, _rehydrate_runs=True)

参数

名称	说明
recursive	bool 指示是否递归所有后代。 默认值: False
tags	str 或 dict 如果指定，则返回与指定的 "tag" 或 {"tag": "value"} 匹配的运行。 默认值: None
properties	str 或 dict 如果指定，则返回与指定的 "property" 或 {"property": "value"} 匹配的运行。 默认值: None
type	str 如果指定，则返回与此类型匹配的运行。 默认值: None
status	str 如果指定，则返回具有指定状态 "status" 的运行。 默认值: None
_rehydrate_runs	bool 指示是实例化原始类型的运行还是实例化基运行。 默认值: True

返回

类型	说明
list	Run 对象的列表。

get_context

返回当前服务上下文。

使用此方法检索当前服务上下文中的记录指标和上传文件。 如果 allow_offline 为 True（默认值），则针对运行对象的操作将打印到标准输出。

get_context(allow_offline=True, used_for_context_manager=False, **kwargs)

参数

名称	说明
cls 必需	指示类方法。
allow_offline	bool 允许服务上下文回退到脱机模式，以便可以在本地测试训练脚本，而无需使用 SDK 提交作业。 默认值为 True。 默认值: True
kwargs 必需	dict 其他参数的字典。
used_for_context_manager	默认值: False

返回

类型	说明
Run	提交的运行。

注解

此函数通常用于检索脚本内经过身份验证的运行对象，以通过experiment.submit() 提交执行。 此运行对象既是与 Azure 机器学习服务通信的经过身份验证的上下文，也是包含指标、文件（项目）和模型的概念容器。

   run = Run.get_context() # allow_offline=True by default, so can be run locally as well
   ...
   run.log("Accuracy", 0.98)
   run.log_row("Performance", epoch=e, error=err)

get_detailed_status

提取运行的最新状态。 如果运行的状态为“已排队”，则会显示详细信息。

get_detailed_status()

返回

类型	说明
dict[str, str]	最新状态和详细信息

注解

• 状态：运行的当前状态。 与 get_status() 返回的值相同。

• 详细信息：当前状态的详细信息。

   run = experiment.submit(config)
   details = run.get_detailed_status()
   # details = {
   #     'status': 'Queued',
   #     'details': 'Run requested 1 node(s). Run is in pending status.',
   # }

get_details

获取运行的定义、状态信息、当前日志文件和其他详细信息。

get_details()

返回

类型	说明
dict[str, str]	返回运行的详细信息

注解

返回的字典包含以下键值对：

• runId：此运行的 ID。

• 目标

• 状态：运行的当前状态。 与 get_status() 返回的值相同。

• startTimeUtc：启动此运行的 UTC 时间，采用 ISO8601。

• endTimeUtc：完成此运行的 UTC 时间（已完成或失败），采用 ISO8601。

  如果运行仍在进行，则此键不存在。

• 属性：与运行关联的不可变键值对。 默认属性包括运行的快照 ID 和有关从中创建运行的 git 存储库的信息（如果有）。 可以使用 add_properties 将其他属性添加到运行中。

• inputDatasets：与运行关联的输入数据集。

• inputDatasets：与运行关联的输入数据集。

• logFiles

• submittedBy

   run = experiment.start_logging()

   details = run.get_details()
   # details = {
   #     'runId': '5c24aa28-6e4a-4572-96a0-fb522d26fe2d',
   #     'target': 'sdk',
   #     'status': 'Running',
   #     'startTimeUtc': '2019-01-01T13:08:01.713777Z',
   #     'endTimeUtc': '2019-01-01T17:15:65.986253Z',
   #     'properties': {
   #         'azureml.git.repository_uri': 'https://example.com/my/git/repo',
   #         'azureml.git.branch': 'master',
   #         'azureml.git.commit': '7dc972657c2168927a02c3bc2b161e0f370365d7',
   #         'azureml.git.dirty': 'True',
   #         'mlflow.source.git.repoURL': 'https://example.com/my/git/repo',
   #         'mlflow.source.git.branch': 'master',
   #         'mlflow.source.git.commit': '7dc972657c2168927a02c3bc2b161e0f370365d7',
   #         'ContentSnapshotId': 'b4689489-ce2f-4db5-b6d7-6ad11e77079c'
   #     },
   #     'inputDatasets': [{
   #         'dataset': {'id': 'cdebf245-701d-4a68-8055-41f9cf44f298'},
   #         'consumptionDetails': {
   #             'type': 'RunInput',
   #             'inputName': 'training-data',
   #             'mechanism': 'Mount',
   #             'pathOnCompute': '/mnt/datasets/train'
   #         }
   #     }],
   #     'outputDatasets': [{
   #         'dataset': {'id': 'd04e8a19-1caa-4b1f-b318-4cbff9af9615'},
   #         'outputType': 'RunOutput',
   #         'outputDetails': {
   #             'outputName': 'training-result'
   #         }
   #     }],
   #     'runDefinition': {},
   #     'logFiles': {},
   #     'submittedBy': 'Alan Turing'
   # }

get_details_with_logs

返回运行状态，包括日志文件内容。

get_details_with_logs()

返回

类型	说明
dict	返回包含日志文件内容的运行的状态。

get_environment

获取此运行使用的环境定义。

get_environment()

返回

类型	说明
Environment	返回环境对象。

get_file_names

列出与运行关联中存储的文件。

get_file_names()

返回

类型	说明
list[str]	现有项目的路径列表

get_metrics

检索记录到运行的指标。

如果 recursive 为 True（默认值为 False），则提取给定运行的子树中运行的指标。

get_metrics(name=None, recursive=False, run_type=None, populate=False)

参数

名称	说明
name	str 指标的名称。 默认值: None
recursive	bool 指示是否递归所有后代。 默认值: False
run_type	str 默认值: None
populate	bool 指示是否提取链接到指标的外部数据的内容。 默认值: False

返回

类型	说明
dict	包含用户指标的字典。

注解

   run = experiment.start_logging() # run id: 123
   run.log("A", 1)
   with run.child_run() as child: # run id: 456
       child.log("A", 2)

   metrics = run.get_metrics()
   # metrics = { 'A': 1 }

   metrics = run.get_metrics(recursive=True)
   # metrics = { '123': { 'A': 1 }, '456': { 'A': 2 } } note key is runId

get_properties

从服务中提取运行的最新属性。

get_properties()

返回

类型	说明
dict	运行的属性。

注解

属性是系统生成的不可变信息，例如使用 add_properties 方法添加的持续时间、执行日期、用户和自定义属性。 有关详细信息，请参阅标记和查找运行。

在向 Azure 机器学习提交作业时，如果源文件存储在本地 git 存储库中，则有关存储库的信息将存储为属性。 创建运行或调用 Experiment.submit 时，将添加这些 git 属性。 有关 git 属性的详细信息，请参阅 Azure 机器学习的 Git 集成。

get_secret

从运行的上下文中获取机密值。

获取提供的名称的机密值。 机密名称引用存储在与工作区关联的 Azure Key Vault 中的值。 有关使用机密的示例，请参阅在训练运行中使用机密。

get_secret(name)

参数

名称	说明
name 必需	str 要返回其机密的机密名称。

返回

类型	说明
str	机密值。

get_secrets

获取给定机密名称列表的机密值。

获取所提供名称列表的已找到和未找到机密的字典。 每个机密名称引用存储在与工作区关联的 Azure 密钥保管库中的值。 有关使用机密的示例，请参阅在训练运行中使用机密。

get_secrets(secrets)

参数

名称	说明
secrets 必需	list[str] 要返回其机密值的机密名称的列表。

返回

类型	说明
dict[str: str]	返回已找到和未找到的机密的字典。

get_snapshot_id

获取最新的快照 ID。

get_snapshot_id()

返回

类型	说明
str	最新的快照 ID。

get_status

提取运行的最新状态。

返回的常见值包括“正在运行”、“已完成”和“失败”。

get_status()

返回

类型	说明
str	最新状态。

注解

• 未启动 - 这是客户端运行对象在云提交之前所处的临时状态。

• 正在启动 - 运行已开始在云中处理。 调用方此时具有运行 ID。

• 正在预配 - 在为给定的作业提交创建按需计算时返回。

• 正在准备 - 正在准备运行环境：

  • Docker 映像生成

  • Conda 环境设置

• 已排队 - 作业已在计算目标中排队。 例如，在 BatchAI 中，作业处于已排队状态

  等待所有请求的节点准备就绪时。

• 正在运行 - 作业已开始在计算目标中运行。

• 正在完成 - 用户代码已完成，并且运行处于后期处理阶段。

• 已请求取消 - 已请求取消作业。

• 已完成 - 运行已成功完成。 这包括用户代码和运行

  后期处理阶段。

• 失败 - 运行失败。 通常，运行上的 Error 属性会提供有关原因的详细信息。

• 已取消 - 遵循取消请求并指示运行现已成功取消。

• 未响应 - 对于启用了检测信号的运行，最近未发送任何检测信号。

   run = experiment.submit(config)
   while run.get_status() not in ['Completed', 'Failed']: # For example purposes only, not exhaustive
       print('Run {} not in terminal state'.format(run.id))
       time.sleep(10)

get_submitted_run

已弃用。 使用 get_context。

获取此试验的已提交运行。

get_submitted_run(**kwargs)

返回

类型	说明
Run	提交的运行。

get_tags

从服务中提取运行上的最新可变标记集。

get_tags()

返回

类型	说明
dict	存储在运行对象上的标记。

list

获取可选筛选器指定的试验中的运行列表。

static list(experiment, type=None, tags=None, properties=None, status=None, include_children=False, _rehydrate_runs=True)

参数

名称	说明
experiment 必需	Experiment 包容性试验。
type	str 如果指定，则返回与指定类型匹配的运行。 默认值: None
tags	str 或 dict 如果指定，则返回与指定的 "tag" 或 {"tag": "value"} 匹配的运行。 默认值: None
properties	str 或 dict 如果指定，则返回与指定的 "property" 或 {"property": "value"} 匹配的运行。 默认值: None
status	str 如果指定，则返回具有指定状态 "status" 的运行。 默认值: None
include_children	bool 如果设置为 true，则提取所有运行，而不仅是顶级运行。 默认值: False
_rehydrate_runs	bool 如果设置为 True（默认情况下），将使用已注册的提供程序重新实例化该类型的对象，而不是基运行。 默认值: True

返回

类型	说明
list[Run]	运行的列表。

注解

下面的代码示例演示 list 方法的一些用法。

   favorite_completed_runs = Run.list(experiment, status='Completed', tags='favorite')

   all_distinct_runs = Run.list(experiment)
   and_their_children = Run.list(experiment, include_children=True)

   only_script_runs = Run.list(experiment, type=ScriptRun.RUN_TYPE)

list_by_compute

获取可选筛选器指定的计算中的运行列表。

static list_by_compute(compute, type=None, tags=None, properties=None, status=None)

参数

名称	说明
compute 必需	ComputeTarget 包容性计算。
type	str 如果指定，则返回与指定类型匹配的运行。 默认值: None
tags	str 或 dict 如果指定，则返回与指定的 "tag" 或 {"tag": "value"} 匹配的运行。 默认值: None
properties	str 或 dict 如果指定，则返回与指定的 "property" 或 {"property": "value"} 匹配的运行。 默认值: None
status	str 如果指定，则返回具有指定状态 "status" 的运行。 允许的值仅为“正在运行”和“已排队”。 默认值: None

返回

类型	说明
<xref:builtin.generator>	~_restclient.models.RunDto 的生成器

log

使用给定名称在运行中记录指标值。

log(name, value, description='', step=None)

参数

名称	说明
name 必需	str 指标的名称。
value 必需	要发布给服务的值。
description 必需	str 可选的指标说明。
step	int 可选轴，用于指定指标内的值顺序。 默认值: None

注解

在运行中记录某个指标会导致在试验中的运行记录中存储该指标。 可在一次运行中多次记录同一指标，其结果被视为该指标的一个矢量。 如果为指标指定了步骤，必须为所有值指定该步骤。

log_accuracy_table

将准确度表记录到项目存储。

准确度表指标是一种多用途的非标量指标，可用于生成多种类型的折线图，这些图在预测概率的空间内持续变化。 这些图的示例包括 ROC、精准率-召回率以及提升曲线。

准确度表的计算类似于 ROC 曲线的计算。 ROC 曲线将真正率和假正率存储在许多不同的概率阈值处。 准确度表将真正、假正、真负和假负的原始数量存储在许多不同的概率阈值处。

有两种方法用于选择阈值：“概率”和“百分位数”。它们的不同之处在于从预测概率空间中采样的方式。

概率阈值是 0 到 1 之间均匀间隔的阈值。 如果 NUM_POINTS 为 5，则概率阈值为 [0.0, 0.25, 0.5, 0.75, 1.0]。

百分位数阈值根据预测概率的分布进行间隔。 每个阈值对应于概率阈值处数据的百分位数。 例如，如果 NUM_POINTS 为 5，则第一个阈值将位于第 0 个百分位数处，第二个阈值位于第 25 个百分位数处，第三个阈值位于第 50 个百分位数处，以此类比。

概率表和百分位数表都是三维列表，其中第一个维度表示类标签，第二个维度表示一个阈值的样本（使用 NUM_POINTS 缩放），第三个维度始终有 4 个值：TP、FP、TN、FN，并且始终按该顺序显示。

混淆值（TP、FP、TN、FN）是使用一对多策略计算的。 请参阅以下链接了解更多详细信息：https://en.wikipedia.org/wiki/Multiclass_classification

N = 验证数据集中的样本数（示例中为 200）M = 阈值数 = 从概率空间中获取的样本数（示例中为 5）C = 完整数据集中的类数（示例中为 3）

准确度表的一些不变量：

• 所有类的所有阈值的 TP + FP + TN + FN = N
• TP + FN 在任何类的所有阈值处都是相同的
• TN + FP 在任何类的所有阈值处都是相同的
• 概率表和百分位数表的形状为 [C, M, 4]

注意：M 可以是任何值并控制图表的分辨率。这独立于数据集，在计算指标时定义，并占用存储空间、计算时间和分辨率。

类标签应为字符串，混淆值应为整数，阈值应为浮点数。

log_accuracy_table(name, value, description='')

参数

名称	说明
name 必需	str 准确度表的名称。
value 必需	str 或 dict 包含名称、版本和数据属性的 JSON。
description 必需	str 可选的指标说明。

注解

有效 JSON 值的示例：

   {
       "schema_type": "accuracy_table",
       "schema_version": "1.0.1",
       "data": {
           "probability_tables": [
               [
                   [82, 118, 0, 0],
                   [75, 31, 87, 7],
                   [66, 9, 109, 16],
                   [46, 2, 116, 36],
                   [0, 0, 118, 82]
               ],
               [
                   [60, 140, 0, 0],
                   [56, 20, 120, 4],
                   [47, 4, 136, 13],
                   [28, 0, 140, 32],
                   [0, 0, 140, 60]
               ],
               [
                   [58, 142, 0, 0],
                   [53, 29, 113, 5],
                   [40, 10, 132, 18],
                   [24, 1, 141, 34],
                   [0, 0, 142, 58]
               ]
           ],
           "percentile_tables": [
               [
                   [82, 118, 0, 0],
                   [82, 67, 51, 0],
                   [75, 26, 92, 7],
                   [48, 3, 115, 34],
                   [3, 0, 118, 79]
               ],
               [
                   [60, 140, 0, 0],
                   [60, 89, 51, 0],
                   [60, 41, 99, 0],
                   [46, 5, 135, 14],
                   [3, 0, 140, 57]
               ],
               [
                   [58, 142, 0, 0],
                   [56, 93, 49, 2],
                   [54, 47, 95, 4],
                   [41, 10, 132, 17],
                   [3, 0, 142, 55]
               ]
           ],
           "probability_thresholds": [0.0, 0.25, 0.5, 0.75, 1.0],
           "percentile_thresholds": [0.0, 0.01, 0.24, 0.98, 1.0],
           "class_labels": ["0", "1", "2"]
       }
   }

log_confusion_matrix

将混淆矩阵记录到项目存储。

这会记录围绕 sklearn 混淆矩阵的包装器。 指标数据包含矩阵本身的类标签和二维列表。 有关如何计算指标的更多详细信息，请参阅以下链接：https://scikit-learn.org/stable/modules/generated/sklearn.metrics.confusion_matrix.html

log_confusion_matrix(name, value, description='')

参数

名称	说明
name 必需	str 混淆矩阵的名称。
value 必需	str 或 dict 包含名称、版本和数据属性的 JSON。
description 必需	str 可选的指标说明。

注解

有效 JSON 值的示例：

   {
       "schema_type": "confusion_matrix",
       "schema_version": "1.0.0",
       "data": {
           "class_labels": ["0", "1", "2", "3"],
           "matrix": [
               [3, 0, 1, 0],
               [0, 1, 0, 1],
               [0, 0, 1, 0],
               [0, 0, 0, 1]
           ]
       }
   }

log_image

在运行记录中记录图像指标。

log_image(name, path=None, plot=None, description='')

参数

名称	说明
name 必需	str 指标的名称。
path 必需	str 图像的路径或流。
plot 必需	<xref:matplotlib.pyplot> 要记录为图像的绘图。
description 必需	str 可选的指标说明。

注解

使用此方法在运行中记录图像文件或 matplotlib 绘图。 运行记录中可显示和比较这些图像。

log_list

使用给定名称将指标值的列表记录到运行中。

log_list(name, value, description='')

参数

名称	说明
name 必需	str 指标的名称。
value 必需	list 指标的值。
description 必需	str 可选的指标说明。

log_predictions

将预测记录到项目存储。

这会记录指标分数，该分数可用于将真实目标值的分布与回归任务的预测值的分布进行比较。

预测是分箱的，标准偏差是针对折线图上的误差条计算的。

log_predictions(name, value, description='')

参数

名称	说明
name 必需	str 预测的名称。
value 必需	str 或 dict 包含名称、版本和数据属性的 JSON。
description 必需	str 可选的指标说明。

注解

有效 JSON 值的示例：

   {
       "schema_type": "predictions",
       "schema_version": "1.0.0",
       "data": {
           "bin_averages": [0.25, 0.75],
           "bin_errors": [0.013, 0.042],
           "bin_counts": [56, 34],
           "bin_edges": [0.0, 0.5, 1.0]
       }
   }

log_residuals

将残差记录到项目存储。

这会记录显示回归任务残差直方图所需的数据。 残差是预测值与实际值之差。

应比计数的数量多一个边。 有关使用计数和边表示直方图的示例，请参阅 numpy 直方图文档。 https://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html

log_residuals(name, value, description='')

参数

名称	说明
name 必需	str 残差的名称。
value 必需	str 或 dict 包含名称、版本和数据属性的 JSON。
description 必需	str 可选的指标说明。

注解

有效 JSON 值的示例：

   {
       "schema_type": "residuals",
       "schema_version": "1.0.0",
       "data": {
           "bin_edges": [50, 100, 200, 300, 350],
           "bin_counts": [0.88, 20, 30, 50.99]
       }
   }

log_row

使用给定名称在运行中记录行指标。

log_row(name, description=None, **kwargs)

参数

名称	说明
name 必需	str 指标的名称。
description	str 可选的指标说明。 默认值: None
kwargs 必需	dict 其他参数的字典。 在这种情况下，为指标的列。

注解

使用 log_row 创建包含列的表指标，如 kwargs 中所述。 每个命名的参数会生成一个具有指定值的列。 可调用 log_row 一次，记录任意元组，或在循环中调用多次，生成完整表格。

   citrus = ['orange', 'lemon', 'lime']
   sizes = [ 10, 7, 3]
   for index in range(len(citrus)):
       run.log_row("citrus", fruit = citrus[index], size=sizes[index])

log_table

使用给定名称在运行中记录表格指标。

log_table(name, value, description='')

参数

名称	说明
name 必需	str 指标的名称。
value 必需	dict 指标的表值，字典，其中键是要发布给服务的列。
description 必需	str 可选的指标说明。

register_model

注册模型以用于操作化。

register_model(model_name, model_path=None, tags=None, properties=None, model_framework=None, model_framework_version=None, description=None, datasets=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None, **kwargs)

参数

名称	说明
model_name 必需	str 模型的名称。
model_path	str 模型的相对云路径，例如“outputs/modelname”。 如果未指定（无），则将 model_name 用作路径。 默认值: None
tags	dict[str, str] 要分配给模型的键值标记的字典。 默认值: None
properties	dict[str, str] 要分配给模型的键值属性的字典。 这些属性在模型创建后无法更改，但是可以添加新的键值对。 默认值: None
model_framework	str 要注册的模型的框架。 当前支持的框架：TensorFlow、ScikitLearn、Onnx、Custom、Multi 默认值: None
model_framework_version	str 已注册模型的框架版本。 默认值: None
description	str 模型的可选说明。 默认值: None
datasets	list[(str, AbstractDataset)] 元组的列表，其中第一个元素描述数据集-模型关系，第二个元素是数据集。 默认值: None
sample_input_dataset	AbstractDataset 可选。 已注册模型的示例输入数据集 默认值: None
sample_output_dataset	AbstractDataset 可选。 已注册模型的示例输出数据集 默认值: None
resource_configuration	ResourceConfiguration 可选。 用于运行已注册模型的资源配置 默认值: None
kwargs 必需	dict 可选参数。

返回

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

注解

   model = best_run.register_model(model_name = 'best_model', model_path = 'outputs/model.pkl')

remove_tags

删除此运行上可变标记的列表。

remove_tags(tags)

参数

名称	说明
tags 必需	list 要删除的标记的列表。

返回

类型	说明
	存储在运行对象上的标记

restore_snapshot

将快照还原为 ZIP 文件。 返回 ZIP 的路径。

restore_snapshot(snapshot_id=None, path=None)

参数

名称	说明
snapshot_id	str 要还原的快照 ID。 如果未指定，则使用最新的。 默认值: None
path	str 保存下载的 ZIP 的路径。 默认值: None

返回

类型	说明
str	路径。

set_tags

在运行上添加或修改一组标记。 未在字典中传递的标记保持不变。

还可以添加简单的字符串标记。 当这些标记作为键出现在标记字典中时，它们的值为“无”。 有关详细信息，请参阅标记和查找运行。

set_tags(tags)

参数

名称	说明
tags 必需	dict[str] 或 str 存储在运行对象中的标记。

start

将运行标记为已启动。

当运行已由另一个行动者创建时，这通常用于高级方案。

start()

submit_child

提交试验并返回活动子运行。

submit_child(config, tags=None, **kwargs)

参数

名称	说明
config 必需	object 要提交的配置。
tags	dict 要添加到已提交运行的标记，例如 {"tag": "value"}。 默认值: None
kwargs 必需	dict 提交函数中用于配置的其他参数。

返回

类型	说明
Run	运行对象。

注解

提交是对 Azure 机器学习平台的异步调用，用于在本地或远程硬件上执行试运行。 根据配置，提交将自动准备执行环境、执行代码，以及将源代码和结果捕获到试验的运行历史记录中。

若要提交试验，首先需要创建描述试验运行方法的配置对象。 该配置取决于所需的试用类型。

如何使用 ScriptRunConfig 从本地计算机提交子试验的示例如下所示：

   from azureml.core import ScriptRunConfig

   # run a trial from the train.py code in your current directory
   config = ScriptRunConfig(source_directory='.', script='train.py',
       run_config=RunConfiguration())
   run = parent_run.submit_child(config)

   # get the url to view the progress of the experiment and then wait
   # until the trial is complete
   print(run.get_portal_url())
   run.wait_for_completion()

有关如何配置运行的详细信息，请参阅 submit。

tag

使用一个字符串键和可选字符串值标记运行。

tag(key, value=None)

参数

名称	说明
key 必需	str 标记键
value	str 标记的可选值 默认值: None

注解

运行中的标记和属性都是字符串 -> 字符串的字典。 它们之间的区别在于可变性：可以设置、更新和删除标记，但只能添加属性。 这使得属性更适用于系统/工作流相关的行为触发器，而标记通常是面向用户的并且对试验使用者有意义。

   run = experiment.start_logging()
   run.tag('DeploymentCandidate')
   run.tag('modifiedBy', 'Master CI')
   run.tag('modifiedBy', 'release pipeline') # Careful, tags are mutable

   run.add_properties({'BuildId': os.environ.get('VSTS_BUILD_ID')}) # Properties are not

   tags = run.get_tags()
   # tags = { 'DeploymentCandidate': None, 'modifiedBy': 'release pipeline' }

take_snapshot

保存输入文件或文件夹的快照。

take_snapshot(file_or_folder_path)

参数

名称	说明
file_or_folder_path 必需	str 包含运行源代码的文件或文件夹。

返回

类型	说明
str	返回快照 ID。

注解

快照旨在成为用于执行试验运行的源代码。 这些内容与运行一起存储，以便将来可以复制运行试用。

注意

调用 submit 时，会自动拍摄快照。 通常，只有交互式（笔记本）运行才需要 take_snapshot 方法。

upload_file

将文件上传到运行记录。

upload_file(name, path_or_stream, datastore_name=None)

参数

名称	说明
name 必需	str 要上传的文件的名称。
path_or_stream 必需	str 要上传的文件的相对本地路径或流。
datastore_name 必需	str 可选数据存储名称

返回

类型	说明
ResourceProperties

注解

   run = experiment.start_logging()
   run.upload_file(name='important_file', path_or_stream="path/on/disk/file.txt")

注意

在指定输出目录中自动运行捕获文件，对于大多数运行类型，该目录默认为 "./outputs"。 仅当需要上传其他文件或未指定输出目录时使用 upload_file。

upload_files

将文件上传到运行记录。

upload_files(names, paths, return_artifacts=False, timeout_seconds=None, datastore_name=None)

参数

名称	说明
names 必需	list 要上传的文件的名称。 如果设置，还必须设置路径。
paths 必需	list 要上传的文件的相对本地路径。 如果设置，则名称是必需的。
return_artifacts 必需	bool 指示应为上传的每个文件返回项目对象。
timeout_seconds 必需	int 上传文件的超时。
datastore_name 必需	str 可选数据存储名称

注解

upload_files 对单独文件具有与 upload_file 相同的效果，但是使用 upload_files 时，具有性能和资源利用率优势。

   import os

   run = experiment.start_logging()
   file_name_1 = 'important_file_1'
   file_name_2 = 'important_file_2'
   run.upload_files(names=[file_name_1, file_name_2],
                       paths=['path/on/disk/file_1.txt', 'other/path/on/disk/file_2.txt'])

   run.download_file(file_name_1, 'file_1.txt')

   os.mkdir("path")  # The path must exist
   run.download_file(file_name_2, 'path/file_2.txt')

注意

在指定输出目录中自动运行捕获文件，对于大多数运行类型，该目录默认为“./outputs”。 仅当需要上传其他文件或未指定输出目录时使用 upload_file。

upload_folder

将指定的文件夹上传到给定的前缀名称。

upload_folder(name, path, datastore_name=None)

参数

名称	说明
name 必需	str 要上传的文件的文件夹的名称。
folder 必需	str 要上传的文件夹的相对本地路径。
datastore_name 必需	str 可选数据存储名称

注解

   run = experiment.start_logging()
   run.upload_folder(name='important_files', path='path/on/disk')

   run.download_file('important_files/existing_file.txt', 'local_file.txt')

注意

在指定输出目录中自动运行捕获文件，对于大多数运行类型，该目录默认为“./outputs”。 仅当需要上传其他文件或未指定输出目录时使用 upload_folder。

wait_for_completion

等待此运行完成。 返回等待后的状态对象。

wait_for_completion(show_output=False, wait_post_processing=False, raise_on_error=True)

参数

名称	说明
show_output	bool 指示是否在 sys.stdout 上显示运行输出。 默认值: False
wait_post_processing	bool 指示是否在运行完成后等待后处理完成。 默认值: False
raise_on_error	bool 指示当运行处于失败状态时是否引发错误。 默认值: True

返回

类型	说明
dict	状态对象。

属性

description

返回运行说明。

该运行的可选说明是用户指定的字符串，可用于描述运行。

返回

类型	说明
str	运行说明。

display_name

返回运行显示名称。

该运行的可选名称是用户指定的字符串，可用于以后识别运行。

返回

类型	说明
str	运行显示名称。

experiment

获取包含运行的试验。

返回

类型	说明
Experiment	检索与运行对应的试验。

id

获取运行 ID。

运行的 ID 是包容性试验中唯一的标识符。

返回

类型	说明
str	运行 ID。

name

已弃用。 使用 display_name。

运行的可选名称是用户指定的字符串，可用于以后识别运行。

返回

类型	说明
str	运行 ID。

number

获取运行编号。

单调递增的数字，表示试验中的运行顺序。

返回

类型	说明
int	运行编号。

parent

从服务中提取此运行的父级运行。

运行可以具有可选的父级，从而生成运行的潜在树层次结构。 若要将指标记录到父级运行，请使用父级对象的 log 方法，例如 run.parent.log()。

返回

类型	说明
Run	父级运行或无（如果未设置父级运行）。

properties

返回此运行的不可变属性。

返回

类型	说明
dict[str], str	运行的本地缓存属性。

注解

属性包括不可变的系统生成信息，例如持续时间、执行日期、用户等。

status

返回运行对象的状态。

tags

返回此运行中的可变标记集。

返回

类型	说明
dict	存储在运行对象上的标记。

type

获取运行类型。

指示如何创建或配置运行。

返回

类型	说明
str	运行类型。