快速上手¶

运行内置组件¶

使用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_cwd 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_cwd 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="ubuntu:latest",
                args=[f"replica #{specs.macros.replica_id}: {msg}"],
                num_replicas=num_replicas,
            )
        ],
    )

注意

不同于 --msg，--num_replicas 不具有默认值，表明它是必需的参数。
test.py 不包含应用程序的逻辑，而只是一个工作定义。

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

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

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

在其他图像上运行¶

到目前为止，我们已经使用utils.echo运行了local_cwd调度器。这意味着我们指定的entrypoint是相对于当前工作目录的，并且忽略了指定的镜像。这对我们来说并不重要，因为我们指定了一个绝对路径作为入口点（entrypoint=/bin/echo）。如果我们指定了entrypoint=echo, local_cwd 调度器会尝试调用相对于当前目录和指定 PATH 的echo。

如果您有预构建的应用程序二进制文件，使用 local_cwd 是验证应用程序和 specs.AppDef 的快速方法。但如果您想在远程调度器上运行应用程序，这并不是很有用（请参阅在其他调度器上运行）。

注意

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

为了匹配远程镜像的行为，我们可以使用local_docker调度器，它将通过docker启动镜像并运行相同的应用程序。

注意

在继续之前，您需要安装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_docker \
             ~/test.py:echo \
             --num_replicas 4 \
             --msg "foobar from docker!"

在其他调度器上运行¶

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

注意

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

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

$ torchx schedulers

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

$ torchx runopts <sched_name>
$ torchx runopts local_docker

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

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

注意

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

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

下一步¶

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