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 schedulers

运行一个应用程序作为任务¶

命令 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 get_spec(foo: int, bar: str) -> specs.AppDef:
  <...spec file details omitted for brevity...>

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

现在你已经理解了如何选择要启动的应用，现在是时候看看需要传递的参数是什么了。有三组参数：

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

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

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

$ torchx run --scheduler local --scheduler_args image_fetcher=dir,log_dir=/tmp ...

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

$ torchx run --scheduler local 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调度器运行：

$ torchx run      --scheduler local      --scheduler_args image_fetcher=dir,log_dir=/tmp      echo      --msg "hello $USER"
=== RUN RESULT ===
Launched app: local://torchx_kiuk/echo_ecd30f74

The run subcommand does not block for the job to finish, instead it simply schedules the job on the specified scheduler and prints an app handle which is a URL of the form: $scheduler_name://torchx_$user/$job_id. Keep note of this handle since this is what you’ll need to provide to other subcommands to identify your job.

描述和查询作业的状态¶

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 时谨慎判断。