企业官网建设流程全解析

CUTLASS GEMM Heuristics 指南：用解析式启发式缩小自动调优搜索空间

【免费下载链接】cutlassCUDA Templates and Python DSLs for High-Performance Linear Algebra项目地址: https://gitcode.com/GitHub_Trending/cu/cutlass

导读

本文讲解 CUTLASS 仓库中位于 media/docs/cpp/heuristics.md 的 GEMM Heuristics 功能：它通过 NVIDIAnvidia-matmul-heuristics解析式（analytical）启发式模型，为给定的 GEMM 问题规模与硬件 SKU 直接预测并排序各 kernel 配置的预估性能，从而只构建和评测一小部分候选 kernel，大幅缩小运行时自动调优（autotuning）的搜索空间。读完本文，你将掌握：如何编写 GEMM 问题定义 JSON、如何通过 CMake 选项与cutlass_profiler完成"启发式选核 → 构建 → 评测"的完整闭环，以及如何直接调用 Python API 进行 kernel 筛选。

概述：为什么要用 Heuristics 压缩搜索空间

CUTLASS 的cutlass_library传统上通过穷举配置（CTA tile、instruction tile、pipeline stages、cluster 形状等）为每个 GEMM 问题实例化大量 kernel，再由运行时自动调优逐一 profiling 选出最快者。这种"构建全部 → 全部评测"的流程在配置空间巨大时成本很高。

Gemm heuristics 的目的正是减少运行时自动调优的搜索空间：只让一个"有依据的子集"进入构建与评测阶段。其底层使用 NVIDIA 的nvidia-matmul-heuristics——一种解析式启发式模型，能够根据问题尺寸（m/n/k）与硬件 SKU 对 GEMM kernel 按预估性能排序。从源码结构看，这一集成被设计为cutlass_library中的实验性功能，官方在文档中明确声明不保证完整的功能或性能覆盖。

功能覆盖范围（当前版本边界）

在编写问题文件与选择硬件前，务必确认当前版本支持的范围：

• 问题空间：仅支持普通稠密（plain dense）GEMM，数据类型限于f8、f16、f32；
• 硬件：仅支持 Hopper（sm9x）与 Blackwell（sm10x）两代架构。

超出上述范围的问题定义不会被启发式模型正确评估，这也是CUTLASS_LIBRARY_HEURISTICS_RESTRICT_KERNELS等规避选项存在的原因（见下文）。

快速上手：从依赖安装到 Profile 全流程

1. 安装依赖

推荐直接安装官方 wheel：

pip install nvidia-matmul-heuristics

该包通过python/cutlass_library/heuristics_provider.py中的MatmulHeuristics类被加载。值得注意的兼容性细节：nvidia-matmul-heuristics0.1.0.28 版本修改了 API（构造函数移除gpu与load_discovery_implicitly参数，GPU 改由createHardwareDescriptor()+setHardwarePredefinedGpu()指定），该源码通过检测构造函数签名自动区分新旧 API，因此建议保持 wheel 为较新版本。若需要指定动态库路径，可设置环境变量CUTLASS_NVMMH_SO_PATH。

2. 准备问题输入文件（JSON）

启发式模型需要一份JSON list形式的 GEMM 问题定义。下面沿用官方文档示例，包含两个问题（一个 FP16、一个 FP8）：

[ { "m" : 4096, "n" : 4096, "k" : 4096, "batch_count" : 1, "layout" : "tnn", "dtype_a" : "f16", "dtype_b" : "f16", "dtype_c" : "f16", "dtype_acc" : "f32", "dtype_d" : "f16", "beta" : 0.0, "use_fast_acc": false }, { "m" : 4096, "n" : 4096, "k" : 4096, "batch_count" : 1, "layout": "tnn", "dtype_a" : "e5m2", "dtype_b" : "e5m2", "dtype_c" : "f32", "dtype_acc" : "f32", "dtype_d" : "e5m2", "beta" : 0.0, "use_fast_acc": true } ]

字段说明与默认值（依据 python/cutlass_library/heuristics.py 中get_gemm_configs()的参数解析）：

重要限制：use_fast_acc仅对SM90 上的 FP8 kernel有意义，其他精度下该字段被忽略（文档明确说明）。从 python/cutlass_library/heuristics_provider.py 可以看到，它通过后端属性DISABLE_FAST_ACC_FOR_FP8传入启发式库。

3. 构建：通过 CMake 启用 Heuristics

使用常规 CMake 流程构建 CUTLASS，并附加 heuristics 相关选项。硬件信息在联网构建时会自动检测（基于 CUDA Driver API）；离线构建则需用-DCUTLASS_LIBRARY_HEURISTICS_GPU显式指定。以下是最小化的 Hopper（sm90）示例命令：

$ cmake .. \ -DCUTLASS_NVCC_ARCHS=90a \ -DCUTLASS_LIBRARY_HEURISTICS_PROBLEMS_FILE=<path_to_your_problem_list.json> \ -DCUTLASS_LIBRARY_HEURISTICS_CONFIGS_PER_PROBLEM=<number of configurations to build per problem> ... ... $ make cutlass_profiler -j

构建完成后会产出一份CSV testlist，其中包含自动调优所需的全部测试用例（每个 kernel 及其运行时参数）。该文件默认输出到构建目录下的heuristics.csv（见 tools/library/CMakeLists.txt），可用-DCUTLASS_LIBRARY_HEURISTICS_TESTLIST_FILE修改位置。

CMake 选项一览（官方文档 + 源码确认）：

• CUTLASS_LIBRARY_HEURISTICS_PROBLEMS_FILE：指向包含 GEMM 问题 JSON list 的文件路径；顶层 CMakeLists.txt 会将其转换为绝对路径后传入生成器。
• CUTLASS_LIBRARY_HEURISTICS_CONFIGS_PER_PROBLEM：每个 GEMM 问题启发式返回的配置数上限（同一配置/kernel 可被多个问题共享）。对应生成器参数--heuristics-configs-per-problem，默认值为10（见 python/cutlass_library/generator.py）。
• CUTLASS_LIBRARY_HEURISTICS_RESTRICT_KERNELS：布尔选项，默认OFF（构建全部启发式建议的配置）。置为ON时，仅构建默认 CUTLASS CMake 流程实例化的 kernel 集合，并与CUTLASS_LIBRARY_INSTANTIATION_LEVEL等选项组合生效。当启发式建议的 kernel 配置在当前平台无法构建时（某些不支持或实验性场景），可将其置为ON作为规避手段。
• CUTLASS_LIBRARY_HEURISTICS_TESTLIST_FILE：输出 CSV 的路径，该文件可直接被cutlass_profiler消费。
• CUTLASS_LIBRARY_HEURISTICS_GPU：离线构建时指定目标 GPU，例如H100_SXM。未设置时通过 CUDA Driver API 自动检测硬件属性。合法字符串以 python/cutlass_library/generator.py 中--heuristics-gpu的choices为准，包括：H100_SXM、H100_PCIE、H100_NVL、H200_SXM、H20_SXM、B200、GB200_NVL、RTX_5080、RTX_5090、RTX_PRO_6000（另有''/auto表示自动检测）。注意文档正文示例中的H100_SXM5与源码枚举略有差异，应以 generator.py 的实际枚举为准。

构建链路：上述选项在 tools/library/CMakeLists.txt 中被组装为HEURISTICS_ARGS（--heuristics-problems-file、--heuristics-testlist-file、--heuristics-configs-per-problem，以及按需的--heuristics-restrict-kernels、--heuristics-gpu），随后附加到generator.py的执行命令中。生成日志输出到构建目录的library_instance_generation.log。

4. Profile：用 CSV 驱动 cutlass_profiler

用上一步产出的 testlist CSV 运行cutlass_profiler，收集每个测试用例的性能数据，从而确定每个输入问题最快的已构建 kernel 配置。以下命令固定每个测试用例评测 50ms：

cutlass_profiler --operation=Gemm --testlist-file=<path_to_your_testlist.csv> --profiling-iterations=0 --profiling-duration=50 --verification-enabled=false --output=<path_to_outfile>

其中--profiling-iterations=0表示不按迭代次数、而是按--profiling-duration指定的毫秒时长来评测；--verification-enabled=false关闭正确性校验以节省评测时间；--output指定结果输出文件。

源码级原理：启发式如何转化为可构建的 kernel

整个流程的核心实现在 python/cutlass_library/heuristics.py 与 python/cutlass_library/heuristics_provider.py 两个文件中，可由 CMake 触发，也可由 Python 直接调用。

调用链一：filter_manifest_and_write_heuristics_file()（CMake 构建入口）

当 CMake 检测到CUTLASS_LIBRARY_HEURISTICS_PROBLEMS_FILE时，会在生成器流程中调用该函数（generator.py）。其职责：

1. 读取 JSON 问题列表；
2. 解析--heuristics-gpu（None/auto/""表示自动检测），构造MatmulHeuristics(gpu=...)；
3. 若架构列表包含sm100，调用mmh.set_cta_div_n(64)，将 CTA tile 的 N 维度设为 64 的倍数（对应后端属性CTA_TILE_N_DIV_REQUIREMENT）——这是为 Blackwell 平台特设的约束；
4. 逐问题调用get_gemm_configs()获得建议配置；
5. 按架构（sm90/sm100/sm101）分别调用generate_sm90_from_heuristics_configs()或generate_sm100_from_heuristics_configs()，把启发式建议翻译为 CUTLASSGemmOperation并注册进 manifest；--heuristics-restrict-kernels为真时传入空 manifest 以"只生成不注册"；
6. 通过write_profiler_testlist_to_csv()将"问题 + kernel 配置 + 运行时参数"序列化为cutlass_profiler可消费的 CSV。

调用链二：get_single_gemm_config()与MatmulHeuristics.get_configs()

get_single_gemm_config()（heuristics.py）是对MatmulHeuristics.get_configs()的薄封装。后者在 heuristics_provider.py 中完成关键翻译：

• 将 CUTLASS 的DataType映射为 cuBLAS 风格精度字符串（如f16→H、f32→S、e4m3→Q、e5m2→R），组合为precision串；
• 将LayoutType三元组映射为NvMatmulHeuristicsMatmulLayout（前两维取 A/B 的 n/t 大写组合，第三维按 C/D 的行/列主序）；
• 调用getEx()获取按预估运行时间排序的配置列表；
• 每个返回的 kernel 配置被提取为结构化字典，包含：cta_tile_m/n/k、instr_tile_m/n/k、warp_tile_m/n/k、cluster_m/n/k、swizzle_size、raster_order（along_m/along_n，由cta_order推断）、split_k_slices、estimated_runtime，以及 dtype、layout、alignment、use_fast_acc、voidC等字段。

其中voidC由beta == 0.0推导（beta==0时 C 可为 void，跳过 C 的读写）。这些字段正是后续生成TileDescription、MathInstruction与 schedule 的直接输入。

架构分支：SM90 与 SM100 的生成差异

• SM90（generate_sm90_from_heuristics_configs，heuristics.py）：将建议配置填入TileDescription后，通过get_valid_schedules()依据 CUDA 版本、对齐性、数据类型、use_fast_acc等推导合法的主 schedule 与 StreamK schedule，最终经CreateGemmUniversal3xOperator()生成 3x collective 风格的 Universal GEMM kernel；StreamK 变体使用TileSchedulerType.StreamK。
• SM100（generate_sm100_from_heuristics_configs，heuristics.py）：依据cluster_m奇偶性推断是否为 2SM 指令（is_2sm = cluster_m % 2 == 0），据此调整 instruction shape，并选择TmaWarpSpecialized1SmSm100/TmaWarpSpecialized2SmSm100等 schedule，同样支持 StreamK tile scheduler。

这些生成逻辑与 CUTLASS 3.x 的 collective builder 代码路径一致，最终统一通过 manifest 的 kernel filter 注册进待构建列表。

直接使用 Python API（自定义 emitter 场景）

如果已经预构建了 CUTLASS kernel，或者使用自定义的 CUTLASS emitter，可以直接在 Python 中调用相关 API 选择要构建或评测的 kernel，参考filter_manifest_and_write_heuristics_file()（heuristics.py）的用法：

• get_single_gemm_config(m, n, k, batch_count, layouts, dtypes, alignment_a, alignment_b, voidC, use_fast_acc, count, provider)：单问题选核，返回含 CTA tile、指令 tile、stages、cluster、swizzle、raster order、splitK 等完整字段的配置字典列表；
• get_gemm_configs(problems, provider, count)：批量问题选核，对每个问题字典追加configs键，返回结果可直接用于后续 kernel 生成；
• serialize_heuristics_results_to_json(problems_with_configs, outfile_path)：将结果（含DataType/LayoutType枚举）序列化为可读 JSON，便于调试；
• write_profiler_testlist_to_csv(configs_list, outfile_path)：把配置列表写成cutlass_profiler可消费的 CSV testlist。

这些函数组合起来，可以在不经过 CMake 的前提下复现"启发式选核 → 生成 kernel → 输出 profiler testlist"的完整数据流。

小结与注意事项

• GEMM Heuristics 是cutlass_library的实验性特性，功能与性能覆盖不保证完备，使用前请确认问题空间（f8/f16/f32稠密 GEMM）与硬件（Hopper sm9x、Blackwell sm10x）在支持范围内；
• use_fast_acc只影响 SM90 的 FP8 kernel；离线构建务必用-DCUTLASS_LIBRARY_HEURISTICS_GPU指定 GPU，其合法取值以 python/cutlass_library/generator.py 的枚举为准；
• 若启发式建议的 kernel 在目标平台构建失败，将CUTLASS_LIBRARY_HEURISTICS_RESTRICT_KERNELS=ON可回退到默认 kernel 集合；
• 完整工作流为：pip install nvidia-matmul-heuristics→ 编写问题 JSON → CMake 构建（产出heuristics.csvtestlist）→cutlass_profiler评测，最终以实测数据确定每个问题的最快 kernel 配置。

【免费下载链接】cutlassCUDA Templates and Python DSLs for High-Performance Linear Algebra项目地址: https://gitcode.com/GitHub_Trending/cu/cutlass