基准测试工具 - 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 API，在概念上合并了 timeit.Timer.repeat 和 timeit.Timer.autorange。（精确算法在方法文档字符串中讨论。）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 (可选[str]) – 用于总结 stmt 的字符串。例如，如果 stmt 为“torch.nn.functional.relu(torch.add(x, 1, out=out))”，则可以将 label 设置为“ReLU(x + 1)”以提高可读性。

• sub_label (可选[str]) –

  提供补充信息以区分具有相同 stmt 或 label 的测量值。例如，在上面的示例中，sub_label 可以是“float”或“int”，以便于区分：“ReLU(x + 1)：(float)”

  ”ReLU(x + 1)：(int)” 在打印测量值或使用 Compare 进行汇总时。

• description (可选[str]) –

  用于区分具有相同 label 和 sub_label 的测量值的字符串。 description 的主要用途是向 Compare 信号数据列。例如，可以根据输入大小进行设置，以创建以下形式的表格

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

  使用 Compare。它也包含在打印测量值时。

• env (可选[str]) – 此标签表示在不同环境中运行了否则相同的任务，因此不相同，例如在对内核进行 A/B 测试时。 Compare 将在合并重复运行时将具有不同 env 规范的测量值视为不同。

• 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。块大小的选择对测量质量很重要，必须平衡两个相互竞争的目标

1. 较小的块大小会导致更多重复，通常会得到更好的统计数据。

2. 较大的块大小可以更好地摊销 timer 调用的成本，并导致测量结果偏差更小。这很重要，因为 CUDA 同步时间是非平凡的（从个位数到两位数微秒），否则会使测量结果产生偏差。

blocked_autorange 通过运行预热阶段来设置 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 中添加导入才能使它们正确传输。

默认情况下，将收集并缓存一个空语句的配置文件，以指示来自驱动 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)

合并副本的便利方法。

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

返回类型

List[Measurement]

property significant_figures: int

近似有效数字估计。

此属性旨在提供一种方便的方法来估计测量的精度。它仅使用四分位数区域来估计统计数据，以尝试减轻来自尾部的偏差，并使用 1.645 的静态 z 值，因为它预计不会用于 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 在报告函数时会包含完整的文件路径（因为它应该这样做）。但是，这在比较配置文件时会导致问题。如果 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(...)

剥离前缀可以通过规范化字符串并导致比较时等效调用站点的更好取消来改善此问题。

返回类型

CallgrindStats

counts(*, denoise=False)

返回执行的指令总数。

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

返回类型

int

delta(other, inclusive=False)

比较两个计数集的差异。

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

返回类型

函数计数

stats(inclusive=False)

返回详细的函数计数。

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

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

返回类型

函数计数

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 通常是一个内容无关的容器，但是这对于获得可靠的结果足够重要，因此需要一个例外。

返回类型

函数计数

filter(filter_fn)

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

返回类型

函数计数

transform(map_fn)

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

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

返回类型

函数计数