CLI

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 子命令採用以下其中一項：

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 的 URL。記住這個控制代碼，因為這是您需要提供給其他子命令以識別您的作業的內容。

注意

如果未提供 --scheduler 選項，則它預設為指向 local_cwd 的排程器後端 default。若要變更預設排程器，請參閱：註冊自訂排程器.

檢查將執行的內容（試執行）

當您撰寫或偵錯元件時，您可能希望找出並檢查執行程式提交的排程器請求物件，以及由元件函數建立的 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