PyTorch 性能剖析入门（第1部分）：torch.profiler 使用指南

Hugging Face Blog

Hugging Face Blog2026年5月29日

PyTorch 性能剖析入门（第1部分）：torch.profiler 使用指南

8.7Score

TL;DR · AI 摘要

PyTorch 性能剖析入门指南（第1部分）系统讲解了如何使用 torch.profiler 分析矩阵乘加操作的性能瓶颈，通过可视化 trace 和事件链揭示 CPU-GPU 协同执行机制，并对比启用 torch.compile 前后的行为变化，帮助初学者快速掌握性能分析核心技能。

核心要点

使用 `torch.profiler.profile` + `record_function` 可轻松捕获 CPU/GPU 事件与内核调用链，生成可交互 t
trace 中的 CPU 阶段负责调度 GPU kernel，GPU kernel 是并行执行的核心计算单元，二者协同构成完整执行路径
启用 `torch.compile` 后，原生 matmul+add 的两步操作被融合为单个 kernel，显著减少 kernel launch 开销

结构提纲

按章节快速跳转。

§引言：为什么需要 profiling？
Profiling 是优化模型性能的前提，但其门槛高、输出复杂；本文旨在降低入门难度，引导读者从基础操作开始理解 trace。
§核心概念定义：kernel 与 scheduler
GPU kernel 是并行运行在多个线程上的程序；CPU 负责调度和启动这些 kernel；这是理解 trace 中事件顺序的基础。
§实践演示：matmul + add 操作的 profiling 流程
通过定义 fn(x,w,b) 函数、添加 record_function 注解、包裹 profile 上下文三步，即可捕获完整执行链路。
·trace 解读：CPU lane / GPU lane / gaps
CPU lane 显示 Python 调用栈与 kernel launch；GPU lane 展示实际执行的 CUDA kernel；间隙代表同步或等待时间。
·事件链追踪：从 Python 到 CUDA kernel
Python 调用 → PyTorch 张量操作 → kernel launch request → GPU scheduler → kernel execution，形成端到端执行路径。
§torch.compile 效果对比实验
启用 compile 后，原本分离的 matmul 和 add 操作被融合为一个 kernel，减少了 kernel launch 次数与上下文切换开销。

思维导图

用一张图看清主题之间的关系。

查看大纲文本（无障碍 / 无 JS 友好）

PyTorch Profiling 入门指南
- 核心目标
  - 降低 profiling 入门门槛
  - 建立 trace 解读能力
- 关键技术点
  - kernel vs scheduler
  - CPU/GPU 执行链路
- 实操流程
  - 代码准备
  - 函数注解 record_function
  - profile 上下文包装
- trace 分析
  - CPU lane：调度与 launch
  - GPU lane：kernel 执行
  - gap：同步/等待
- 优化验证
  - torch.compile 融合效果
  - kernel launch 数量变化

金句 / Highlights

值得收藏与分享的关键句。

What you cannot profile, you cannot optimize. — 性能优化的第一步是准确测量，否则所有改进都是盲目的。
— 引言段
⬇︎ 下载 PNG 𝕏 分享到 X
A GPU kernel is a program that runs in parallel on many threads of the GPU; the CPU schedules and launches these kernels. — 理解 kernel 与 scheduler 的分工是解读 trace 的关键前提。
— 定义部分
⬇︎ 下载 PNG 𝕏 分享到 X
When you use a PyTorch operation, it is automatically translated to one or more kernels that do the job on GPU. — 大多数用户无需手动写 kernel，但需理解其背后自动转换机制。
— 定义部分
⬇︎ 下载 PNG 𝕏 分享到 X
With torch.compile, the two-step matmul + add becomes a single fused kernel, reducing kernel launch overhead significantly. — 编译器融合是提升吞吐的关键手段之一。
— torch.compile 对比部分
⬇︎ 下载 PNG 𝕏 分享到 X

#PyTorch#profiler#performance#CUDA#torch.compile

打开原文

标题：在 PyTorch 中进行性能分析（第一部分）：初学者指南 —— torch.profiler

原文链接：https://huggingface.co/blog/torch-profiler 发布日期：2026-05-29T00:00:00.702Z

_“你无法分析的，就无法优化。”_

无论你是希望从大型语言模型（LLM）中榨取更多每秒处理的 token 数量、缩短推理耗时几毫秒，还是仅仅想弄清楚为何你的训练循环运行速度远低于规格说明书所承诺的性能，最终都必须经过性能分析这一环节。

问题在于，性能分析具有陡峭的学习曲线：追踪数据是密密麻麻、五彩斑斓的矩形块组成的墙；事件名称令人望而生畏；大多数教程默认读者已经能读懂这些内容。因此，即便我们深知应当进行性能分析，打开一个追踪文件时仍可能觉得这是一项最宜推迟（或交给他人）的任务。本文及其开启的系列文章，正是我们为降低这一学习门槛所做的努力。

这是《PyTorch 性能分析》系列的第一篇，我们将逐步培养阅读性能分析器输出结果的能力，并以此驱动优化工作。整体计划如下：

第一部分（本文）：从最简单的操作——矩阵乘法后接偏置加法开始，学习如何解读性能分析器返回的数据；
第二部分：扩展到 nn.Linear 和小型 MLP，利用追踪数据启发优化思路，并窥探底层的 kernels；
第三部分：将前述知识整合应用于使用 transformers 的大语言模型场景中。

本文以初学者视角记录整个探索过程，仅需具备基础 PyTorch 知识即可入门。建议以轻松的心态阅读，期待收获若干“啊哈！”时刻。文章结构采用问题导向方式：我们打开一份追踪数据，提出疑问：“等等，为什么会出现这种情况？”，然后一路追查直到理解其原因。到文章结尾，你将掌握：

如何设置 torch.profiler 并理解它实际返回的内容；
如何阅读性能分析器表格与追踪数据（CPU 路径、GPU 路径以及两者之间可疑的间隙）；
从一次 Python 调用一路向下，直至 CUDA kernel 执行的完整事件链；
当我们在代码上添加 torch.compile 后，哪些变化发生了（以及更有趣的是，哪些并未改变）。

在正式开始前，有两个定义将使下文更易理解：

GPU kernel 是一种在 GPU 多个线程上并行执行的程序；
CPU 负责调度和启动这些 kernel。

通常情况下，你无需亲自编写 GPU kernel；当你调用 PyTorch 操作时，它会自动被翻译成一个或多个 kernel，在 GPU 上完成任务。

带着这两个概念，让我们开始提问吧。

我们整篇文章所使用的脚本如下：`01_matmul_add.py`。我们建议你在单独标签页中打开该脚本，并逐行走读代码。本文所有示例均在 NVIDIA A100-SXM4-80GB GPU 上运行。

矩阵乘法与加法操作

正如 Sara Hooker 博士精辟指出：“正如我们身体主要由水构成，深度神经网络也主要由矩阵乘法组成。” 尽管它们如此基础，却绝不能错过——这正是我们性能分析之旅的起点。

code

def fn(x, w, b):
  return torch.add(torch.matmul(x, w), b)

矩阵加法与矩阵乘法的组合，模拟了神经元中权重与偏置的交互方式。这个加法操作（此处“pun intended”双关语意为“有意为之的双关”）将帮助我们理解后续章节中提到的编译机制。

为了进行性能分析，我们将使用 torch.profiler 模块。具体步骤如下：

准备好待分析的代码（见 `01_matmul_add.py`，即 def fn，它封装了矩阵乘法与矩阵加法）；
添加注解：虽然此步完全可选，但我们强烈推荐。record_function 将我们的函数标注为 matmul_add，便于在追踪数据中快速定位（如后文所述）：

code

def step():
  with torch.profiler.record_function("matmul_add"):
    return fn(x, w, b)

使用 torch.profiler.profile 上下文管理器包裹相关代码：

code

with torch.profiler.profile(
    activities=[
        torch.profiler.ProfilerActivity.CPU,  # CPU 相关活动
        torch.profiler.ProfilerActivity.CUDA, # GPU 相关活动
    ],
  ) as prof:
    # 建议多次运行以预热 GPU
    for _ in range(5):
      step()
      prof.step()

导出性能分析结果：

code

# 性能分析器表格
prof.key_averages().table(sort_by="cuda_time_total", row_limit=15)

# 性能分析器追踪数据
prof.export_chrome_trace(trace_path)

性能分析器会导出两种不同的产物：

性能分析器表格：提供算法的统计摘要。它回答“什么占用了最多时间”。这有助于识别热点。热点是指占用时间最多的事件，可能是流水线的瓶颈，或被频繁触发的事件。
性能分析器跟踪：提供时间执行视图。回答“操作何时以及为何发生”，描绘 CPU 和 GPU 上的活动。当我们需要调查已启动的内核、启动延迟、CPU 和 GPU 活动之间的重叠等情况时，这非常有用。

让我们通过第一次执行来观察这两者。(这里是完整的 `01_matmul_add.py` 脚本)

建议在带有 GPU 的机器上运行此脚本。

code

uv run 01_matmul_add.py --size 64

如果你在 GPU 机器上运行上述脚本，你会在 traces/01_matmul_add 文件夹中找到两个工件：

code

64_bf16_cold_eager.json
64_bf16_cold_eager.txt

| ![Image 7: Profiler table for matmul add on 64 sized matrices](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/torch-profiler/profile-table-64.png) | | --- | | Figure 1: Profiler table for matmul add on 64 sized matrices |

.txt 文件包含性能分析器表格。打开文件时，如图 1 所示，你会看到一个大表格，第一列包含在分析范围内触发的事件。

其他列与事件在 CPU、GPU 或 torch.profiler.profile 中 activities 指定的任何其他设备上所花费的时间相关。查看哪些事件占用时间最多，并尝试直观判断该事件是否确实应该花费这么多时间。同时，查看 "# of Calls" 列也很重要，它表示事件被触发的次数。

顺便说一下，我们还来谈谈 "Self CPU/CUDA" 与 "CPU/CUDA total"。"Self" 列仅测量事件本身所花费的时间，不包括其子事件。"total" 列包括事件及其所有子事件。因此，如果你查看 matmul_add 的 "CPU total"，它由事件自身所花时间和它触发的子事件所花时间组成。这是一个需要注意的重要细节。

如果你查看表格的最后两行，你会发现性能分析器告诉我们：

code

Self CPU time total: 2.314ms
Self CUDA time total: 23.104us

CPU 时间以 ms 为单位，而 GPU 时间以 us 为单位。为了理解，GPU 上花费的时间（内核 ampere_bf16_s16816gemm...）不到 CPU 上花费时间（matmul_add 操作）的 1%。GPU 大部分时间处于空闲状态，这是一个明显的警告信号。发生这种情况的原因是 GPU 可以非常快速地计算小规模矩阵乘法，因此我们的代码大部分时间用于准备内核、在 GPU 上启动它们、发送数据进行乘法运算以及收集结果。这个概念被称为 _overhead-bound_ 算法。

摆脱这种状态的最简单方法是使用更大的矩阵乘法。

code

uv run 01_matmul_add.py --size 4096

| ![Image 8: Profiler table for matmul add algorithm on 4096 sized matrices](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/torch-profiler/profiler-table-4096.png) | | --- | | Figure 2: Profiler table for matmul add on 4096 sized matrices |

图 2 的最后两行是：

code

Self CPU time total: 4.908ms
Self CUDA time total: 4.495ms

两个时间都以 ms 为单位，这意味着仅通过增加矩阵乘法的大小，我们就获得了更多的 GPU 时间。如果你查看图 2，你还会注意到，现在大部分 CUDA 时间由 GPU 内核（ampere_bf16_s16816gemm_..）占用，而不是由启动它的 CPU 操作（matmul_add）占用。这意味着我们确实能够从 overhead-bound 转变为 compute-bound。

我们现在进入可视化调度链，它存在于 .json 工件中。你可以将它们上传到 Perfetto UI 查看跟踪，或者使用 uvx trace-util traces -b traces 直接生成 Perfetto 链接。

64x64 跟踪

| ![Image 9: PyTorch profiler trace of a 64×64 bf16 matmul followed by an add on a CUDA GPU](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/torch-profiler/64-matmul-add.png) | | --- | | Figure 3: Profiler trace for matmul and add on 64 sized matrices |

在图 3 中，我们看到矩阵乘法和加法的性能分析器跟踪。这里，条形宽度表示事件的持续时间，垂直嵌套表示调用层次结构，CPU 通道表示在 CPU 上发生的事件，而 GPU 通道显示实际的内核执行。人们还可能注意到空闲空间，这些是等待或空闲时间。

脚本使用默认配置运行，包括：

size 64: 输入、权重和偏置的大小为 (64, 64)
dtype bf16: 数据类型为 bfloat16
no compile: 未编译 torch 操作
no warmup: 未在分析前预热 GPU

使用 Perfetto 时，建议使用键盘快速访问跟踪。可以使用 "W A S D" 来导航跟踪。