基本概念¶

项目结构¶

TorchX 中的顶级模块是：

torchx.specs：应用程序规范（作业定义）API
torchx.components：预定义（内置）应用程序规格
torchx.runner：给定一个应用程序规范，将应用程序作为 Scheduler 上的 Job 提交
torchx.schedulers：运行程序支持的后端作业计划程序
torchx.pipelines：将给定应用程序规范转换为 ML 管道平台中的“阶段”的适配器
torchx.runtime：可在编写应用程序（不是 App Spec）中使用的 util 和 abstraction 库
torchx.cli：CLI 工具

下面是一个 UML 图

概念¶

应用定义¶

在 TorchX 中，an 只是一个定义为实际应用。在调度程序行话中，这是 a 和 a Kubernetes 中的类似概念是 .为了消除 application 二进制文件（logic）和 spec 中，我们通常将 TorchX 称为 “app spec” 或 . 是通用接口，允许您将应用程序作为独立作业运行或作为 ML 管道中的一个阶段。AppDefJobDefinitionspec.yamlAppDefspecs.AppDefspecs.AppDeftorchx.runnertorchx.pipelines

下面是一个与 “hello world” 相呼应的简单示例specs.AppDef

import torchx.specs as specs

specs.AppDef(
   name="echo",
   roles=[
       specs.Role(
           name="echo",
           entrypoint="/bin/echo",
           image="/tmp",
           args=["hello world"],
           num_replicas=1
       )
   ]
)

如您所见，是一个纯 python 数据类，它只需将主二进制文件（entryPoint）的名称编码，将参数编码为传递给它，以及其他一些运行时参数，例如有关要在其中运行的容器的信息（）。specs.AppDefnum_replicasentrypoint=/bin/echo

应用程序规范非常灵活，可以对各种应用程序拓扑的规范进行编码。例如，表示应用程序是分布式的。指定 multiple 可以表示非同构分布式应用程序，例如需要单个 “协调者”和许多“工人”。num_replicas > 1specs.Roles

请参阅 API 文档以了解更多信息。torchx.specs

使 App Spec 灵活的原因也使其具有许多领域。好处新闻是，在大多数情况下，您不必从头开始构建 App Spec。相反，您将使用一个名为的模板化应用程序规范。components

组件¶

TorchX 中的组件只是一个模板化的 .您可以将它们视为方便的 “工厂方法”。spec.AppDefspec.AppDef

注意

与应用程序不同，组件不会映射到实际的 python 数据类。相反，返回 an 的工厂函数称为组件。spec.AppDef

应用程序规范的模板化粒度各不相同。部分组件例如上面的示例是 ready-to-run的，这意味着它们具有硬编码的应用程序二进制文件。其他的，例如（分布式数据并行） specs 仅指定应用程序的拓扑。下面是一种可能的模板化指定同构节点拓扑的 ddp 样式训练器应用程序规范：echoddp

import torchx.specs as specs

def ddp(jobname: str, nnodes: int, image: str, entrypoint: str, *script_args: str):
   single_gpu = specs.Resources(cpu=4, gpu=1, memMB=1024)
   return specs.AppDef(
           name=jobname,
           roles=[
               specs.Role(
                   name="trainer",
                   entrypoint=entrypoint,
                   image=image,
                   resource=single_gpu,
                   args=script_args,
                   num_replicas=nnodes
               )
           ]
   )

如您所见，参数化级别完全取决于组件作者。而创建组件的工作量不超过编写 Python 函数。不要试图通过以下方式过度泛化组件参数化所有内容。组件易于创建且成本低廉，根据重复的用例创建任意数量的文件。

专业提示 1：由于组件是 python 函数，因此组件组成可以通过 Python 函数组合而不是对象组合来实现。但是，我们不建议为了可维护性而进行组件组合 目的。

专业提示 2：要定义组件之间的依赖关系，请使用流水线 DSL。请参阅下面的 Pipeline Adapters 部分，了解 TorchX 组件如何用于管道的上下文中。

在编写您自己的组件之前，请浏览 TorchX 附带的组件库以查看是否符合您的需求。

运行程序和计划程序¶

A 完全符合您的预期 - 给定应用程序规范通过 Job Scheduler 将应用程序作为 Job 启动到集群上。Runner

在 TorchX 中有两种方法可以访问 runner：

命令行界面：torchx run ~/app_spec.py
编程：torchx.runner.get_runner().run(appspec)

有关运行程序可以的调度程序列表，请参阅 Schedulers 启动应用程序到。

管道适配器¶

虽然运行器将组件作为独立作业启动，但可以将组件插入 ML 管道/工作流。对于特定目标管道平台（例如 kubeflow 管道）、TorchX 定义一个适配器，该适配器将 TorchX 应用程序规范转换为任何 “stage” 表示形式在 Target Platform 中。例如，适用于 kubeflow pipelines 的适配器将 App Spec 转换为 a（或者更准确地说，是 KFP “component spec” yaml）。torchx.pipelinestorchx.pipelines.kfpkfp.ContainerOp

在大多数情况下，应用程序规范会映射到管道中的“阶段”（或节点）。然而，高级组件，尤其是那些具有微型控制流的组件它自己的（例如 HPO）可以映射到 “sub-pipeline” 或 “inline-pipeline”。这些高级组件如何映射到管道的确切语义取决于 Target Pipeline Platform。例如，如果 pipeline DSL 允许从上游动态地向 pipeline 添加阶段阶段，则 TorchX 可以利用此功能来“内联”该 sub-pipeline 连接到主管道。TorchX 通常会尽力适应 App 规范添加到 Target Pipeline Platform 中最规范的表示形式。

有关支持的管道平台的列表，请参阅 Pipelines。

运行¶

重要

torchx.runtime绝不是使用 TorchX 的必要条件。如果您的基础设施是固定的，并且您不需要您的应用程序为了在不同类型的调度器和管道之间可移植，您可以跳过此部分。

您的应用程序（不是 app spec，而是实际的 app 二进制文件）的依赖项为零添加到 TorchX（例如不使用 TorchX，而是使用 Component 可以为其创建）。/bin/echoecho_torchx.py

注意

torchx.runtime是您应该使用的唯一模块，当编写您的应用程序二进制文件！

但是，由于 TorchX 本质上允许您的应用程序在任何地方运行建议在计划程序/基础结构中编写应用程序不可知的时尚。

这通常意味着使用 scheduler/infra 在接触点添加 API 层。例如，以下应用程序不是与基础设施无关的

import boto3

def main(input_path: str):
   s3 = boto3.session.Session().client("s3")
   path = s3_input_path.split("/")
   bucket = path[0]
   key = "/".join(path[1:])
   s3.download_file(bucket, key, "/tmp/input")
   input = torch.load("/tmp/input")
   # ...<rest of code omitted for brevity>...

上面的二进制文件隐含地假设是 AWS S3 路径。使此 Trainer 存储无关的一种方法是引入抽象层。对于文件系统，PyTorch Lightning 等框架已经定义了层（Lightning 在后台使用 fsspec）。上面的二进制文件可以重写为与存储无关闪电。input_pathFileSystemio

import pytorch_lightning.utilities.io as io

def main(input_url: str):
   fs = io.get_filesystem(input_url)
   with fs.open(input_url, "rb") as f:
       input = torch.load(f)
   # ...<rest of code omitted for brevity>...

现在可以称为 AS 或使其与存储在各种存储中的 input 兼容。mainmain("s3://foo/bar")main("file://foo/bar")

存在定义文件系统抽象的现有库。在中，您可以找到库或指向其他库的指针，它为您可能需要编写的各种功能提供抽象一个与基础设施无关的应用程序。理想情况下，中的特征是上游的及时发送到 Lightning 等旨在用于编写应用程序。但是，为这些抽象作品找到一个合适的永久归宿可能需要时间，甚至需要一个全新的 OSS 项目。在此之前，这些功能可以成熟并可供用户使用通过模块。FileSystemtorchx.runtimetorchx.runtimetorchx.runtime

后续步骤¶

查看快速入门指南，了解如何创建和运行组件。