CLI¶

The torchx CLI 是一个围绕 torchx.runner.Runner 的命令行工具。它允许用户在不编写管道（即工作流）的情况下，直接将 torchx.specs.AppDef 启动到支持的调度器之一。这对于在不承担学习、编写和处理管道的技术和认知开销的情况下快速迭代应用程序逻辑非常方便。

注意

当犹豫不决时使用 torchx --help。

列出内置组件¶

模块下的大部分组件torchx.components都是CLI认为的“内置”应用。在编写自己的组件之前，你应该浏览一下内置组件，看看是否已经有符合你需要的应用。如果有，就无需再编写应用规范了！

$ torchx builtins
Found <n> builtin configs:
 1. echo
 2. simple_example
 3. touch
 ... <omitted for brevity>

列出支持的调度器和参数¶

要获取一个你可以启动作业的支持调度器列表，请运行以下命令：

$ torchx runopts
local_docker:
{ 'log_dir': { 'default': 'None',
               'help': 'dir to write stdout/stderr log files of replicas',
               'type': 'str'}}
local_cwd:
...
slurm:
...
kubernetes:
...

作为作业运行组件¶

命令 run 可以是以下之一：

内置名称

$ torchx run --scheduler <sched_name> echo

组件函数的完整 Python 模块路径

$ torchx run --scheduler <sched_name> torchx.components.utils.echo

*.py 文件的文件路径，该文件定义了组件以及该文件中的组件函数名称。

$ cat ~/my_trainer_spec.py
import torchx.specs as specs

def my_trainer(foo: int, bar: str) -> specs.AppDef:
  <...spec file details omitted for brevity...>

$ torchx run --scheduler <sched_name> ~/my_trainer_spec.py:my_trainer

现在你已经了解了如何选择要启动的应用程序，接下来是看看需要传递哪些参数。有三组参数：

传递给run子命令的参数，请通过运行以下命令查看它们的列表：
```
$ torchx run --help
```

调度程序的参数 (--scheduler_args，也称为 run_options 或 run_configs），每个调度程序需要不同的参数，要查找特定调度程序的参数，请运行以下命令（显示了 local_cwd 调度程序的命令：

$ torchx runopts local_cwd
{ 'log_dir': { 'default': 'None',
           'help': 'dir to write stdout/stderr log files of replicas',
           'type': 'str'}}

# pass run options as comma-delimited k=v pairs
$ torchx run --scheduler local_cwd --scheduler_args log_dir=/tmp ...

传递给组件的参数（应用程序参数包括在内），这也取决于组件本身，并且可以在组件上的--help字符串中看到。

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

Echos a message

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

综合起来，使用echo和local_cwd调度器运行：

$ torchx run --scheduler local_cwd --scheduler_args log_dir=/tmp utils.echo --msg "hello $USER"
=== RUN RESULT ===
Launched app: local://torchx_kiuk/echo_ecd30f74

默认情况下，run 子命令不会阻塞等待作业完成，而是简单地在指定调度器上调度作业并打印一个app handle，这是一个形式为$scheduler_name://torchx_$user/$job_id 的URL。请记住这个句柄，因为这是你需要提供给其他子命令以标识你的作业的内容。

注意

如果未提供 --scheduler 选项，则默认为调度器后端 default，该后端指向 local。要更改默认调度器，请参见：注册自定义调度器。

检查将要运行的内容（预览）¶

当您编写或调试组件时，您可能希望找到并检查运行程序提交的调度器请求对象以及组件函数创建的AppDef对象。为此，请使用--dryrun选项到run子命令：

$ torchx run --dryrun utils.echo --msg hello_world
=== APPLICATION ===
{ 'metadata': {},
  'name': 'echo',
  'roles': [ { 'args': ['hello_world'],
               'base_image': None,
               'entrypoint': '/bin/echo',
               'env': {},
               'image': '/tmp',
               'max_retries': 0,
               'name': 'echo',
               'num_replicas': 1,
               'port_map': {},
               'resource': { 'capabilities': {},
                             'cpu': -1,
                             'gpu': -1,
                             'memMB': -1},
               'retry_policy': <RetryPolicy.APPLICATION: 'APPLICATION'>}]}
=== SCHEDULER REQUEST ===
PopenRequest(
    app_id='echo_c944ffb2',
    log_dir='/tmp/torchx_asmtmyqj/torchx_kiuk/echo_c944ffb2',
    role_params={
        'echo': [
            ReplicaParam(
                args=['/bin/echo', 'hello_world'],
                env={'TORCHELASTIC_ERROR_FILE': '/tmp/torchx_asmtmyqj/torchx_kiuk/echo_c944ffb2/echo/0/error.json'},
                stdout=None,
                stderr=None)
            ]
        },
    role_log_dirs={'echo': ['/tmp/torchx_asmtmyqj/torchx_kiuk/echo_c944ffb2/echo/0']})

注意

调度程序请求的打印输出会根据调度程序类型而有所不同。上面的例子是一个模拟请求，因为调度程序是一个本地调度程序，它简单地使用subprocess.Popen来模拟POSIX进程中的副本。然而，调度程序请求包含了对运行器如何为特定调度后端翻译AppDef的宝贵见解。

描述和查询作业的状态¶

The describe 子命令基本上是 run 命令的逆操作。也就是说，它在给定 app_handle 时打印应用程序规范。

$ torchx describe <app handle>

重要的

命令describe尝试通过查询调度器来重建应用规范。因此，您看到的打印内容并不总是与给定到run完全相同的应用规范。运行器能够重建应用规范的程度取决于许多因素，例如调度器的describe_job API 的描述程度，以及在提交作业时是否忽略了应用规范中的某些字段，因为调度器不支持此类参数/功能。绝不要依赖describe API 作为您的应用规范存储功能。它只是用来帮助您进行检查。

要获取正在运行的任务的状态：

$ torchx status <app_handle> # prints status for all replicas and roles
$ torchx status --role trainer <app_handle> # filters it down to the trainer role

按--role过滤对具有多个角色的大规模工作很有用。

查看日志¶

注意

此功能取决于您的调度器设置保留日志的时间长短。 TorchX 不会为您存档日志，而是依赖于调度器的 get_log API 来获取日志。请参阅调度器的用户手册以正确设置日志保留。

The log 子命令是调度器的 get_log API 的一个简单包装器，用于让您从一个地方拉取/打印所有副本和角色的日志。它还允许您拉取特定于副本或角色的日志。下面是一些有用且易于理解的日志访问模式。

$ torchx log <app_handle>
Prints all logs from all replicas and roles (each log line is prefixed with role name and replica id)

$ torchx log --tail <app_handle>
If the job is still running tail the logs

$ torchx log --regex ".*Exception.*" <app_handle>
regex filter to exceptions

$ torchx log <app_handle>/<role>
$ torchx log <app_handle>/trainer
pulls all logs for the role trainer

$ torchx log <app_handle>/<role_name>/<replica_id>
$ torchx log <app_handle>/trainer/0,1
only pulls trainer 0 and trainer 1 (node not rank) logs

注意

某些调度程序不支持服务器端正则表达式过滤器。在这种情况下，正则表达式过滤器将在客户端应用，这意味着完整的日志必须通过客户端传递。这可能会对本地主机造成很大负担。请在使用日志 API 时谨慎判断。