Утилиты для бенчмаркинга — torch.utils.benchmark

Создано: 2 нояб. 2020 г. | Последнее обновление: 7 мая 2026 г.

class torch.utils.benchmark.Timer(stmt='pass', setup='pass', global_setup='', timer=<function timer>, globals=None, label=None, sub_label=None, description=None, env=None, num_threads=1, language=Language.PYTHON) [исходный код]

Вспомогательный класс для измерения времени выполнения инструкций PyTorch.

Полное руководство по использованию этого класса см. здесь: https://pytorch.org/tutorials/recipes/recipes/benchmark.html

Таймер PyTorch основан на timeit.Timer (и фактически внутри использует timeit.Timer), но имеет несколько важных отличий:

Учет особенностей среды выполнения:

Timer выполняет прогревочные запуски (это важно, поскольку некоторые компоненты PyTorch инициализируются лениво), задает размер пула потоков для корректного сравнения и при необходимости синхронизирует асинхронные функции ускорителей.
Акцент на повторных измерениях:

При измерении кода, особенно сложных ядер и моделей, значительные колебания результатов от запуска к запуску могут исказить оценку. Предполагается, что все измерения должны включать повторные запуски для количественной оценки шума и вычисления медианы, которая надежнее среднего значения. Поэтому этот класс концептуально объединяет timeit.Timer.repeat и timeit.Timer.autorange, отступая от API timeit. (Точные алгоритмы описаны в строках документации методов.) Метод timeit воспроизводит исходный вариант для случаев, когда адаптивная стратегия не требуется.
Дополнительные метаданные:

При создании Timer можно при желании указать label, sub_label, description и env. (Они определены ниже.) Эти поля включаются в представление объекта результата и используются классом Compare для группировки и отображения результатов сравнения.
Количество инструкций

Помимо времени выполнения, Timer может запускать инструкцию под Callgrind и сообщать количество выполненных инструкций.

Аргументы конструктора, непосредственно соответствующие timeit.Timer:

stmt, setup, timer, globals

Аргументы конструктора, специфичные для таймера PyTorch:

label, sub_label, description, env, num_threads

Параметры:

stmt (str) – Фрагмент кода, который будет выполняться в цикле и измеряться.
setup (str) – Необязательный код настройки. Используется для определения переменных, задействованных в stmt
global_setup (str) – (Только для C++) Код, который размещается на верхнем уровне файла, например для инструкций #include.
timer (Callable[[], float]) – Вызываемый объект, возвращающий текущее время. Если PyTorch собран без поддержки ускорителей или ускоритель отсутствует, по умолчанию используется timeit.default_timer; в противном случае перед измерением времени выполняется синхронизация ускорителей.
globals (dict[str, Any] | None) – Словарь, определяющий глобальные переменные при выполнении stmt. Это другой способ передать переменные, необходимые для stmt.
label (str | None) – Строка с кратким описанием stmt. Например, если stmt — «torch.nn.functional.relu(torch.add(x, 1, out=out)», можно задать label равным «ReLU(x + 1)», чтобы улучшить читаемость.
sub_label (str | None) –

Дополнительные сведения для различения измерений с одинаковыми stmt или label. Например, в приведенном выше примере sub_label может быть равен «float» или «int», чтобы результаты было легко различать: «ReLU(x + 1): (float)»

«ReLU(x + 1): (int)» при выводе объектов Measurement или при создании сводки с помощью Compare.
description (str | None) –

Строка для различения измерений с одинаковыми label и sub_label. Основное назначение description — указать Compare столбцы данных. Например, его можно задать в зависимости от размера входных данных, чтобы получить таблицу следующего вида:
```
                        | n=1 | n=4 | ...
                        ------------- ...
ReLU(x + 1): (float)    | ... | ... | ...
ReLU(x + 1): (int)      | ... | ... | ...
```
с помощью Compare. Это значение также включается при выводе объекта Measurement.
env (str | None) – Эта метка указывает, что в остальном идентичные задачи выполнялись в разных средах и поэтому не являются эквивалентными, например при A/B-тестировании изменения ядра. Compare будет считать объекты Measurement с разными значениями env отдельными при объединении повторных запусков.
num_threads (int) – Размер пула потоков PyTorch при выполнении stmt. Производительность в однопоточном режиме важна как для одной из ключевых задач логического вывода, так и в качестве хорошего показателя внутренней эффективности алгоритма, поэтому по умолчанию используется один поток. Это отличается от размера пула потоков PyTorch по умолчанию, который старается задействовать все ядра.

adaptive_autorange(threshold=0.1, *, min_run_time=0.01, max_run_time=10.0, callback=None) [исходный код]

Подобно blocked_autorange, но также проверяет вариативность измерений и повторяет их, пока отношение межквартильного размаха к медиане не станет меньше 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) – пороговое значение отношения межквартильного размаха к медиане для остановки
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 во внутреннем цикле. Выбор размера блока важен для качества измерений и требует баланса между двумя конкурирующими целями:

Малый размер блока обеспечивает больше повторных измерений и, как правило, более точную статистику.
Большой размер блока позволяет лучше распределить стоимость вызова timer и дает менее смещенную оценку. Это важно, поскольку синхронизация ускорителя занимает заметное время (от единиц до нескольких десятков микросекунд) и в противном случае исказила бы измерение.

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 не может содержать произвольные структуры данных в памяти. (В отличие от методов измерения времени.) Глобальные переменные ограничены встроенными объектами, объектами nn.Modules и функциями или модулями TorchScript, чтобы уменьшить вероятность неожиданностей при сериализации и последующей десериализации. Подробнее об этом см. в классе GlobalsBridge. Будьте особенно внимательны с nn.Modules: они используют pickle, и для корректной передачи может понадобиться добавить импорт в setup.

По умолчанию собирается и кэшируется профиль пустой инструкции, чтобы определить количество инструкций, выполняемых циклом Python, который управляет stmt.

Возвращает:: Объект CallgrindStats, предоставляющий сведения о количестве инструкций и базовые средства для анализа и обработки результатов.

timeit(number=1000000) [исходный код]

Повторяет семантику timeit.Timer.timeit().

Выполняет основную инструкцию (stmt) number раз. https://docs.python.org/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) [исходный код]

Контейнер верхнего уровня для результатов Callgrind, собранных Timer.

Для обработки обычно используется класс 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) [исходный код]

Сравнивает два набора счетчиков.

Одна из распространенных причин собирать сведения о количестве инструкций — определить, как конкретное изменение повлияет на число инструкций, необходимых для выполнения некоторой единицы работы. Если это число возрастает, следующий логичный вопрос — «почему». Обычно для ответа нужно выяснить, какая часть кода привела к увеличению количества инструкций. Эта функция автоматизирует процесс, позволяя легко сравнивать счетчики как с учетом вложенных вызовов, так и без них.

Тип возвращаемого значения:: FunctionCounts

stats(inclusive=False) [исходный код]

Возвращает подробные счетчики функций.

Возвращаемые FunctionCounts можно представить как кортеж кортежей вида (количество, путь_и_имя_функции).

inclusive соответствует семантике Callgrind. Если значение True, счетчики включают инструкции, выполненные дочерними функциями. inclusive=True полезен для выявления узких мест в коде; inclusive=False полезен для уменьшения шума при сравнении счетчиков двух разных запусков. (Подробнее см. CallgrindStats.delta(…).)

Тип возвращаемого значения:: FunctionCounts

class torch.utils.benchmark.FunctionCounts(_data, inclusive, truncate_rows=True, _linewidth=None) [исходный код]

Контейнер для обработки результатов Callgrind.

Поддерживаются:

Сложение и вычитание для объединения результатов или их сравнения.
Индексация, как у кортежей.
Функция denoise, удаляющая вызовы CPython, известные своей недетерминированностью и значительным уровнем шума.
Два метода высшего порядка (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.org/tutorials/recipes/recipes/benchmark.html

Параметры:: results (list[Measurement]) – Список объектов Measurement для отображения.

colorize(rowwise=False) [исходный код]

Добавляет цветовое оформление к форматированной таблице.

По умолчанию раскрашивает столбцы.

extend_results(results) [исходный код]

Добавляет результаты к уже сохраненным.

Все добавляемые результаты должны быть экземплярами Measurement.

highlight_warnings() [исходный код]: Включает выделение предупреждений при создании форматированной таблицы.

print() [исходный код]: Выводит форматированную таблицу.

trim_significant_figures() [исходный код]: Включает сокращение числа значащих цифр при создании форматированной таблицы.

torch.utils.benchmark.examples.op_benchmark.assert_dicts_equal(dict_0, dict_1) [исходный код]

Встроенное сравнение словарей не сравнивает массивы NumPy.

Например:

x = {"a": np.ones((2, 1))}
x == x  # Raises ValueError

torch.utils.benchmark.utils.fuzzer.prod(values, base=1) [исходный код]

np.prod может вызвать переполнение, поэтому для вычисления произведения размеров следует использовать Python.

Несмотря на то что тип результата np.prod повышается до int64, переполнение все равно возможно. В таком случае отрицательное значение пройдет проверку размера, а при попытке фактически выделить память для Tensor возникнет ошибка нехватки памяти.

torch.utils.benchmark.utils.common.select_unit(t) [исходный код]

Определяет, как масштабировать значения времени порядка O(1).

Эта утилита форматирует числа для удобного восприятия.

Тип возвращаемого значения:: tuple[str, float]

torch.utils.benchmark.utils.common.trim_sigfig(x, n) [исходный код]

Округляет x до n значащих цифр (например, 3.14159, 2 -> 3.10000).

Тип возвращаемого значения:: float

torch.utils.benchmark.utils.compile.bench_all(model, sample_input, num_iters=5, optimizer=None, loss_fn=None) [исходный код]

Это простая утилита для тестирования производительности torch.compile. В частности, она проверяет, настроен ли ваш GPU для использования тензорных ядер, если он их поддерживает. Она также тестирует все основные бэкенды и выводит таблицу результатов, чтобы вы могли легко сравнить их. Для многих бэкендов требуются дополнительные зависимости, поэтому установите их отдельно с помощью pip.

Вы получите одну таблицу для инференса и другую для обучения. Если вы хотите использовать эту утилиту для обучения, обязательно передайте ей torch.optim.Optimizer.

Важные предупреждения: ваш GPU поддерживает тензорные ядра; мы включим их автоматически, установив torch.set_float32_matmul_precision(‘high’)

Если компиляция завершится с ошибкой по какой-либо причине, в том числе из-за отсутствующей зависимости, мы выведем Failed to compile {backend} with mode {mode}

torch.utils.benchmark.utils.compile.benchmark_compile(model, sample_input, num_iters=5, backend=None, mode='default', optimizer=None, loss_fn=None) [исходный код]: Используйте эту утилиту для тестирования производительности torch.compile.

torch.utils.benchmark.examples

torch.utils.benchmark.examples.spectral_ops_fuzz_test

Микротесты производительности для модуля torch.fft

run_benchmark

© 2026, PyTorch Contributors
PyTorch has a BSD-style license, as found in the LICENSE file.
https://docs.pytorch.org/docs/2.14/benchmark_utils.html