错误传播

分布式 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(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 不存在，则时间戳为当前时间戳（自纪元以来的秒数）。

字段 message 是对故障的简要解释。如果错误文件存在，则消息将从错误文件中获取。否则，将根据故障签名生成一个消息。

注意

假设 error_file 由 torch.distributed.elastic.multiprocessing.errors.error_handler.ErrorHandler 写入。否则，行为未定义。