torch.profiler

Обзор

Профилировщик PyTorch — это инструмент, позволяющий собирать показатели производительности во время обучения и инференса. API контекстного менеджера профилировщика помогает лучше понять, какие операторы модели наиболее затратны, изучить формы их входных данных и трассировки стека, исследовать активность ядер устройства и визуализировать трассировку выполнения.

torch.profiler.profiler.schedule(*, wait, warmup, active, repeat=0, skip_first=0, skip_first_wait=0) [исходный код]

Возвращает вызываемый объект, который можно использовать в качестве аргумента schedule профилировщика. Профилировщик пропустит первые skip_first шагов, затем будет ожидать в течение wait шагов, после чего выполнит прогрев в течение следующих warmup шагов, а затем будет вести активную запись в течение следующих active шагов. После этого цикл повторится, начиная с wait шагов. Необязательное число циклов указывается параметром repeat; нулевое значение означает, что циклы будут продолжаться до завершения профилирования.

Параметр skip_first_wait определяет, нужно ли пропустить первый этап wait. Это может быть полезно, если пользователь хочет ждать между циклами дольше, чем skip_first, но не во время первого профилирования. Например, если skip_first равно 10, а wait равно 20, перед прогревом в первом цикле будет выполнено ожидание в течение 10 + 20 = 30 шагов, если skip_first_wait равно нулю, и только 10 шагов, если skip_first_wait не равно нулю. Во всех последующих циклах ожидание между последней активной фазой и прогревом составит 20 шагов.

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

Callable

torch.profiler.profiler.supported_activities() [исходный код]

Возвращает набор поддерживаемых действий трассировки профилировщика.

Примечание: профилировщик использует библиотеку CUPTI для трассировки ядер CUDA на устройстве. Если CUDA включена, но CUPTI недоступна, передача ProfilerActivity.CUDA профилировщику приводит к использованию устаревшего кода профилирования CUDA (как и в устаревшем torch.autograd.profiler). В результате время CUDA включается в таблицу вывода профилировщика, но не в трассировку JSON.

torch.profiler.profiler.tensorboard_trace_handler(dir_name, worker_name=None, use_gzip=False, use_python_export=False) [исходный код]

Выводит файлы трассировки в каталог dir_name, после чего этот каталог можно напрямую передать TensorBoard в качестве logdir. worker_name должен быть уникальным для каждого рабочего процесса в распределённом сценарии; по умолчанию ему присваивается значение «[hostname]_[pid]».

Справочник API

class torch.profiler.profile(*, activities=None, schedule=None, on_trace_ready=None, record_shapes=False, profile_memory=False, with_stack=False, with_flops=False, with_modules=False, experimental_config=None, execution_trace_observer=None, acc_events=False, custom_trace_id_callback=None, post_processing_timeout_s=None) [исходный код]

Контекстный менеджер профилировщика.

Параметры:

• activities (iterable) –

  список групп действий (CPU, CUDA), используемых при профилировании; поддерживаемые значения: torch.profiler.ProfilerActivity.CPU, torch.profiler.ProfilerActivity.CUDA, torch.profiler.ProfilerActivity.XPU. Значение по умолчанию: ProfilerActivity.CPU и, если доступны, ProfilerActivity.CUDA или ProfilerActivity.XPU.

  Каждый элемент может быть перечислением ProfilerActivity (собирает все типы действий группы по умолчанию) или отображением dict, сопоставляющим ProfilerActivity списку отдельных имён типов действий для сбора, например {ProfilerActivity.CUDA: ["GPU_MEMCPY", "CUDA_RUNTIME"]}. Пустой список (например, {ProfilerActivity.CUDA: []}) означает, что для этой группы ничего собираться не будет. Одна и та же группа действий не должна встречаться более одного раза. Допустимые имена типов действий и особенности поведения для разных устройств см. в разделе ProfilerActivity.

• schedule (Callable) – вызываемый объект, принимающий шаг (int) в качестве единственного параметра и возвращающий значение ProfilerAction, указывающее действие профилировщика для каждого шага.
• on_trace_ready (Callable) – вызываемый объект, который вызывается в конце каждого цикла профилирования (когда schedule возвращает ProfilerAction.RECORD_AND_SAVE). Получает экземпляр profile в качестве единственного аргумента; обычно используется для экспорта трассировки (например, с помощью export_chrome_trace()) или вывода сводки.
• record_shapes (bool) – сохранять информацию о формах входных данных операторов.
• profile_memory (bool) – отслеживать выделение и освобождение памяти тензоров.
• with_stack (bool) – записывать исходную информацию (имя файла и номер строки) для операций.
• with_flops (bool) – использовать формулу для оценки числа FLOPs (операций с плавающей запятой) для определённых операторов (умножения матриц и двумерной свёртки).

• with_modules (bool) –

  записывать иерархию модулей (включая имена функций), соответствующую стеку вызовов операции. Например, если прямой вызов модуля A вызывает прямой вызов модуля B, содержащего операцию aten::add, то иерархия модулей для aten::add — A.B.

  Устарело начиная с версии ``with_modules``: свойство объявлено устаревшим и будет удалено в будущей версии. Оно собирает данные только для моделей TorchScript, которые сами объявлены устаревшими, и ничего не делает в eager-режиме. Используйте with_stack=True, который записывает события nn.Module для моделей в eager-режиме.

• experimental_config (_ExperimentalConfig) – набор экспериментальных параметров для функций библиотеки Kineto. Обратная совместимость не гарантируется.
• execution_trace_observer (ExecutionTraceObserver) – объект PyTorch Execution Trace Observer. Трассировки выполнения PyTorch представляют рабочие нагрузки ИИ/МО в виде графа и позволяют использовать бенчмарки с повторным воспроизведением, симуляторы и эмуляторы. Если этот аргумент задан, методы start() и stop() наблюдателя будут вызваны для того же временного интервала, что и профилировщик PyTorch. Пример кода см. в разделе с примерами ниже.
• acc_events (bool) – включить накопление FunctionEvents в нескольких циклах профилирования.
• post_processing_timeout_s (float) – необязательное время ожидания в секундах для постобработки результатов профилировщика. Если оно задано, разбор событий прекратится по истечении этого времени, а результат будет неполным. Полезно для обработки больших трассировок, обработка которых может занять слишком много времени.
• custom_trace_id_callback (Callable[[], str], optional) – предоставляемый пользователем генератор идентификаторов трассировки, вызываемый один раз за цикл профилирования. По умолчанию используется случайный UUID; получить его можно с помощью get_trace_id().

Примечание

Используйте schedule() для создания вызываемого объекта расписания. Нестандартные расписания полезны при профилировании длительных заданий обучения и позволяют пользователю получать несколько трассировок на разных итерациях процесса обучения. Расписание по умолчанию непрерывно записывает все события в течение всего времени работы контекстного менеджера.

Примечание

Используйте tensorboard_trace_handler() для создания файлов результатов для TensorBoard:

on_trace_ready=torch.profiler.tensorboard_trace_handler(dir_name)

После профилирования файлы результатов можно найти в указанном каталоге. Используйте команду:

tensorboard --logdir dir_name

чтобы просмотреть результаты в TensorBoard. Дополнительную информацию см. в разделе Плагин PyTorch Profiler для TensorBoard.

Примечание

Включение трассировки форм и стека приводит к дополнительным накладным расходам. Если задано record_shapes=True, профилировщик будет временно удерживать ссылки на тензоры; это может дополнительно препятствовать некоторым оптимизациям, зависящим от счётчика ссылок, и приводить к созданию дополнительных копий тензоров.

Примеры:

with torch.profiler.profile(
    activities=[
        torch.profiler.ProfilerActivity.CPU,
        torch.profiler.ProfilerActivity.CUDA,
    ]
) as p:
    code_to_profile()
print(p.key_averages().table(sort_by="self_cuda_time_total", row_limit=-1))

Использование функций schedule, on_trace_ready и step профилировщика:

# Non-default profiler schedule allows user to turn profiler on and off
# on different iterations of the training loop;
# trace_handler is called every time a new trace becomes available
def trace_handler(prof):
    print(
        prof.key_averages().table(sort_by="self_cuda_time_total", row_limit=-1)
    )
    # prof.export_chrome_trace("/tmp/test_trace_" + str(prof.step_num) + ".json")


with torch.profiler.profile(
    activities=[
        torch.profiler.ProfilerActivity.CPU,
        torch.profiler.ProfilerActivity.CUDA,
    ],
    # In this example with wait=1, warmup=1, active=2, repeat=1,
    # profiler will skip the first step/iteration,
    # start warming up on the second, record
    # the third and the fourth iterations,
    # after which the trace will become available
    # and on_trace_ready (when set) is called;
    # the cycle repeats starting with the next step
    schedule=torch.profiler.schedule(wait=1, warmup=1, active=2, repeat=1),
    on_trace_ready=trace_handler,
    # on_trace_ready=torch.profiler.tensorboard_trace_handler('./log')
    # used when outputting for tensorboard
) as p:
    for iter in range(N):
        code_iteration_to_profile(iter)
        # send a signal to the profiler that the next iteration has started
        p.step()

В следующем примере показана настройка Execution Trace Observer (execution_trace_observer)

with torch.profiler.profile(
    ...
    execution_trace_observer=(
        ExecutionTraceObserver().register_callback("./execution_trace.json")
    ),
) as p:
    for iter in range(N):
        code_iteration_to_profile(iter)
        p.step()

Также можно обратиться к test_execution_trace_with_kineto() в tests/profiler/test_profiler.py. Примечание: можно также передать любой объект, соответствующий интерфейсу _ITraceObserver.

add_metadata(key, value) [исходный код]

Добавляет в файл трассировки пользовательские метаданные с текстовым ключом и текстовым значением.

add_metadata_json(key, value) [исходный код]

Добавляет в файл трассировки пользовательские метаданные с текстовым ключом и допустимым значением JSON.

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

Возвращает список неагрегированных объектов FunctionEvent для использования в обратном вызове трассировки или после завершения профилирования.

export_chrome_trace(path, use_python_export=False) [исходный код]

Экспортирует собранную трассировку в формате Chrome JSON. Если Kineto включён, экспортируется только последний цикл расписания.

export_memory_timeline(path, device=None) [исходный код]

Экспортирует сведения о событиях памяти из собранного профилировщиком дерева для указанного устройства и строит временную диаграмму. С помощью export_memory_timeline можно экспортировать файлы трёх типов; тип определяется суффиксом path.

• Для диаграммы в формате HTML используйте суффикс .html; временная диаграмма памяти будет встроена в HTML-файл в виде изображения PNG.
• Для точек графика, состоящих из [times, [sizes by category]], где times — временные метки, а sizes — использование памяти для каждой категории. Временная диаграмма памяти будет сохранена в формате JSON (.json) или сжатого JSON (.json.gz) в зависимости от суффикса.
• Для исходных точек данных о памяти используйте суффикс .raw.json.gz. Каждое исходное событие памяти будет состоять из (timestamp, action, numbytes, category), где action — одно из значений [PREEXISTING, CREATE, INCREMENT_VERSION, DESTROY], а category — одно из перечислений torch.profiler._memory_profiler.Category.

Результат: временная диаграмма памяти, сохранённая в виде сжатого JSON, JSON или HTML.

Устарело начиная с версии ``export_memory_timeline``: метод объявлен устаревшим и будет удалён в будущей версии. Вместо него используйте torch.cuda.memory._record_memory_history и torch.cuda.memory._export_memory_snapshot.

export_stacks(path, metric='self_cpu_time_total') [исходный код]

Сохраняет трассировки стека в файл.

Параметры:

• path (str) – путь для сохранения файла со стеками;
• metric (str) – используемая метрика: «self_cpu_time_total» или «self_cuda_time_total»

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

Возвращает текущий идентификатор трассировки.

key_averages(group_by_input_shape=False, group_by_stack_n=0, group_by_overload_name=False, include_python_functions=False) [исходный код]

Вычисляет средние значения событий, группируя их по имени оператора и (при необходимости) формам входных данных, стеку и имени перегрузки.

Возвращает EventList агрегированных событий.

Примечание

Чтобы использовать функции работы с формами и стеком, обязательно задайте record_shapes/with_stack при создании контекстного менеджера профилировщика.

preset_metadata_json(key, value) [исходный код]

Задаёт пользовательские метаданные, пока профилировщик не запущен; они будут добавлены в файл трассировки позже. Метаданные представляют собой текстовый ключ и допустимое значение JSON.

set_custom_trace_id_callback(callback) [исходный код]

Задаёт генератор идентификаторов трассировки. Он вызывается в начале каждого цикла, поэтому его изменение между циклами позволяет получать разные идентификаторы для каждого цикла.

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

Сообщает профилировщику о начале следующего шага профилирования.

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

Отсоединяет ProfilerObserver cupti_monitor текущего цикла (с незаписанным интервалом), чтобы завершить отложенный экспорт ВНЕ потока обучения (вызвав obs.join(force=False) в рабочем потоке). Для серверных компонентов, не использующих CUPTI, возвращает None.

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

Any

toggle_collection_dynamic(enable, activities) [исходный код]

Включает или отключает сбор данных о действиях в любой момент сбора. В настоящее время поддерживается переключение операций Torch (CPU) и действий CUDA, поддерживаемых Kineto.

Параметры:

activities (iterable) – список групп действий, используемых при профилировании; поддерживаемые значения: torch.profiler.ProfilerActivity.CPU, torch.profiler.ProfilerActivity.CUDA

Примеры:

with torch.profiler.profile(
    activities=[
        torch.profiler.ProfilerActivity.CPU,
        torch.profiler.ProfilerActivity.CUDA,
    ]
) as p:
    code_to_profile_0()
    // turn off collection of all CUDA activity
    p.toggle_collection_dynamic(False, [torch.profiler.ProfilerActivity.CUDA])
    code_to_profile_1()
    // turn on collection of all CUDA activity
    p.toggle_collection_dynamic(True, [torch.profiler.ProfilerActivity.CUDA])
    code_to_profile_2()
print(p.key_averages().table(
    sort_by="self_cuda_time_total", row_limit=-1))

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

Блокирует выполнение, пока не будут записаны все отложенные экспорты cupti_monitor, затем отменяет регистрацию. Ничего не делает, если серверный компонент cupti_monitor не активен. Вызовите метод в потоке обучения, если файлы должны находиться на диске; при завершении выполняется принудительная очистка CUPTI (в этом случае безопасная).

class torch.profiler.ProfilerAction(value) [исходный код]

Действия профилировщика, которые можно выполнять в указанные интервалы.

NONE, WARMUP, RECORD и RECORD_AND_SAVE — это значения, доступные пользователю и возвращаемые расписанием, предоставленным пользователем. DEVICE_STOPPED устанавливается самим профилировщиком, когда сбор данных с устройства прекращается раньше времени из-за ошибок; пользовательское расписание не должно возвращать это значение.

class torch.profiler.ProfilerActivity

Типы устройств, поддерживаемые профилировщиком.

Элементы:

CPU : события CPU (операторы, среда выполнения, …).

XPU : активность устройства Intel XPU. В словаре действий с детальной настройкой ({ProfilerActivity.XPU: [...]}) имена, не являющиеся типами действий XPU, интерпретируются как имена аппаратных метрик Intel XPU и включают профилировщик с областью действия на уровне отдельных ядер, например {ProfilerActivity.XPU: ["GpuTime", "GpuCoreClocks"]}. Значения метрик присоединяются к каждому ядру в виде счётчиков Perfetto. Для сбора аппаратных метрик необходимы ZET_ENABLE_METRICS=1 и доступ к счётчикам производительности графического процессора (perf_stream_paranoid/observation_paranoid должны быть установлены в 0). Имена метрик зависят от устройства и определяются драйвером, а не PyTorch. Поскольку запись в словаре собирает именно перечисленные в ней данные, запрос только метрик (например, {ProfilerActivity.XPU: ["GpuTime"]}) не включает сбор действий XPU по умолчанию; чтобы продолжить их трассировку, укажите нужные имена типов действий вместе с метриками, например {ProfilerActivity.XPU: ["CONCURRENT_KERNEL", "XPU_RUNTIME", "GpuTime"]}.

MTIA : активность устройства MTIA.

CUDA : ядра и среда выполнения CUDA.

HPU : активность устройства HPU.

PrivateUse1 : активность серверной части PrivateUse1.

property name

API Intel Instrumentation and Tracing Technology

torch.profiler.itt.is_available() [исходный код]

Проверяет, доступна ли функция ITT.

torch.profiler.itt.mark(msg) [исходный код]

Описывает мгновенное событие, произошедшее в определённый момент.

Параметры:

msg (str) – сообщение ASCII, связанное с событием.

torch.profiler.itt.range_push(msg) [исходный код]

Помещает диапазон в стек вложенных диапазонов. Возвращает глубину начатого диапазона, отсчитываемую от нуля.

Параметры:

msg (str) – сообщение ASCII, связанное с диапазоном.

torch.profiler.itt.range_pop() [исходный код]

Извлекает диапазон из стека вложенных диапазонов. Возвращает глубину завершённого диапазона, отсчитываемую от нуля.

torch.profiler.itt.range(msg, *args, **kwargs) [исходный код]

Контекстный менеджер / декоратор, который помещает диапазон ITT в стек в начале своей области действия и извлекает его в конце. Если переданы дополнительные аргументы, они используются как аргументы функции msg.format().

Параметры:

msg (str) – сообщение, связанное с диапазоном.