检查流和结果

Metaflow 提供了一个客户端 API，用于检查过去运行的结果。它特别适合在笔记本中使用。如果您想在笔记本或其他应用中运行流程，请参见 管理流程。

本文件提供了客户端API的概述。请参阅客户端API参考页面中的完整API。

对象层次结构​

请注意，Client API中的所有操作都受到当前命名空间的过滤，如组织结果中所述。如果您没有得到预期的结果，请确保您在正确的命名空间中。Client API会咨询元数据服务以获取结果，因此请确保客户端已正确配置以使用正确的元数据提供者。

您可以直接从metaflow包中导入上述显示的任何对象，如下所示（例如）：

from metaflow import Run

根对象 Metaflow 可以简单地实例化为

from metaflow import Metaflow
mf = Metaflow()

这是所有其他对象的入口点。例如，您可以列出过去运行的所有流，使用:

from metaflow import Metaflow
print(Metaflow().flows)

浏览对象层次结构​

上面列出的每个对象都遵循一致的接口。所有下面的操作在所有对象中都可用，而不仅仅是在演示的对象中。

列出子项​

您可以通过遍历父对象简单列出任何父对象的子对象：

from metaflow import Flow
flow = Flow('HelloFlow')
runs = list(flow)

如预期，这也可以工作：

from metaflow import Flow
flow = Flow('HelloFlow')
for run in flow:
    print(run)

访问特定子项​

您可以使用方括号访问特定的子项，类似于字典中的键查找。请注意，键始终是字符串（即使它们是数值 ID）：

from metaflow import Flow
flow = Flow('HelloFlow')
run = flow['2']

通过其地址访问特定对象​

除了从根节点向下导航之外，您还可以通过其完全限定名（称为 pathspec）直接实例化每个对象。请注意，此操作也受当前命名空间的限制，如在 组织结果 中所述；简而言之，您将无法访问不是当前命名空间的 Flow；返回的错误消息将清楚地说明对象是否存在且不在命名空间中，或根本不存在。

你可以通过其名称实例化，例如，一个特定的流：

from metaflow import Flow
flow = Flow('HelloFlow')

您可以通过其运行 ID 实例化流的特定运行：

from metaflow import Run
run = Run('HelloFlow/2')

并且运行中的每一步都有它的名称：

from metaflow import Step
step = Step('HelloFlow/2/start')

访问数据​

客户端API的最典型用例之一是访问由运行产生的数据工件。每个数据工件由一个 DataArtifact 对象表示，其父对象是一个 Task。

DataArtifact 是实际值的容器对象。除了值，DataArtifact 还包括关于工件的元数据，例如它的创建时间。

通常您只对工件的值感兴趣。对于这种典型的用例，我们在Task对象中提供了一个便利属性.data。.data属性返回一个容器，该容器将任务生成的所有工件作为属性。

例如，这是访问运行中某个步骤生成的值的最短方法：

from metaflow import Step
print(Step('DebugFlow/2/a').task.data.x)

在这里，我们打印运行 2 的流程 DebugFlow 的步骤 a 中的 self.x 的值。

添加、移除和替换标签​

Metaflow 2.7.1中的新功能：您需要升级您的Metaflow库和元数据服务才能享受此功能。

每次运行都有一组标签附加，这就是用户定义的注释。您可以按照以下方式添加和删除标签：

from metaflow import Run
run = Run('HelloFlow/2')
run.add_tag('one_tag') # add one tag
run.add_tags(['another_tag', 'yet_another', 'one_tag']) # add many tags
print(run.user_tags)

这将打印 one_tag, another_tag, yet_another。请注意 one_tag 被添加了两次，但由于标签是一个集合，重复项会被忽略。

移除工作是对称进行的：

from metaflow import Run
run = Run('HelloFlow/2')
run.remove_tag('one_tag') # remove one tag
run.remove_tags(['another_tag', 'yet_another']) # remove many tags

您还可以用其他标签替换标签：

from metaflow import Run
run = Run('HelloFlow/2')
run.replace_tag('one_tag', 'better_tag')
run.replace_tags(['yet_another', 'another_tag'], ['better_tag'])

replace 调用首先移除作为第一个参数指定的标签，然后添加第二个参数中的标签。关键是，这是一个 原子操作：如果其他方在 replace 运行时列出标签，他们不会看到移除和添加之间的部分状态。

请注意，您还可以使用 tag 命令在命令行上执行这些操作，例如：

python helloflow.py tag add --run-id 2 one_tag

系统标签​

除了用户定义的标签，Metaflow 会自动为运行分配少量的 系统标签。这些标签可以用于过滤和组织运行，但不能被删除或替换为其他标签。

您可以像这样查看分配给运行的一组系统标签：

from metaflow import Run
print(Run('HelloFlow/2').system_tags)

或者系统标签和用户定义标签的并集，如下所示：

from metaflow import Run
print(Run('HelloFlow/2').tags)

常见属性​

每个对象都有以下可用属性：

• user_tags: 用户定义的标签，分配给对象的运行
• system_tags: 系统定义的（不可变）标签，分配给对象的运行
• tags: user_tags和system_tags的联合
• created_at: 创建时间戳
• parent: 父对象
• pathspec: 对象的完全限定名称
• path_components: 包含在 pathspec 中的元素的列表

与流程相关的属性​

要访问一个迭代器以获取运行并按标签过滤，请使用 runs() 方法。有关更多细节，请参见 Tagging。

Flow 有两个额外属性与确定流程的最新运行相关。 注意，返回的任何 Run 将在当前命名空间中。

• latest_run: 最新运行的Run（无论其是否已完成或是否成功）
• latest_successful_run: Run 最新成功（因此已完成）运行的运行。

与运行相关的属性​

要访问运行步骤的迭代器并按标签过滤，请使用steps()方法。有关详细信息，请参见标记。

Run 还具有一些额外属性，以便于访问常用信息：

• data: 访问该运行的最终任务的data对象的快速方式。换句话说，这是访问流程结束时产生的数据的最快方式。
• successful: 一个布尔值，指示运行是否成功完成。注意，如果运行尚未完成（即：仍在进行中），这将返回 False。
• finished: 一个布尔值，指示运行是否完成。返回的值将是 True，无论运行是否成功。
• finished_at: 一个表示运行完成时间的日期时间对象。如果运行尚未完成，则为None
• code: 在某些情况下，运行时使用的代码会被保存和持久化；这允许您访问此代码。
• end_task: 运行中最后一步的Task对象的快捷方式。
• trigger: 有关事件的信息，这些事件触发了此次运行，如果可用的话。

与步骤相关的属性​

一个 Step 通常只有一个 Task。如果它是一个 foreach 步骤，则一个 Step 将有多个 Task 对象作为其子项；每个 Task 将对应于 Step 的一次执行。

要访问一个步骤的任务迭代器并按标签进行过滤，请使用 tasks() 方法。有关更多详细信息，请参阅 Tagging。

Step 还有一些额外的属性：

• task: 方便的方法，用于返回与此 Step 关联的唯一 Task。如果 一个 Step 有多个 Task，则将返回其中的任何一个（不保证顺序）。
• finished_at: 一个日期时间对象，表示步骤的完成时间。当所有任务完成时，该步骤完成。
• environment_info: 一个包含执行环境元数据的字典对象。 查看依赖项以获取更多详细信息。

与任务相关的属性​

由于Task是在Metaflow中的实际执行单元，这些对象包含最丰富的属性集：

• data：一个方便的方法来访问由这个 Task 产生的所有数据。有关更多信息，请参见 Accessing data。
• artifacts：一个方便的方法来访问由这个 Task 生成的所有 DataArtifact 对象。请参见 访问数据。
• successful: 一个布尔值，指示此 Task 是否成功完成。
• finished: 一个布尔值，指示该 Task 是否完成。
• exception: 如果这个 Task 抛出了一个异常（即：它没有成功完成），它将被包含在这里。
• finished_at: 一个日期时间对象，表示此 Task 的完成时间。
• stdout: 一个包含该 Task 的标准输出的字符串。
• stderr: 一个包含此Task标准错误的字符串。
• code: 用于执行此 Task 的代码（如果可用）。
• environment_info: 一个包含执行环境元数据的字典对象。 查看Dependencies以获取更多细节。

这是一个示例：

from metaflow import Step
step = Step('DebugFlow/2/a')
if step.task.successful:
    print(step.task.finished_at)

元数据提供者​

客户端 API 依赖于元数据服务来适当地收集结果。Metaflow 支持本地模式 (.metaflow 目录在您的文件系统上) 和远程模式。

from metaflow import get_metadata, metadata

# Fetch currently configured metadata provider
get_metadata()

# Configure Client to use local metadata provider globally
metadata('/Users/bob/metaflow')

# Configure Client to use remote metadata provider globally
metadata('https://localhost:5000/mymetaflowservice')

请注意，更改元数据提供者是一个全局操作，所有后续的客户端操作将使用指定的元数据提供者。