快速上手¶

运行内置组件¶

使用TorchX最简单的方式是通过提供的CLI。

$ pip install torchx
$ torchx --help

使用 TorchX，你可以自定义应用，但 TorchX 提供了一套内置功能。现在让我们来看看这些内置功能。

$ torchx builtins
Found <n> builtin configs:
  ...
  i. utils.echo
  j. utils.touch
  ...

Echo看起来很熟悉且简单。让我们了解如何运行 utils.echo。

$ torchx run --scheduler local utils.echo --help
usage: torchx run echo [-h] [--msg MSG]

Echos a message

optional arguments:
-h, --help  show this help message and exit
--msg MSG   Message to echo

我们能看到它接受一个 --msg 个参数。让我们尝试在本地运行它

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

注意

echo 在此上下文中只是一个应用程序规范。它不是应用程序逻辑本身，而是运行 /bin/echo 的“作业定义”。如果你还没有这样做，现在是阅读基本概念以熟悉基本概念的好时机。

定义自己的组件¶

现在让我们自己尝试实现echo。为了使事情更有趣，我们将在我们的echo版本中添加两个更多的参数：

并行运行的副本数量
请提供待翻译的文本内容。

首先，我们创建一个应用配置文件。这只是一个普通的Python文件，在其中我们定义了应用程序的配置。

$ touch ~/test.py

现在将以下内容复制并粘贴到 test.py

import torchx.specs as specs


def echo(num_replicas: int, msg: str = "hello world") -> specs.AppDef:
    """
    Echos a message to stdout (calls /bin/echo)

    Args:
       num_replicas: number of copies (in parallel) to run
       msg: message to echo

    """
    return specs.AppDef(
        name="echo",
        roles=[
            specs.Role(
                name="echo",
                entrypoint="/bin/echo",
                image="/tmp",
                args=[f"replica #{specs.macros.replica_id}: {msg}"],
                num_replicas=num_replicas,
            )
        ],
    )

注意

不同于 --msg，--num_replicas 不具有默认值，表明它是必需的参数。
我们使用本地目录（/tmp）作为 image。在实践中，这将是调度器支持的包的标识符（例如 Docker 镜像）。
test.py 不包含应用程序的逻辑，而只是一个工作定义。

现在让我们尝试运行我们的自定义 echo

$ torchx run --scheduler local ~/test.py:echo --num_replicas 4 --msg "foobar"

replica #0: foobar
replica #1: foobar
replica #2: foobar
replica #3: foobar

在其他图像上运行¶

到目前为止，我们已经运行了utils.echo次，使用了image=/tmp个。这意味着我们指定的entrypoint是相对于/tmp的。这对我们没有关系，因为我们指定了绝对路径作为入口点（entrypoint=/bin/echo）。如果我们指定了entrypoint=echo，本地调度器将尝试调用/tmp/echo。

如果您有一个预构建的应用程序二进制文件，将图像设置为本地目录是验证应用程序和specs.AppDef的快速方法。但如果您想在远程调度器上运行应用程序，这并不是很有用（请参阅在其他调度器上运行）。

注意

The image 字符串在 specs.Role 中是一个由调度器支持的容器镜像标识符。请参阅调度器文档以了解您要使用的调度器支持的容器镜像。

对于 local 优化器，我们可以看到它支持本地目录和 Docker 作为图像：

$ torchx runopts local

{ 'image_type': { 'default': 'dir',
                 'help': 'image type. One of [dir, docker]',
                 'type': 'str'},
... <omitted for brevity> ...

注意

在继续之前，您需要安装Docker。如果您尚未完成此操作，请按照以下安装说明进行：https://docs.docker.com/get-docker/

现在让我们尝试在一个Docker容器中运行echo。修改你在上一节创建的~/test.py中的echo的AppDef，以使image="ubuntu:latest"。

import torchx.specs as specs


def echo(num_replicas: int, msg: str = "hello world") -> specs.AppDef:
    """
    Echos a message to stdout (calls /bin/echo)

    Args:
       num_replicas: number of copies (in parallel) to run
       msg: message to echo

    """
    return specs.AppDef(
        name="echo",
        roles=[
            specs.Role(
                name="echo",
                entrypoint="/bin/echo",
                image="ubuntu:latest", # IMAGE NOW POINTS TO THE UBUNTU DOCKER IMAGE
                args=[f"replica #{specs.macros.replica_id}: {msg}"],
                num_replicas=num_replicas,
            )
        ],
    )

尝试运行echo应用

$ torchx run --scheduler local \
             --scheduler_args image_type=docker \
             ~/test.py:echo \
             --num_replicas 4 \
             --msg "foobar from docker!"

在其他调度器上运行¶

到目前为止，我们已经在本地启动了组件。让我们来看看如何在真实的调度器上运行这个。

注意

本节假设您已经设置了一个运行中的实例，该实例支持一个或多个调度器。

让我们来看看我们可以启动哪些调度器，并选择一个你已经设置好的。

$ torchx schedulers

对于大多数调度器，您将必须指定一个额外的--scheduler_args参数。这些是调度器启动时与应用程序（作业）运行实例相关的参数，而不是应用程序定义（应用特例），例如作业priority。调度器参数是调度器特定的，因此您需要找到计划使用的调度器所需的调度器参数

$ torchx runopts <sched_name>
$ torchx runopts local

现在你已经弄清楚了需要哪些调度器参数，启动你的应用程序。

$ torchx run --scheduler <sched_name> --scheduler_args <k1=v1,k2=v2,...> \
    ~/my_app.py <app_args...>
$ torchx run --scheduler local --scheduler_args image_type=dir,log_dir=/tmp \
    ~/my_app.py --foo=bar

注意

如果你的应用参数与run子命令的参数重叠，你必须使用--分隔符以避免混淆。例如，如果你的应用还接受一个--scheduler参数，请按照以下方式运行它。

$ torchx run --scheduler local ~/my_app.py -- --scheduler foobar

下一步¶

查看其他功能，例如 torchx CLI
学习如何通过参考 torchx.specs 来编写更复杂的应用程序规格。
浏览内置组件集合 builtin components
查看调度器列表以了解 runner 支持的调度器
查看可以在哪些机器学习流水线平台上运行组件