概述¶

注意

上图仅用于说明目的。并非所有盒子目前是开箱即用的。

该模块包含一组内置的 TorchX 组件。目录 structure 按组件类别进行组织。组件只是模板化的应用程序规格。将它们视为不同类型的工厂方法的作业定义。在此 module 就是我们所说的组件。specs.AppDef

您可以浏览模块中的组件库或在我们的 Docs 页面上。torchx.components

使用 Builtin¶

找到内置组件后，您可以：

将组件作为作业运行
在工作流（管道）的上下文中使用组件

在这两种情况下，组件都将作为作业运行，区别在于该作业将作为独立作业直接在调度程序或“阶段”上运行具有上游和/或下游依赖项的工作流。

注意

根据组件的语义，作业可能是单一的 node 或 distributed 的例如，如果组件具有单个 role 中，则作业是单个 node 作业。如果组件具有多个角色和/或任何 role 的 Role，则该作业是一个多节点分布式作业。role.num_replicas == 1num_replicas > 1

不确定是应该将组件作为作业还是管道阶段运行？请使用以下经验法则：

刚开始？通过将组件作为作业运行来熟悉该组件
需要作业依赖项？将组件作为管道阶段运行
不需要作业依赖项？将组件作为作业运行

创作¶

由于组件只是一个返回，编写您自己的组件就像使用以下命令编写 Python 函数一样简单规则：specs.AppDef

组件函数必须返回一个，并且必须指定返回类型specs.AppDef
组件的所有参数都必须是 PEP 484 类型注释的，并且类型必须是以下之一
1. 原：intfloatstrbool
2. 可选基元：，，Optional[int]Optional[float]Optional[str]
3. 基元映射：Dict[Primitive_key, Primitive_value]
4. 基元列表：List[Primitive_values]
5. 可选集合：，Optional[List]Optional[Dict]
6. VAR_ARG：（在将参数传递给 entrypoint 脚本时很有用）*arg
（可选）google 格式的文档字符串（特别是 see ）。此文档字符串纯粹是信息性的在那个 torchx cli 中，CLI 使用它来自动生成一条信息性消息，即与他人共享组件时很有用。如果组件没有文档字符串该选项仍然有效，但参数将具有固定的描述（请参阅下文）。请注意，当通过function_with_pep484_type_annotations--help--helptorchx.runner、文档字符串根本没有被 torchx 拾取。

下面是一个启动 DDP 脚本的示例组件，它是这torchx.components.dist.ddp()内置。

import os
import torchx.specs as specs

def ddp(
    *script_args: str,
    image: str,
    script: str,
    host: str = "aws_p3.2xlarge",
    nnodes: int = 1,
    nproc_per_node: int = 1,
) -> specs.AppDef:
   return specs.AppDef(
       name=os.path.basename(script),
       roles=[
           spec.Role(
               name="trainer",
               image=image,
               resource=specs.named_resources[host],
               num_replicas=nnodes,
               entrypoint="python",
               args=[
                   "-m",
                   "torch.distributed.run",
                   "--rdzv_backend=c10d",
                   "--rdzv_endpoint=localhost:5900",
                   f"--nnodes={nnodes}",
                   f"--nprocs_per_node={nprocs_per_node}",
                   "-m",
                   script,
                   *script_args,
               ],
           ),
       ]
   )

假设上面的组件保存在中，我们可以在它上运行：example.py--help

$ torchx ./example.py:ddp --help
usage: torchx run ...torchx_params... ddp  [-h] --image IMAGE --script SCRIPT [--host HOST]
                                          [--nnodes NNODES] [--nproc_per_node NPROC_PER_NODE]
                                          ...

AppDef: ddp. TIP: improve this help string by adding a docstring ...<omitted for brevity>...

positional arguments:
  script_args           (required)

optional arguments:
  -h, --help            show this help message and exit
  --image IMAGE         (required)
  --script SCRIPT       (required)
  --host HOST           (default: aws_p3.2xlarge)
  --nnodes NNODES       (default: 1)
  --nproc_per_node NPROC_PER_NODE
                        (default: 1)

如果我们包含这样的文档字符串：

def ddp(...) -> specs.AppDef:
  """
  DDP Simplified.

  Args:
     image: name of the docker image containing the script + deps
     script: path of the script in the image
     script_args: arguments to the script
     host: machine type (one from named resources)
     nnodes: number of nodes to launch
     nproc_per_node: number of scripts to launch per node

  """

  # ... component body same as above ...
  pass

然后，该消息将反映函数和参数描述在文档字符串中，如下所示：--help

usage: torchx run ...torchx_params... ddp  [-h] --image IMAGE --script SCRIPT [--host HOST]
                                          [--nnodes NNODES] [--nproc_per_node NPROC_PER_NODE]
                                          ...

App spec: DDP simplified.

positional arguments:
  script_args           arguments to the script

optional arguments:
  -h, --help            show this help message and exit
  --image IMAGE         name of the docker image containing the script + deps
  --script SCRIPT       path of the script in the image
  --host HOST           machine type (one from named resources)
  --nnodes NNODES       number of nodes to launch
  --nproc_per_node NPROC_PER_NODE
                        number of scripts to launch per node

验证¶

要验证您是否已正确定义组件，您可以：

（最简单）使用 cli 试运行您的组件：--helptorchx run --dryrun ~/component.py:train --help
使用组件 Linter（请参阅 dist_test.py 作为示例）

作为 Job 运行¶

您可以使用 torchx cli 将组件作为作业运行，也可以使用 torchx.runner.两者是相同的，实际上 CLI 在后台使用 Runner，因此您可以自由选择。快速入门指南介绍了入门的基础知识。

编程运行¶

要以编程方式运行内置函数或你自己的组件，只需调用组件作为常规 Python 函数，并将其传递给torchx.runner. 下面是一个调用 builtin 的示例：utils.echo

from torchx.components.utils import echo
from torchx.runner import get_runner

get_runner().run(echo(msg="hello world"), scheduler="local_cwd")

CLI 运行（内置）¶

从 cli 运行组件时，您必须传递要调用的组件函数。对于内置组件，其格式为，其中是组件相对于的模块路径，是该模块中的组件函数。因此，对于，我们将删除前缀并将其作为{component_module}.{component_fn}{component_module}torchx.components{component_fn}torchx.components.utils.echotorchx.components

$ torchx run utils.echo --msg "hello world"

有关更多信息，请参阅 CLI 文档。

CLI 运行（自定义）¶

要使用 cli 运行自定义组件，您必须使用略有不同的表单 .其中是 file 路径，并且是 component 函数。假设你的组件在中，并且 component function 被调用，你可以运行这个{component_path}:{component_fn}{component_path}{component_fn}/home/bob/component.pytrain()

# option 1. use absolute path
$ torchx run /home/bob/component.py:train --help

# option 2. let the shell do the expansion
$ torchx run ~/component.py:train --help

# option 3. same but after CWD to $HOME
$ cd ~/
$ torchx run ./component.py:train --help

# option 4. files can be relative to CWD
$ cd ~/
$ torchx run component.py:train --help

注意

builtins 也可以以这种方式运行，前提是您知道 TorchX 的安装目录！

从 CLI 传递组件参数¶

由于组件只是 python 函数，因此以编程方式使用它们非常简单。如上所示，当通过 cli 的子命令运行组件时，将传递组件参数作为程序参数，使用双破折号 + param_name 语法（例如或）。 cli 根据 docstring 的 DocString 中。以下是有关如何传递各种类型的组件参数的摘要，假设组件定义为：run--param1=1--param1 1

# in comp.py
from typing import Dict, List
import torchx.specs as specs

def f(i: int, f: float, s: str, b: bool, l: List[str], d: Dict[str, str], *args) -> specs.AppDef:
   """
   Example component

   Args:
       i: int param
       f: float param
       s: string param
       b: bool param
       l: list param
       d: map param
       args: varargs param

   Returns: specs.AppDef
   """

   pass

帮助：torchx run comp.py:f --help
基元（，，）：intfloatstrtorchx run comp.py:f --i 1 --f 1.2 --s "bar"
布尔值：（或torchx run comp.py:f --b True--b False)
地图：torchx run comp.py:f --d k1=v1,k2=v2,k3=v3
列表：torchx run comp.py:f --l a,b,c
VAR_ARG：作为位置而不是参数传递，因此它们被指定在命令的末尾。分隔符用于启动 VAR_ARGS 部分。这当组件和应用程序具有相同的参数时，或者在传递 arg.以下是一些示例： * : * : : * :*args----help*args=["arg1", "arg2", "arg3"]torchx run comp.py:f --i 1 arg1 arg2 arg3*args=["--flag", "arg1"]torchx run comp.py:f --i 1 --flag arg1 `` * ``*args=["--help"]torchx run comp.py:f -- --help*args=["--i", "2"]torchx run comp.py:f --i 1 -- --i 2

在管道中运行¶

torchx.pipelines 定义了将 torchX 组件转换为表示目标管道平台（有关支持的管道编排器的列表，请参阅管道）。

其他资源¶

看：

本模块中定义的组件作为说明性示例
定义您自己的组件快速入门指南
组件最佳实践指南
应用最佳实践指南

概述¶