PyTorch `torch.compile()` 基准测试指南：TorchBench / HuggingFace / TIMM 三套件与 TorchInductor 加速评测实战

本指南围绕 PyTorch 仓库 benchmarks/dynamo 目录下的基准测试框架展开，介绍 TorchBench、HuggingFace、TIMM 三大评测套件如何使用统一入口脚本对 torch.compile()（TorchDynamo + 各类编译后端，重点是 TorchInductor）做训练/推理的性能与精度评测。读者读完可掌握 dashboard 结果复现所需的环境准备、完整命令行参数、单模型调试以及结果文件的解读方法，并了解底层公共 Runner 的实现机制。

概述：torch.compile() 基准测试框架解决什么问题

PyTorch 自 2.0 起通过 torch.compile() 将模型编译优化分为 TorchDynamo（前端图捕获）与编译后端（如 TorchInductor）两层。要回答“某个后端在真实模型上比 eager 模式快多少、精度是否对齐”，就必须有一套统一的、可复现的评测基础设施。

benchmarks/dynamo/README.md 所描述的正是这套基础设施：它以 TorchBenchmark（TorchBench）、HuggingFace Transformers、TIMM 三组真实模型集合为载体，提供 torchbench.py、huggingface.py、timm_models.py 三个入口脚本，共享同一套参数解析与执行框架，输出统一格式的 CSV/JSON 结果，既服务于每日运行的性能看板（Performance Dashboard），也支持在本地逐条复现。

目录内还包括配套的检查脚本与预期值清单（如 check_accuracy.py、check_perf_csv.py、ci_expected_accuracy），以及 run_all.sh、runner.py 等批量执行入口。

三大基准套件及其在仓库中的落点

README 明确了三套评测模型的定位：它们共同覆盖了 CV、NLP、推荐等领域最具代表性的模型形态，用于衡量编译器在不同算子组合下的真实收益。

套件	模型来源与侧重	仓库内低层 Runner	配套配置文件
TorchBenchmark	初始取自 Papers With Code 高被引研究模型，覆盖面广	torchbench.py	torchbench.yaml
HuggingFace	以 Transformer 为主，每个模型类别挑选代表模型	huggingface.py	huggingface.yaml
TIMM	以视觉模型为主，按类别挑选代表模型	timm_models.py	timm_models.yaml

从源码看，三套 Runner 全部继承自 common.py 中的 BenchmarkRunner（见 torchbench.py 的导入），通过 load_yaml_file 加载各自的 YAML 配置。以 torchbench.py 为例，模型的 skip 名单、batch size、容差（tolerance）、禁用 CUDA graph 的模型等均从 YAML 读取，例如：

• skip.all / skip.device.{cpu,cpu_aarch64,cuda,xpu} / skip.freezing.{cpu,cuda}：各设备与冻结（freezing）场景下需要跳过的模型；
• batch_size.training / batch_size.inference：为每个模型指定的 batch size；
• tolerance.*：精度校验的容差分级（如 higher_fp16、even_higher、higher_bf16、cosine 等）。

对应地，huggingface.yaml 中记录了 Transformer 模型的 skip.device.cpu、batch_size.divisors、tolerance.higher_training 等配置，且针对超大模型（如 google/gemma-3-4b-it、openai/gpt-oss-20b）单独做了跳过或 batch 缩减处理。

TorchBench 的模型加载采用动态导入方式：在 torchbench.py 中按 torchbenchmark.models.<name>、torchbenchmark.canary_models.<name>（可再扩展 FB 模型）逐一尝试 importlib.import_module，并约定每个模型暴露 Model 类。模型集合则来自 torchbenchmark._list_model_paths()（见 torchbench.py），因此使用前需要按下一节的步骤安装 TorchBenchmark 依赖。

TIMM 的入口 timm_models.py 在首次运行时若检测不到 timm 会自动执行 pip install 安装 PyTorch Image Models；HuggingFace 套件同样会在首次运行时分发所需依赖并下载模型。README 中对此的表述是“low-level runner 在首次运行自动下载并安装所需依赖”。

性能看板：GPU 与 CPU 的结果归口

GPU Performance Dashboard

README 指出，benchmarks/dynamo 的每日结果汇总在 TorchInductor 性能看板上，当前在 NVIDIA A100 GPU 上运行，数据由 inductor-perf-test-nightly 工作流生成。

看板采用 Base Commit 与 New Commit 双提交对比的呈现方式，例如 2.38x → 2.41x 表示性能从基线提交的 2.38 倍提升到新提交的 2.41 倍。需要特别强调的是：所有性能结果都以 eager 模式 PyTorch 为 1x 基准做归一化，数值越高越好。这一“相对 eager 的加速比”口径在 common.py 的结果写入逻辑中也能印证——CSV 结果中专门记录 speedup 列，汇总打印时使用几何平均（gmean）跨模型求总体加速比。

CPU Performance Dashboard

除 GPU 外，仓库同样维护 CPU 场景的 TorchInductor 性能看板，结果在相应 GitHub issue 中周期更新。CPU 评测需要显式使用 --device=cpu，并使用 _skip["device"]["cpu"]、_skip["freezing"]["cpu"] 等配置过滤不适用的模型（见 torchbench.py）。

本地运行：环境准备与依赖安装

先决条件

• 一个已构建/安装、可用的 PyTorch 开发环境（需包含 torch._dynamo 与 torch._inductor 模块）；
• Python 侧依赖：yaml、pandas、scipy、psutil、tqdm、numpy 等（见 common.py 的导入）；
• 各套件对应的模型仓库依赖。

依赖安装（Makefile）

Makefile 封装了与 PyTorch CI 版本对齐的依赖准备流程，目标包括：

• clone-deps：递归克隆 torchvision、torchdata、torchaudio、detectron2、FBGEMM、torchrec 以及 torchbenchmark；
• pull-deps：在 clone 基础上，按 .github/ci_commit_pins/ 下的 pin 文件切换到指定提交（保证与 CI 一致的版本）并更新子模块；
• build-deps：使用 uv pip install 安装基础 Python 依赖，并以可编辑模式（-e .）安装各依赖包，最后执行 python install.py 安装 TorchBench 模型。

build-deps 支持按需安装单个或多个 TorchBench 模型，例如：

make build-deps TORCHBENCH_MODELS="alexnet"
make build-deps TORCHBENCH_MODELS="alexnet basic_gnn_gcn BERT_pytorch"
# TORCHBENCH_MODELS=""（空）表示安装全部 TorchBench 模型

对于 HuggingFace / TIMM 套件，无需提前枚举安装：入口脚本会在缺失依赖时自动处理（TIMM 见 timm_models.py 的自动安装逻辑）。

统一入口：三个 Runner 脚本与共享 CLI

运行三套评测的命令形态完全一致，各自脚本名对应不同套件：

./benchmarks/dynamo/torchbench.py ...
./benchmarks/dynamo/huggingface.py ...
./benchmarks/dynamo/timm_models.py ...

三者的参数解析集中在 common.py 的 parse_args()，并经由 main(runner, ...)（见 common.py）统一分发执行。由于这些脚本对当前工作目录较敏感（TorchBench 需要 chdir 到其安装目录，见 torchbench.py），README 与源码均建议从仓库根目录（项目根）直接以 ./benchmarks/dynamo/xxx.py 的形式运行。

核心参数速查表

以下参数是复现看板/做自定义评测最常用的一组，均见 README，并与 parse_args() 中定义一一对应：

参数 / 环境变量	取值与含义
--accuracy 或 --performance	互斥必选：--accuracy 以小 batch + eval 模式做正确性校验；--performance 测量相对 eager 的加速比。看板两种都会跑
--training 或 --inference	互斥必选：选择评测训练还是推理。看板两种都会跑
--device=cuda / --device=cpu	选择评测设备（参数解析还接受 hpu、--device-index 指定具体卡）
--amp / --bfloat16 / --float16 / --float32	互斥的精度选择组：--amp 用于训练，--bfloat16 用于推理，构成看板首行配置；另有 --amp-dtype={bfloat16,float16} 可指定 AMP 精度
--cold-start-latency	每次运行模型都使用全新的 Triton 缓存目录，强制冷启动编译，用于准确测量编译耗时（源码 common.py）；与 --warm-start-latency 互斥
--backend=inductor	选择编译后端，默认候选来自 torch._dynamo.list_backends()；inductor 即 TorchInductor，更多后端见 --help
--output=<filename>.csv	结果 CSV 输出路径（同名的 .json 会一并生成，供看板上报）
--dynamic-shapes / --dynamic-batch-only	动态形状配置；--dynamic-batch-only 隐含 --dynamic-shapes，仅把 batch 维视为动态
--disable-cudagraphs	关闭 CUDA graphs（默认配置即关闭，用于无 cudagraphs 的对比）
--freezing	仅推理场景，启用额外优化（参数/常量折叠冻结）
--cpp-wrapper	启用 C++ wrapper 代码以降低运行时开销（见 README 的 dashboard 复现说明）
TORCHINDUCTOR_MAX_AUTOTUNE=1（环境变量）	测量 max-autotune 模式（编译时间更长，看板每周执行一次）
--export-aot-inductor	评测 ahead-of-time（AOT）编译模式：先导出 FX Graph 再走 AOTInductor
--total-partitions / --partition-id	将套件划分为若干分片并行跑（参数解析约束 --total-partitions 取 1~15），用于跨机器并行
--only=<NAME>	只运行单个模型，便于调试；详见下文

常用调试/过滤参数还包括：--filter/-k、--exclude/-x、--exclude-exact（正则/精确名过滤）；--repeat/-n（默认 30 次计时取中位数）；--batch-size（覆盖默认 batch）；--no-skip（强制运行跳过名单中的模型）；--fast/-f（跳过慢模型）；--inductor-config/-c key=value（直接注入 torch._inductor.config）。完整清单请对任一脚本运行 --help。

精度与容差如何工作

--accuracy 模式会将编译模型输出与 eager 模型输出对齐校验。校验手段与容差来自三处：

1. 每套件的 YAML 为具体模型声明了分级容差，如 torchbench.yaml 中的 tolerance.higher_fp16（1e-2）、even_higher（8e-2）等，fp16/bf16/AMP 场景取更宽容差（见 torchbench.py）；
2. 非确定性模型会单独跳过精度比对或改用 cosine 相似度（--cosine）；
3. 训练精度基于 loss 归约比较，见 reduce_to_scalar_loss 与 torchbench.py。

另外源码为 CI 可复现性固定了随机种子：patch_torch_manual_seed() 将 torch.manual_seed 固定为 1337（见 common.py），batch 变化场景还会在每次迭代重置 RNG（common.py）。

复现看板首行：完整命令示例

README 给出的“复现看板第一行（仅 performance）”命令如下，覆盖三套件 × （训练 + 推理）：

./benchmarks/dynamo/torchbench.py --performance --training --amp --backend=inductor --output=torchbench_training.csv
./benchmarks/dynamo/torchbench.py --performance --inference --bfloat16 --backend=inductor --output=torchbench_inference.csv

./benchmarks/dynamo/huggingface.py --performance --training --amp --backend=inductor --output=huggingface_training.csv
./benchmarks/dynamo/huggingface.py --performance --inference --bfloat16 --backend=inductor --output=huggingface_inference.csv

./benchmarks/dynamo/timm_models.py --performance --training --amp --backend=inductor --output=timm_models_training.csv
./benchmarks/dynamo/timm_models.py --performance --inference --bfloat16 --backend=inductor --output=timm_models_inference.csv

要点：

• 精度搭配：训练统一用 --amp（自动混合精度），推理统一用 --bfloat16，这与上一节参数表的说明一致；
• 后端：--backend=inductor 表示评测 TorchInductor；
• 首次运行 HuggingFace/TIMM 套件会下载模型，耗时较长；训练套件通常也比推理更慢。

单模型调试：--only

完整跑完三套件代价很高，README 建议调试阶段用 --only=<NAME> 只跑单个模型：

./benchmarks/dynamo/torchbench.py --performance --inference --bfloat16 --backend=inductor --only=resnet50 --output=single.csv

单模型调试更常用的组合是降低重复次数、关闭不必要的输出，例如：

./benchmarks/dynamo/torchbench.py --performance --inference --bfloat16 --backend=inductor \
  --only=resnet50 --repeat=3 --disable-output

其中 --repeat 控制计时轮数，--disable-output 表示跳过结果文件写入（源码 common.py）。

此外，--only 还支持直接加载自定义模型文件（不需要预先进入套件模型列表），格式为：

--only=path:/absolute/path/to/model.py,class:LinearModel

要求：path 必须是绝对路径（因为 dynamo 会改变当前工作目录）、类需继承 torch.nn.Module 并实现 get_example_inputs() 方法返回示例输入（详见 common.py 中 load_model_from_path 的说明与示例）。这对快速验证“我的自定义模型在 inductor 下表现如何”非常实用。

性能如何测得：底层实验流程与结果解读

eager 与编译交替计时

--performance 实际调用 common.py 的 speedup_experiment：在每一轮计时中先用 torch.compiler.set_stance("force_eager") 测 eager 基线，再测编译后模型，交替插桩计时以抵消频率缩放与机器负载波动（见 common.py）。最终加速比 = eager 中位耗时 / 编译模型中位耗时，均值为多轮取中位数，避免单次抖动。

结果文件与汇总

• 主结果写入 --output 指定的 CSV，含 dev、name、batch_size、speedup、abs_latency 等列；同时为上报看板而追加写入同名 .json（见 common.py，JSON 记录中携带 device、quantization、batch_size 等 extra_info）；
• 若开启 --print-memory / dashboard 内存测量等，CSV 会扩展 compilation_latency、compression_ratio、eager_peak_mem、dynamo_peak_mem 等列（见 common.py）；
• 编译阶段统计另写 <output 前缀>_compilation_metrics.csv；
• 控制台会用几何平均汇总各列（gmean=…），accuracy 列则统计 pass_rate（见 common.py）。

因此看板上的 2.38x → 2.41x 只是对全体模型做 gmean 后的结果；要定位具体是哪个模型提升/回退，直接查看对应 CSV 中每个模型的 speedup 行即可。

从“跑起来”到“测得准”：进阶使用建议

• 冷启动 vs 稳态：要衡量真实编译开销，用 --cold-start-latency（每次新建 Triton 缓存目录）；只想看稳态推理性能则不必加该参数；
• 动态形状评测：--dynamic-shapes 与 --dynamic-batch-only 专用于开启 dynamic 配置的回归场景，注意部分模型（如 sam、llama、detectron2 系列、dlrm 等）在动态 batch 下有已知限制，仓库在 CI_SKIP_DYNAMIC_BATCH_ONLY 集合中集中管理（见 common.py）；
• 训练态差异：部分模型在 eager Adam 基准下精度不稳，仓库为它们回退到 SGD（BENCHMARK_USE_SGD、CI_USE_SGD，见 common.py），自行做训练精度评测时若遇到失败可参考该名单；
• AOT 与端侧：--export-aot-inductor、--export-nativert、--torchscript-jit-trace 等选项让同一套模型集合可延伸到 AOT 编译、NativeRT、TorchScript 等不同执行路径的对比；
• 分片并行：大规模评测用 --total-partitions=N --partition-id=i 切分到 N 台机器并行，最后用 join_results.py 之类脚本合并。

若希望校验自己的改动没有引入回归，仓库还提供了与 CI 预期值对照的脚本（check_perf_csv.py、check_accuracy.py，以及 expected_ci_perf_inductor_torchbench.csv 等预期文件），可把本地产出与预期基线比对，作为开发过程中的回归闸门。

小结

benchmarks/dynamo 目录是一套以真实模型驱动、以 eager 为 1x 基准、面向 TorchDynamo/TorchInductor 的完整评测体系：torchbench.py / huggingface.py / timm_models.py 三个入口共享 common.py 的统一参数与执行框架，YAML 描述各套件的模型名单与容差策略，CSV/JSON 输出既可直接阅读也可上报性能看板。对普通使用者来说，最常需要记住的只有三件事：用 Makefile 备好依赖、用 --only=<模型名> 快速单点验证、用文档中的六条命令即可完整复现看板首行的 performance 结果。

想要更深入地理解评测管线，建议顺着 common.py 的 BenchmarkRunner 基类与 speedup_experiment、accuracy 相关实现继续阅读，同时对照 torchbench.yaml、huggingface.yaml 与 timm_models.yaml 体会“配置驱动评测”的设计思路。