錯誤傳播

在分散式 PyTorch 任務中，每個主機執行一個 TorchElastic 代理，以及多個工作程序（作為 TorchElastic 代理的子程序）。由於工作程序是使用者提供的（您的 PyTorch 指令碼/任務），TorchElastic 有一種方法可以將訓練器上的錯誤透過代理傳播到排程器，最終通知終端使用者任務的狀態並應用任何重試策略。

TorchElastic 將錯誤分為 3 類

類別	子類別	描述
使用者錯誤	輸入錯誤	TorchElastic API 的無效輸入（例如 min > max 節點）
	工作程序失敗	工作子程序上的任何失敗
平臺錯誤	n/a	代理引起的失敗
基礎設施錯誤	n/a	超出代理和工作程序範圍的失敗（例如主機失敗）

除“工作程序失敗”以外的所有錯誤，要麼由代理程序規範地引發，要麼隱式或顯式地導致代理程序崩潰。因此，標準的語言（如 Python）提供的異常處理策略適用。

工作程序失敗是特殊的，因為異常/失敗源自與代理不同的程序，因此錯誤需要跨程序傳播（例如，代理無法簡單地 try-catch 捕獲工作程序上引發的異常）。

TorchElastic 代理使用 torch.distributed.elastic.multiprocessing.start_processes() 啟動工作程序，其中內建了基於檔案的簡單跨程序錯誤傳播機制。

任何用 record() 裝飾的函式或二進位制入口點，會將未捕獲的異常（包含跟蹤資訊）寫入由環境變數 TORCHELASTIC_ERROR_FILE 指定的檔案中。父程序（例如代理）在它啟動的每個子程序上設定此環境變數，然後聚合所有子程序的錯誤檔案，並傳播時間戳最小的錯誤（即第一個錯誤）。

方法和類

torch.distributed.elastic.multiprocessing.errors.record(fn, error_handler=None)

語法糖，用於使用提供的 error_handler 記錄裝飾函式中發生的錯誤/異常。

使用此裝飾器等同於

error_handler = get_error_handler()
error_handler.initialize()
try:
    foobar()
except ChildFailedError as e:
    _, failure = e.get_first_failure()
    error_handler.dump_error_file(failure.error_file, failure.exitcode)
    raise
except Exception as e:
    error_handler.record_exception(e)
    raise

重要提示

在每個程序的頂層方法中使用此裝飾器一次，通常這是主方法。

示例

@record
def main():
    pass


if __name__ == "__main__":
    main()

返回型別

Callable[[…], T]

class torch.distributed.elastic.multiprocessing.errors.ChildFailedError(name, failures)

一種特殊的異常型別，可以從用 @record 裝飾器標註的函式中引發，使子程序的（根異常）按原樣向上層堆疊傳播（例如，不被包裝在父程序的跟蹤資訊中）。

當父程序是簡單的守護程序，而子程序（工作程序）實際在執行有意義的計算時，這非常有用。在這種情況下，錯誤通常發生在子程序上，因為父程序沒有執行任何非平凡的操作，並且子程序的錯誤應該傳播到排程器以便進行準確的根因診斷。

注意

傳播依賴於錯誤檔案而非異常處理，以支援函式和二進位制啟動。

示例

# process tree on a host (container)
0: scheduler-init-process:
           |- 1: torchelastic_agent:
                    |- 2: trainer_0 (ok)
                    |- 3: trainer_1 (fail) -> error.json
                    |- ...
                    |- n+2: trainer_n (ok)
           |- n+3: other processes
           |- ...

在上面的示例中，訓練器 1 的失敗（寫入 error.json 檔案）是根本原因，應該報告給排程器的初始化程序。torchelastic 代理在檢測到訓練器 1 的失敗時會引發一個 ChildFailedError("trainer", {1: "trainer_1/error.json"})，這將把訓練器 1 錯誤檔案的內容傳播到排程器的初始化程序。

class torch.distributed.elastic.multiprocessing.errors.ErrorHandler

將提供的異常物件以及一些關於錯誤的元資料以結構化的 JSON 格式寫入由環境變數 TORCHELASTIC_ERROR_FILE 指定的錯誤檔案。如果未設定此環境變數，則僅記錄本應寫入錯誤檔案的內容。

可以對此處理程式進行子類化以自定義錯誤的處理方式。子類應該重寫 initialize() 和 record_exception()。

class torch.distributed.elastic.multiprocessing.errors.ProcessFailure(local_rank, pid, exitcode, error_file)

表示失敗的程序結果。當工作程序失敗時，它可能會將失敗的根本原因記錄到檔案中。

嘗試從提供的 error_file 讀取失敗時間戳；如果 error_file 不存在，則時間戳為當前時間戳（自 epoch 以來的秒數）。

message 欄位是失敗的簡明解釋。如果錯誤檔案存在，則從錯誤檔案中獲取訊息。否則，將根據失敗簽名生成一個。

注意

假定 error_file 由 torch.distributed.elastic.multiprocessing.errors.error_handler.ErrorHandler 寫入。否則行為是未定義的。