CLI

The torchx CLI 是围绕 torchx.runner.Runner 的命令行工具。它允许用户直接将 torchx.specs.AppDef 启动到支持的调度器之一，而无需编写管道（也称为工作流）。这对于快速迭代应用程序逻辑非常方便，因为它避免了学习、编写和处理管道的技术和认知开销。

注意

如有疑问，请使用 torchx --help。

列出内置组件

大多数在 torchx.components 模块下的组件都是 CLI 认为的“内置”应用程序。在编写自己的组件之前，您应该浏览内置组件，看看是否有适合您需求的组件。如果有，甚至无需编写应用程序规范！

$ torchx builtins
Found <n> builtin configs:
 1. metrics.tensorboard
 2. serve.torchserve
 3. utils.binary
 ... <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:
...

运行组件作为作业

The run 子命令接受以下内容之一：

1. 内置组件的名称

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

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

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

3. 定义组件的 *.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
   

现在您已经了解了如何选择要启动的应用程序，现在该看看需要传递哪些参数了。有三种参数集：

1. 对 run 子命令的参数，请通过运行以下命令查看其列表：

   $ torchx run --help
   

2. 调度器的参数（--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 ...
   

3. 组件的参数（此处包含应用程序参数），这也取决于组件，可以通过组件上的 --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
   

将所有内容整合在一起，使用 local_cwd 调度器运行 echo：

$ torchx run --scheduler local_cwd --scheduler_args log_dir=/tmp utils.echo --msg "hello $USER"
=== RUN RESULT ===
torchx 2022-06-15 16:08:57 INFO     Log files located in: /tmp/torchx/echo-crls3hcpwjmhc/echo/0
local_cwd://torchx/echo-crls3hcpwjmhc

默认情况下，run 子命令不会阻塞以等待作业完成，而是仅在指定的调度器上安排作业并打印一个 app handle，其格式为：$scheduler_name://torchx/$job_id。请记下此句柄，因为您需要将其提供给其他子命令以识别您的作业。

注意

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

检查将要运行的内容（dryrun）

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

$ torchx run --dryrun utils.echo --msg hello_world
=== APPLICATION ===
{ 'metadata': {},
  'name': 'echo',
  'roles': [ { 'args': ['hello_world'],
               '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>

重要

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

列出作业

The list 子命令允许您列出在调度器上启动的应用程序句柄和应用程序的状态。然后，您可以使用应用程序句柄进一步描述应用程序、查看日志等。

$ torchx list -s <scheduler_name>

$ torchx list -s kubernetes
APP HANDLE                                          APP STATUS
--------------------------------------------------  ------------
kubernetes://torchx/default:trainer-a5qvfhe1hyq2w   SUCCEEDED
kubernetes://torchx/default:trainer-d796ei2tdtest   SUCCEEDED
kubernetes://torchx/default:trainer-em0iao2m90000   FAILED
kubernetes://torchx/default:trainer-ew33oxmdg0123   SUCCEEDED