CUDAGraph

class torch.cuda.graphs.CUDAGraph(keep_graph=False) [исходный код]

Обёртка вокруг графа CUDA.

Параметры:

keep_graph (bool, необязательный) – Если keep_graph=False, cudaGraphExec_t будет создан на GPU в конце capture_end, а базовый cudaGraph_t будет уничтожен. Пользователи, которым нужно запросить или иным образом изменить базовый cudaGraph_t перед созданием экземпляра, могут задать keep_graph=True и получить к нему доступ через raw_cuda_graph после capture_end. Обратите внимание, что в этом случае cudaGraphExec_t не будет создан в конце capture_end. Вместо этого он будет создан явным вызовом instantiate или автоматически при первом вызове replay, если ранее не был вызван instantiate. Рекомендуется вручную вызвать instantiate до replay, чтобы избежать повышенной задержки при первом вызове replay. Разрешается изменять исходный cudaGraph_t после первого вызова instantiate, но пользователь должен вручную вызвать instantiate ещё раз, чтобы гарантировать, что созданный экземпляр графа будет содержать эти изменения. PyTorch не может отслеживать эти изменения.

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

Self

Предупреждение

Этот API находится в бета-версии и может измениться в будущих выпусках.

capture_begin(pool=None, capture_error_mode='global', check_input_liveness=False) [исходный код]

Начать захват операций CUDA в текущем потоке.

Обычно не следует вызывать capture_begin самостоятельно. Используйте graph или make_graphed_callables(), которые вызывают capture_begin внутри.

Параметры:

• pool (необязательный) – Токен (возвращаемый graph_pool_handle() или other_Graph_instance.pool()) или MemPool, указывающий, что этот граф может использовать общую память с указанным пулом. См. раздел Управление памятью графов.
• capture_error_mode (str, необязательный) – задаёт cudaStreamCaptureMode для потока захвата графа. Может принимать значения “global”, “thread_local” или “relaxed”. Во время захвата графа CUDA некоторые действия, например cudaMalloc, могут быть небезопасны. Режим “global” приводит к ошибке при выполнении таких действий в других потоках, “thread_local” — только при выполнении таких действий в текущем потоке, а “relaxed” не вызывает ошибку при таких действиях. НЕ меняйте эту настройку, если вы не знакомы с cudaStreamCaptureMode

• check_input_liveness (bool, необязательный) –

  Если True, отслеживает внешние тензорные входы во время захвата графа и вызывает ошибку, если какой-либо из них освобождается до повторного воспроизведения. Это помогает выявлять ошибки «использования после освобождения», когда входные тензоры удаляются сборщиком мусора между захватом и повторным воспроизведением. По умолчанию: False.

  Примечание

  Пользовательские ядра CUDA, добавленные вне PyTorch (например, через cuLaunchKernel или DLPack), этим механизмом не отслеживаются.

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

Завершить захват графа CUDA в текущем потоке.

После capture_end для этого экземпляра можно вызвать replay.

Обычно не следует вызывать capture_end самостоятельно. Используйте graph или make_graphed_callables(), которые вызывают capture_end внутри.

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

Завершить захват, начатый с помощью capture_end_pre(): уничтожить шаблон при вызове keep_graph=False (граф уже должен быть создан; это выполняют capture_end() и менеджер контекста).

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

Завершить захват, но не финализировать его: оставить захваченный cudaGraph_t активным (в обоих режимах keep_graph), чтобы его можно было проверить до того, как capture_end_post() создаст экземпляр и/или уничтожит его.

debug_dump(debug_path, *, verbose=True) [исходный код]

Сохранить захваченный граф в debug_path в формате Graphviz DOT.

Шаблон графа должен быть активен: keep_graph=True (или enable_debug_mode()) либо вызов должен выполняться из обработчика завершения захвата. Требуется пакет cuda.bindings.

Параметры:

• debug_path (обязательный) – Путь для сохранения графа.
• verbose (bool) – Если True (значение по умолчанию), использовать наиболее подробный вывод DOT.

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

Сохранять захваченный граф (эквивалентно keep_graph=True), чтобы его можно было проверить, например, с помощью debug_dump(). Сохранено для обратной совместимости.

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

Возвращает словарь с описанием топологии графа и метаданных его узлов.

Значение keep_graph должно быть True. Перед вызовом этого метода граф должен быть создан (с помощью instantiate()). Требуется пакет cuda.bindings.

Возвращает словарь со следующей структурой:

{
    "exec_graph_id": int,
    "nodes": [
        {
            "index": int,
            "node_type": str,
            "tools_id": int,
            "graph_id": int,
            "node_id": int,
            "kernel_name": str or None,
            "event_ptr": int,
            "host_fn_addr": int,
            "host_fn_name": str or None,
            "dependencies": [int, ...],
            "dependents": [int, ...],
        },
        ...,
    ],
}

event_ptr — это дескриптор cudaEvent_t (в виде int), на который указывает узел записи события или с которого ожидает узел ожидания события: эти узлы не создают временную запись CUPTI, поэтому сопоставление ожидания с записью, которая его сигнализирует, — единственный способ определить закодированную им межпоточную синхронизацию. Для узлов других типов имеет значение 0.

host_fn_addr / host_fn_name заполняются для узлов хоста (обратный вызов CPU, выполняемый как узел графа): адрес обратного вызова и наиболее точное из доступных деманглированное имя символа для него (None, если ему не соответствует экспортируемый символ). Для узлов других типов имеют значение 0 / None.

Значение graph_id каждого узла переназначается на идентификатор графа exec, чтобы значения tools_id совпадали со значениями, отображаемыми профилировщиками на основе CUPTI. dependencies и dependents — это списки индексов узлов в списке nodes.

Эта структура полезна для анализа трассировки профилировщика и определения того, является ли конкретная зависимость, наблюдаемая в профиле, настоящей зависимостью (закодированной в графе) или ложной зависимостью, вызванной отображением независимых потоков на один и тот же аппаратный канал.

Дочерние графы и условные узлы отображаются как самостоятельные узлы, но этот обход не углубляется в их содержимое (это отдельные объекты cudaGraph_t), поэтому операции внутри них отсутствуют в nodes и выводится предупреждение. При этом отображаемые идентификаторы остаются действительными: граф exec сохраняет идентификаторы узлов верхнего уровня.

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

dict

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

Создать экземпляр графа CUDA. Вызывается методом capture_end, если keep_graph=False, либо методом replay, если keep_graph=True и instantiate ещё не был вызван явно. Не уничтожает cudaGraph_t, возвращаемый методом raw_cuda_graph.

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

Возвращает непрозрачный токен, представляющий идентификатор пула памяти этого графа.

Этот идентификатор можно передать параметру capture_begin другого графа, указав, что другой граф может использовать тот же пул памяти.

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

_POOL_HANDLE

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

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

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

list[_POOL_HANDLE]

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

Возвращает базовый cudaGraph_t. Шаблон должен быть активен: для этого требуется keep_graph=True (он сохраняется после capture_end) либо доступ из обработчика завершения захвата (до уничтожения шаблона для keep_graph=False).

Сведения об API для управления этим объектом см. в разделах Управление графами и привязки управления графами cuda-python

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

int

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

Возвращает базовый cudaGraphExec_t. Если keep_graph имеет значение True, должен быть вызван instantiate; если keep_graph имеет значение False, должен быть вызван capture_end. Если вызвать instantiate() после raw_cuda_graph_exec(), ранее возвращённый cudaGraphExec_t будет уничтожен. Вы несёте ответственность за то, чтобы не использовать этот объект после уничтожения.

Сведения об API для управления этим объектом см. в разделах Выполнение графов и привязки выполнения графов cuda-python

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

int

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

Зарегистрировать hook(graph) для выполнения после завершения захвата, но до финализации графа. Захваченный cudaGraph_t активен (доступен через raw_cuda_graph()) в обоих режимах keep_graph. Обработчики вызываются в порядке регистрации. Возвращает дескриптор, свойство remove() которого отменяет регистрацию обработчика.

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

RemovableHandle

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

Зарегистрировать hook(graph) для выполнения при начале захвата этого графа, сразу после начала захвата в текущем потоке. Обработчики вызываются в порядке регистрации. Возвращает дескриптор, свойство remove() которого отменяет регистрацию обработчика.

Предупреждение

Обработчик выполняется во время захвата: любые запущенные им операции CUDA захватываются в граф, а при режиме захвата по умолчанию "global" небезопасный вызов вызывает ошибку. См. torch.cuda.graphs.register_graph_capture_start_hook().

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

RemovableHandle

register_destroy_callback(cb, *, synchronize_before_release=False) [исходный код]

Зарегистрировать cb() для выполнения при уничтожении (финализации) этого графа или при явном вызове reset(), непосредственно перед освобождением ресурсов CUDA. Обратные вызовы выполняются один раз за цикл захвата в порядке регистрации; исключения подавляются, чтобы сбой одного обратного вызова не прерывал выполнение остальных. cb НЕ должен ссылаться на этот граф: финализатор, запускающий его, хранится в глобальном реестре, поэтому обратный вызов, доступный через граф, сохраняет граф до завершения работы интерпретатора (граф никогда не собирается сборщиком мусора, а значит, обратный вызов никогда не выполняется). Возвращает дескриптор, свойство remove() которого отменяет регистрацию обратного вызова.

При очистке синхронизация CUDA не выполняется, а cudaGraphExecDestroy освобождает ресурсы графа, выполняющегося в данный момент, только асинхронно. Поэтому обратный вызов, освобождающий память устройства, которую граф читает или записывает, приводит к использованию после освобождения, если повторное воспроизведение ещё выполняется. Передайте synchronize_before_release=True, чтобы синхронизировать все потоки, в которых воспроизводился этот граф, до вызова обратного вызова. В противном случае обратные вызовы не должны освобождать объекты, на которые ссылается граф.

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

RemovableHandle

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

Зарегистрировать hook(graph) для выполнения после каждого создания экземпляра (включая повторное создание, при котором создаётся новый граф exec). Созданный экземпляр графа доступен через raw_cuda_graph_exec(). Обработчики вызываются в порядке регистрации. Возвращает дескриптор, свойство remove() которого отменяет регистрацию обработчика.

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

RemovableHandle

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

Зарегистрировать hook(graph) для выполнения в конце каждого вызова replay(), сразу после запуска графа. Запуск выполняется асинхронно, поэтому обработчик выполняется после того, как повторное воспроизведение поставлено в очередь, а не после завершения работы GPU. Обработчики вызываются в порядке регистрации. Возвращает дескриптор, свойство remove() которого отменяет регистрацию обработчика. См. примечание о критическом пути для register_replay_start_hook().

Обработчики завершения вызываются, даже если запуск приводит к ошибке, поэтому каждому обработчику начала соответствует обработчик завершения, после чего распространяется ошибка запуска. (Если обработчик начала вызывает ошибку, повторное воспроизведение прерывается до запуска, и обработчик завершения не вызывается.)

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

RemovableHandle

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

Зарегистрировать hook(graph) для выполнения в начале каждого вызова replay(), непосредственно перед запуском графа (после создания экземпляра по запросу, поэтому raw_cuda_graph_exec() действителен). Обработчики вызываются в порядке регистрации. Возвращает дескриптор, свойство remove() которого отменяет регистрацию обработчика.

Примечание

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

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

RemovableHandle

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

Повторно воспроизвести операции CUDA, захваченные этим графом.

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

Удалить граф, хранящийся в этом экземпляре.

retain_object(obj, *, synchronize_before_release=False) [исходный код]

Сохранять obj активным в течение текущего цикла захвата этого графа и освободить его при уничтожении (финализации) графа или явном вызове reset(). Обратный вызов не выполняется; обычный подсчёт ссылок удаляет obj после освобождения сохранённой ссылки. Возвращает дескриптор, свойство remove() которого досрочно освобождает сохранённую ссылку. Как и в случае с register_destroy_callback(), obj НЕ должен ссылаться на этот граф, иначе граф будет сохраняться до завершения работы интерпретатора, а obj никогда не будет освобождён.

synchronize_before_release имеет тот же смысл и те же ограничения, что и в register_destroy_callback(): задайте его, если освобождение obj освобождает память устройства, которую граф читает или записывает (например, если obj — последняя ссылка на тензор, используемый графом), а повторное воспроизведение ещё может выполняться.

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

RemovableHandle