命令行界面¶

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:
...

将组件作为作业运行¶

run 子命令接受以下之一：

内置函数的名称

$ torchx run --scheduler <sched_name> utils.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

将所有内容整合在一起，使用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 的 URL。请记住这个句柄，因为这是你需要提供给其他子命令以识别你的作业的内容。

注意

如果未提供--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转换为特定调度器后端的有价值的信息。

描述和查询作业的状态¶

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 来获取日志。请参考您的调度程序的用户手册以正确设置日志保留。

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

列出工作¶

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