Benchmark Utils - torch.utils.benchmark

class torch.utils.benchmark.Timer(stmt='pass', setup='pass', global_setup='', timer=<built-in function perf_counter>, globals=None, label=None, sub_label=None, description=None, env=None, num_threads=1, language=Language.PYTHON)

用于测量 PyTorch 语句执行时间的辅助类。

有关如何使用此类的完整教程，请参阅： https://pytorch.ac.cn/tutorials/recipes/recipes/benchmark.html

PyTorch Timer 基于 timeit.Timer (实际上在内部使用 timeit.Timer)，但有几个关键区别

1. 运行时感知

   Timer 将执行预热（很重要，因为 PyTorch 的某些元素是延迟初始化的），设置线程池大小以使比较具有可比性，并在必要时同步异步 CUDA 函数。

2. 关注副本

   在测量代码，尤其是复杂的内核/模型时，运行到运行的差异是一个重要的混淆因素。预计所有测量都应包括副本，以量化噪声并允许中值计算，这比平均值更稳健。为此，此类通过概念性地合并 timeit.Timer.repeat 和 timeit.Timer.autorange，偏离了 timeit API。（确切的算法在方法文档字符串中讨论。）timeit 方法被复制用于不需要自适应策略的情况。

3. 可选元数据

   定义 Timer 时，可以选择指定 label、sub_label、description 和 env。（稍后定义）这些字段包含在结果对象的表示中，并由 Compare 类用于对结果进行分组和显示以进行比较。

4. 指令计数

   除了墙上时间外，Timer 还可以使用 Callgrind 运行语句并报告执行的指令数。

直接类似于 timeit.Timer 构造函数参数

stmt、setup、timer、globals

PyTorch Timer 特定的构造函数参数

label、sub_label、description、env、num_threads

参数

• stmt (str) – 要在循环中运行并计时的代码片段。

• setup (str) – 可选的设置代码。用于定义 stmt 中使用的变量

• global_setup (str) –（仅限 C++）放置在文件顶层的代码，用于诸如 #include 语句。

• timer (Callable[[], float]) – 返回当前时间的可调用对象。如果 PyTorch 是在没有 CUDA 或没有 GPU 的情况下构建的，则默认为 timeit.default_timer；否则，它将在测量时间之前同步 CUDA。

• globals (Optional[Dict[str, Any]]) – 一个字典，用于定义执行 stmt 时的全局变量。这是提供 stmt 需要的变量的另一种方法。

• label (Optional[str]) – 总结 stmt 的字符串。例如，如果 stmt 是 “torch.nn.functional.relu(torch.add(x, 1, out=out))”，则可以将 label 设置为 “ReLU(x + 1)” 以提高可读性。

• sub_label (Optional[str]) –

  提供补充信息以消除具有相同 stmt 或标签的测量的歧义。例如，在上面的示例中，sub_label 可能是 “float” 或 “int”，以便易于区分：“ReLU(x + 1): (float)”

  “ReLU(x + 1): (int)”，在打印 Measurement 或使用 Compare 进行汇总时。

• description (Optional[str]) –

  用于区分具有相同标签和子标签的测量的字符串。description 的主要用途是向 Compare 发出数据列的信号。例如，可以根据输入大小设置它以创建表格形式

                          | n=1 | n=4 | ...
                          ------------- ...
  ReLU(x + 1): (float)    | ... | ... | ...
  ReLU(x + 1): (int)      | ... | ... | ...
  

  使用 Compare。它也包含在打印 Measurement 时。

• env (Optional[str]) – 此标签指示在不同环境中运行了其他相同的任务，因此它们是不等效的，例如当 A/B 测试对内核的更改时。Compare 在合并重复运行时，会将具有不同 env 规范的 Measurement 视为不同的。

• num_threads (int) – 执行 stmt 时 PyTorch 线程池的大小。单线程性能作为关键推理工作负载和内在算法效率的良好指标非常重要，因此默认设置为 1。这与尝试利用所有核心的默认 PyTorch 线程池大小形成对比。

adaptive_autorange(threshold=0.1, *, min_run_time=0.01, max_run_time=10.0, callback=None)

类似于 blocked_autorange，但也会检查测量中的可变性，并重复直到 iqr/median 小于 threshold 或达到 max_run_time。

在高层次上，adaptive_autorange 执行以下伪代码

`setup`

times = []
while times.sum < max_run_time
    start = timer()
    for _ in range(block_size):
        `stmt`
    times.append(timer() - start)

    enough_data = len(times)>3 and times.sum > min_run_time
    small_iqr=times.iqr/times.mean<threshold

    if enough_data and small_iqr:
        break

参数

• threshold (float) – iqr/median 阈值，用于停止

• min_run_time (float) – 检查 threshold 之前所需的总运行时

• max_run_time (float) – 所有测量的总运行时，无论 threshold 如何

返回

一个 Measurement 对象，其中包含测量的运行时和重复计数，可用于计算统计信息。（均值、中位数等）

返回类型

Measurement

blocked_autorange(callback=None, min_run_time=0.2)

在保持计时器开销最小化的同时测量多个副本。

在高层次上，blocked_autorange 执行以下伪代码

`setup`

total_time = 0
while total_time < min_run_time
    start = timer()
    for _ in range(block_size):
        `stmt`
    total_time += (timer() - start)

请注意内部循环中的变量 block_size。block size 的选择对于测量质量非常重要，并且必须平衡两个相互竞争的目标

1. 较小的 block size 会产生更多副本，并且通常具有更好的统计数据。

2. 较大的 block size 更好地分摊了 timer 调用的成本，并导致偏差较小的测量。这很重要，因为 CUDA 同步时间非常重要（单到低两位数微秒量级），否则会使测量产生偏差。

blocked_autorange 通过运行预热期来设置 block_size，增加 block size 直到计时器开销小于总计算量的 0.1%。然后将此值用于主测量循环。

返回

一个 Measurement 对象，其中包含测量的运行时和重复计数，可用于计算统计信息。（均值、中位数等）

返回类型

Measurement

collect_callgrind(number: int, *, repeats: None, collect_baseline: bool, retain_out_file: bool) → CallgrindStats

collect_callgrind(number: int, *, repeats: int, collect_baseline: bool, retain_out_file: bool) → Tuple[CallgrindStats, ...]

使用 Callgrind 收集指令计数。

与墙上时间不同，指令计数是确定性的（模程序本身的非确定性和来自 Python 解释器的小量抖动。）这使它们成为详细性能分析的理想选择。此方法在单独的进程中运行 stmt，以便 Valgrind 可以检测程序。由于检测，性能会严重下降，但这可以通过少量迭代通常足以获得良好的测量结果来缓解。

为了使用此方法，必须安装 valgrind、callgrind_control 和 callgrind_annotate。

由于调用者（此进程）和 stmt 执行之间存在进程边界，因此 globals 不能包含任意的内存数据结构。（与计时方法不同）相反，globals 仅限于内置函数、nn.Modules 和 TorchScripted 函数/模块，以减少序列化和后续反序列化带来的意外因素。GlobalsBridge 类提供了关于此主题的更多详细信息。请特别注意 nn.Modules：它们依赖于 pickle，您可能需要在 setup 中添加 import 才能正确传输它们。

默认情况下，将收集并缓存空语句的配置文件，以指示驱动 stmt 的 Python 循环中的指令数。

返回

一个 CallgrindStats 对象，提供指令计数和一些用于分析和操作结果的基本工具。

timeit(number=1000000)

镜像 timeit.Timer.timeit() 的语义。

执行主语句 (stmt) number 次。 https://docs.pythonlang.cn/3/library/timeit.html#timeit.Timer.timeit

返回类型

Measurement

class torch.utils.benchmark.Measurement(number_per_run, raw_times, task_spec, metadata=None)

Timer 测量的结果。

此类存储给定语句的一个或多个测量值。它是可序列化的，并为下游使用者提供了一些便利方法（包括详细的 __repr__）。

static merge(measurements)

用于合并副本的便利方法。

Merge 将时间外推到 number_per_run=1，并且不会传输任何元数据。（因为元数据在副本之间可能不同）

返回类型

List[Measurement]

property significant_figures: int

近似有效数字估计。

此属性旨在提供一种方便的方法来估计测量的精度。它仅使用四分位距来估计统计数据，以尝试减轻来自尾部的偏斜，并使用静态 z 值 1.645，因为它不希望用于小的 n 值，因此 z 可以近似 t。

有效数字估计与 trim_sigfig 方法结合使用，以提供更易于人类理解的数据摘要。__repr__ 不使用此方法；它只是显示原始值。有效数字估计旨在用于 Compare。

class torch.utils.benchmark.CallgrindStats(task_spec, number_per_run, built_with_debug_symbols, baseline_inclusive_stats, baseline_exclusive_stats, stmt_inclusive_stats, stmt_exclusive_stats, stmt_callgrind_out)

由 Timer 收集的 Callgrind 结果的顶层容器。

操作通常使用 FunctionCounts 类完成，该类通过调用 CallgrindStats.stats(…) 获得。还提供了一些便利方法；最重要的是 CallgrindStats.as_standardized()。

as_standardized()

从函数字符串中剥离库名称和一些前缀。

当比较两组不同的指令计数时，一个绊脚石可能是路径前缀。Callgrind 在报告函数时包含完整的文件路径（应该如此）。但是，这可能会在 diff 配置文件时引起问题。如果 Python 或 PyTorch 等关键组件是在两个配置文件中的不同位置构建的，则可能会导致类似于

23234231 /tmp/first_build_dir/thing.c:foo(...)
 9823794 /tmp/first_build_dir/thing.c:bar(...)
  ...
   53453 .../aten/src/Aten/...:function_that_actually_changed(...)
  ...
 -9823794 /tmp/second_build_dir/thing.c:bar(...)
-23234231 /tmp/second_build_dir/thing.c:foo(...)

剥离前缀可以通过规范化字符串并在 diff 时更好地取消等效调用站点来缓解此问题。

返回类型

CallgrindStats

counts(*, denoise=False)

返回执行的指令总数。

有关 denoise 参数的解释，请参阅 FunctionCounts.denoise()。

返回类型

int

delta(other, inclusive=False)

Diff 两组计数。

收集指令计数的一个常见原因是确定特定更改对执行某些工作单元所需的指令数量的影响。如果更改增加了该数量，则下一个逻辑问题是“为什么”。这通常涉及查看代码的哪个部分增加了指令计数。此函数自动化了该过程，以便可以轻松地在包含和排除的基础上 diff 计数。

返回类型

FunctionCounts

stats(inclusive=False)

返回详细的函数计数。

从概念上讲，返回的 FunctionCounts 可以被认为是 (count, path_and_function_name) 元组的元组。

inclusive 匹配 callgrind 的语义。如果为 True，则计数包括子项执行的指令。inclusive=True 有助于识别代码中的热点；inclusive=False 有助于在 diff 来自两个不同运行的计数时减少噪声。（有关更多详细信息，请参阅 CallgrindStats.delta(…)）

返回类型

FunctionCounts

class torch.utils.benchmark.FunctionCounts(_data, inclusive, truncate_rows=True, _linewidth=None)

Callgrind 结果的操作容器。

它支持：

1. 加法和减法以合并或区分结果。

2. 类似元组的索引。

3. 一个 denoise 函数，用于去除已知为非确定性且非常嘈杂的 CPython 调用。

4. 两个高阶方法（filter 和 transform）用于自定义操作。

denoise()

移除已知的噪声指令。

CPython 解释器中的一些指令相当嘈杂。这些指令涉及 Unicode 到字典的查找，Python 使用它来映射变量名。FunctionCounts 通常是一个内容无关的容器，但是这对于获得可靠的结果非常重要，因此有必要进行异常处理。

返回类型

FunctionCounts

filter(filter_fn)

仅保留将 filter_fn 应用于函数名称返回 True 的元素。

返回类型

FunctionCounts

transform(map_fn)

将 map_fn 应用于所有函数名称。

这可以用于规范化函数名称（例如，去除文件路径的不相关部分），通过将多个函数映射到相同的名称来合并条目（在这种情况下，计数会相加）等。

返回类型

FunctionCounts

class torch.utils.benchmark.Compare(results)

用于在格式化表格中显示多个测量结果的辅助类。

表格格式基于 torch.utils.benchmark.Timer 中提供的信息字段（description、label、sub_label、num_threads 等）。

可以使用 print() 直接打印表格，或者将其转换为 str。

有关如何使用此类的完整教程，请参阅： https://pytorch.ac.cn/tutorials/recipes/recipes/benchmark.html

参数

results (List[Measurement]) – 要显示的测量列表。

colorize(rowwise=False)

为格式化表格着色。

默认情况下按列着色。

extend_results(results)

将结果追加到已存储的结果中。

所有添加的结果都必须是 Measurement 的实例。

highlight_warnings()

在构建格式化表格时启用警告高亮显示。

print()

打印格式化表格

trim_significant_figures()

在构建格式化表格时启用有效数字的修剪。