CUTLASS README v4.4.0

概述

CUTLASS 4.4.0

CUTLASS 4.4.0 - 2026年1月

CUTLASS 是一套在 CUDA 中所有层次和规模上实现高性能矩阵乘法（GEMM）及相关计算的抽象集合。它融合了分层分解和数据移动的策略。CUTLASS 将这些"可动部件"分解为可重用、模块化的软件组件和抽象。

概念性并行化层次结构中不同级别的原语可以通过自定义分块大小、数据类型和其他算法策略进行专门化和调优。由此产生的灵活性简化了它们作为自定义内核和应用程序中构建块的使用。

自 2017 年以来，CUTLASS 一直为高性能线性代数提供 CUDA C++ 模板抽象，这些抽象为广泛的计算提供了广泛的支持，包括混合精度计算、专有数据移动（异步拷贝）以及适用于 FP64、FP32、TF32、FP16、BF16、通过张量核心指令进行的 FP32 模拟、8位浮点类型（e5m2 和 e4m3）、块缩放数据类型（NVIDIA NVFP4 和 OCP 标准 MXFP4、MXFP6、MXFP8）、窄位宽整数类型（4位和8位有符号及无符号整数）以及二元1位数据类型（在架构允许原生支持此类数据类型的情况下），横跨 NVIDIA 的 Volta、Turing、Ampere、Ada、Hopper 和 Blackwell 架构。

在这个丰富的基于 C++ 的内核编程抽象生态系统之上，CUTLASS 4 新增了 CUTLASS DSLs 。这些是原生的 Python 接口 ，用于基于核心 CUTLASS 和 CuTe 概念编写高性能 CUDA 内核，且无任何性能妥协。这带来了更平缓的学习曲线、数量级更快的编译时间、与深度学习框架的原生集成（无需编写胶水代码），以及更直观、无需深厚 C++ 专业知识的元编程。

总体而言，我们将 CUTLASS DSLs 设想为一个领域特定语言（DSL）家族 。随着 4.0 版本的发布，我们推出了其中第一个：CuTe DSL。这是一个低层编程模型，与 CuTe C++ 抽象完全一致 ------它暴露了诸如布局、张量、硬件原子等核心概念，并允许对硬件线程和数据层次结构进行完全控制。

CuTe DSL 展示了针对由 NVIDIA 的 Ampere、Hopper 和 Blackwell 架构实现的可编程、高吞吐量张量核心的最优矩阵乘法和其他线性代数操作。

我们相信它将成为学生、研究人员和性能工程师不可或缺的工具------拉平 GPU 编程的学习曲线、快速进行内核设计原型，并将优化方案带入生产。

CuTe DSL 目前处于公开测试阶段，计划于 2025 年夏季末结束测试。

快速入门 - 请参考：

CUTLASS 4.4 新特性

CuTe DSL

新功能

CuTe DSL 现已支持 CUDA 工具包 13.1！
- 使用 cutlass/python/CuTeDSL/setup.sh --cu13 进行设置。
- 详情请参考 CuTe DSL 快速入门指南。
GB300 现已在 CTK 13.1 下的 CuTe DSL 中得到支持。
- 参考 SM103 批量 3xFP4 块缩放 GEMM 内核作为示例内核。
cute.experimental：在现有 CuTe DSL API 之上引入一个更高层次、可组合的层（并非独立的抽象），它可以与现有的 CuTe DSL 构建块混合使用。
- 无碎片编程模型：copy/dot API 直接接受内存引用，而不是描述符/碎片。
- 自动 TMA 描述符生成和更新插入。
- SIMT 拷贝的自动向量化和谓词化。
- 带有便利包装器的新流水线抽象。
- 新的分区操作以简化分区逻辑。
- 设备端 TMA 描述符的分配、初始化和管理。
提前编译（AoT）现已可用！
- 参考 https://github.com/NVIDIA/cutlass/tree/main/examples/python/CuTeDSL/cute/export 下的文件获取使用示例。
JAX 支持 - 您现在可以将 CuTeDSL 与 JAX 一起使用。
- 参考 https://github.com/NVIDIA/cutlass/tree/main/examples/python/CuTeDSL/jax 下的文件获取使用示例。
在 DSL 中引入了版本支持：
- cutlass.version 用于获取 DSL 版本的字符串表示。
- cutlass.CUDA_VERSION 用于获取表示 DSL 所用 CUDA 版本的版本类。
添加了 CopyDsmemStoreOp，用于将数据存储到分布式共享内存并带有显式同步。

新增峰值性能内核示例

SM103 批量 3xFP4 块缩放 GEMM 内核

Bug 修复与改进

修复了 if 语句的两个分支都被执行的问题。
修复了使用 f-string 的 cute.printf。
修复了 cutlass.cuda.initialize_cuda_context() 静默终止 Python 进程的问题。

API 变更

弃用 blackwell_helpers.py 中的 get_num_tmem_alloc_cols。请改用 tmem_allocator.py 中的对应函数。
弃用 SM100_TMEM_CAPACITY_COLUMNS 和 SM100_TMEM_MIN_ALLOC_COLUMNS。
LdMatrix16x16x8bOp 和 StMatrix16x8x8bOp 现在在调用 init 时，如果需要转置，必须显式指定 transpose=True，以避免数据转置的歧义。
LdMatrix16x16x8bOp 的拷贝特性已更新，以忠实于 PTX 而不进行置换。带置换的变体已重命名为 LdMatrix16x8x8bOp。
异步批量拷贝示例中的 group_bulk_copy_modes 现已弃用，请直接使用 group_modes。
cute.arch.calc_packed_f32x2_op 默认启用 ftz 改为默认禁用 ftz。
在 CTK 13.1 下的 CuTe DSL 中，cutlass.cute.arch 中的以下 API 现在要求使用字符串字面量作为参数，而不是枚举：
- fence_proxy
- fence_view_async_tmem_op
- calc_packed_f32x2_op
- warp_redux_sync
- atomic_add, atomic_and, atomic_or, atomic_xor, atomic_max, atomic_min, atomic_exch, atomic_cas
- store
- load

CUTLASS C++

新增功能

添加了 Hopper e2m1 到 fp32 的优化转换以及 e2m1 * TF32 张量核心 GEMM。
- 在 FP32 模式下，将 MmaType 设置为 tfloat32_t。
- TF32 提供精度降低的 FP32 输入（19 位对比 32 位）。
- 对于 TF32，设置 TileShapeK=64（K 必须是 8 的倍数）。
- 通过 compute_memory_reordering_atom<tfloat32_t>() 启用洗牌优化。
- 为混合精度 GEMM 启用 E2M1 -> FP32 -> TF32 张量核心路径。
- 在示例 55 中启用 TF32 支持。
新增示例 93，用于展示 Blackwell 低延迟生成阶段的 GQA 内核。
- 内核设计详情请查看 Readme。
新增示例 94，用于展示 Ada FP8xFP8 -> BF16 GEMM，并在 MMA 循环中对输入矩阵进行块级去量化，使用 FP32 累加。
- 在 CUTLASS 的 include 目录中生成额外的 device/kernel/threadblock 文件，以添加携带缩放张量并在 MMA 循环中使用它们的功能。
- 将 gemm_blockwise 添加到 default_mma_core_sm80 的包含文件中。
在示例 111 中新增 Hopper SM90 状态空间分解（SSD）内核。
在示例 112 中新增 Blackwell SM100 状态空间分解（SSD）内核。
新增对块缩放张量的任意应用提供步长的支持。
- 用户和应用程序现在在所有情况下都必须传递有效的块缩放步长，即使张量是打包的。
支持 CUDA 13.1 的 4x 块缩放公共 PTX。
允许在 AuxTmaParams 中使用非静态的 TmaGbasis。
- 注意力内核中的某些情况可能需要非静态的 tma_gbasis。
- 放宽对 AuxTmaParams 的 TmaGbasis 参数的限制，允许用户手动构造动态的 gbasis。

内核问题修复

修复了 MSVC 预处理问题。
修复了 GEMV 内核中的一个自我赋值问题。
修复了一个 TMA 描述符的 bug，即 CUDA 驱动未正确设置 OOB 地址生成模式。
修复了 Blackwell SM120 乒乓内核中 CLC 调度器的内存栅栏。
修复了 Blackwell SM120 缩放因子中缺失的 SMEM 对齐。
修复了分组 GEMM 的一个 PDL 问题。

性能分析器问题修复

重构 L1 功能测试生成逻辑，减少 L1 测试用例以避免超时。
修复了 nvfp4 分组 GEMM 内核的一个核心转储问题。
修复了不一致的 GEMM 验证逻辑。
为不同类型重新设计了分组 GEMM 验证逻辑。

其他修复

修复了 media/docs 下的一些失效链接。

注意：已知 CUTLASS 4.x 在 Windows 平台上的构建对所有 CUDA 工具包均存在问题。CUTLASS 团队正在修复中。

详情请参阅 CHANGELOG 了解所有过去版本和更新的详细信息。

性能

CUTLASS 原语非常高效。当用于构建设备级 GEMM 内核时，它们展现出接近峰值理论吞吐量的利用率。下图显示了 CUTLASS 3.8 在 NVIDIA Blackwell SM100 架构 GPU 上运行时的性能，表现为各种输入和输出数据类型的理论峰值利用率的百分比。

(此处应有性能对比图)

以下两图显示了自 CUTLASS 3.1 以来，在 NVIDIA H100（NVIDIA Hopper 架构）上 CUTLASS 性能的持续改进。CUTLASS 3.5.1 使用 CUDA 12.5u1 工具包编译。张量核心操作使用 CUDA 的 mma 和 wgmma 指令实现。

(此处应有性能趋势图)

CuTe

CUTLASS 3.0 引入了一个新的核心库 CuTe ，用于描述和操作线程和数据的张量。CuTe 是一个 CUDA C++ 模板抽象集合，用于定义和操作线程及数据的分层多维布局。CuTe 提供 Layout 和 Tensor 对象，它们紧凑地封装了数据的类型、形状、内存空间和布局，同时为用户执行复杂的索引计算。这让程序员能够专注于算法的逻辑描述，而 CuTe 则为他们处理机械性的簿记工作。利用这些工具，我们可以快速设计、实现和修改所有稠密线性代数操作。

CuTe 的核心抽象是分层多维布局，它们可以与数据数组组合以表示张量。布局的表示能力足以代表实现高效稠密线性代数所需的大部分内容。布局也可以通过函数式组合进行操作，基于此我们构建了大量常见操作，例如分块和分区。

CUTLASS 3.0 及更高版本在其模板中全面采用 CuTe。这极大地简化了设计，并提高了代码的可组合性和可读性。更多关于 CuTe 的特定文档可以在其专用文档目录中找到。

兼容性

最低要求：

架构：Volta（计算能力 7.0）
编译器：必须至少支持 C++17
CUDA 工具包版本：11.4

CUTLASS 需要 C++17 主机编译器，并在使用 CUDA 12.8 工具包构建时性能最佳。它也兼容 CUDA 11.4、11.5、11.6、11.7、11.8 以及所有其他 CUDA 12.x 版本。

操作系统

我们已测试以下环境：

操作系统	编译器
Ubuntu 18.04	GCC 7.5.0
Ubuntu 20.04	GCC 10.3.0
Ubuntu 22.04	GCC 11.2.0

注意：已知 GCC 8.5.0 在折叠表达式和重载运算符方面存在退化问题。建议使用 GCC 7.5.0 或（首选）GCC >= 9。

注意：已知 CUTLASS 3.x 在 Windows 平台上的构建对所有 CUDA 工具包均存在问题。CUTLASS 团队正在修复中。

硬件

CUTLASS 已成功在以下 NVIDIA GPU 上运行，并且预期在基于 Volta、Turing、Ampere、Ada 和 Hopper 架构的 NVIDIA GPU 上高效运行。

GPU	CUDA 计算能力	CUTLASS-3 要求的最低 CUDA 工具包
NVIDIA V100 Tensor Core GPU	7.0	11.4
NVIDIA TitanV	7.0	11.4
NVIDIA GeForce RTX 20x0 系列	7.5	11.4
NVIDIA T4	7.5	11.4
NVIDIA A100 Tensor Core GPU	8.0	11.4
NVIDIA A10	8.6	11.4
NVIDIA GeForce RTX 30x0 系列	8.6	11.4
NVIDIA GeForce RTX 40x0 系列	8.9	11.8
NVIDIA L40	8.9	11.8
NVIDIA H100 Tensor Core GPU	9.0	11.8
NVIDIA H200 Tensor Core GPU	9.0	11.8
NVIDIA B200 Tensor Core GPU	10.0	12.8
NVIDIA B300 Tensor Core GPU	10.3	13.0
NVIDIA DRIVE Thor	11.0	13.0
NVIDIA GeForce RTX 50x0 系列	12.0	12.8
NVIDIA DGX Spark	12.1	13.0

目标架构

通常，为一个目标架构生成的 PTX 代码可以在未来的架构上运行（即具有前向兼容性）。然而，CUDA 12.0 引入了"架构加速特性"的概念，其 PTX 不保证前向兼容性。几个 Hopper 和 Blackwell 的 PTX 指令属于这类架构加速特性，因此需要 sm_90a 或 sm100a 目标架构（注意末尾的 "a"）。有关此特性及其他架构加速指令的更多详情，请参阅 CUDA 文档。

目标架构信息通过 CMake 标志 CUTLASS_NVCC_ARCHS 传递给 CUTLASS。为了在 Hopper GH100 上最大化性能，用户需要以 90a 为目标架构构建 CUTLASS。如果用户错误地使用 SM90 目标（注意缺少 "a"）构建了一个使用 SM90a 特性（例如 Hopper 张量核心指令）的内核（使用 CUDA 工具包 12 或 11.8），则该内核预计会在运行时出错。

复制代码

cmake .. -DCUTLASS_NVCC_ARCHS="90a"

或

复制代码

cmake .. -DCUTLASS_NVCC_ARCHS="100a"

注意：数据中心产品中使用的 NVIDIA Blackwell SM100 架构与支撑 NVIDIA Blackwell GeForce RTX 50 系列 GPU（SM120）的计算能力不同。因此，为带有架构条件特性（使用 sm100a）的 Blackwell SM100 架构编译的内核与 RTX 50 系列 GPU 不兼容。

请参阅功能文档了解哪些内核需要哪些目标架构的详细信息。

文档

CUTLASS 在以下文档及随附的 Doxygen 文档中进行了描述。

快速入门指南 - 构建和运行 CUTLASS 的基础知识
功能 - 总结 CUTLASS 中可用的功能
CUDA 中的高效 GEMM - 描述如何在 CUDA 中高效实现 GEMM 内核
CUTLASS 3.x 设计 - 描述 CUTLASS 3.x 设计、其优势，以及 CuTe 如何使我们能够编写更具可组合性的组件
GEMM API 3.x - 描述 CUTLASS 3.x GEMM 模型和 C++ 模板概念
GEMM API 2.x - 描述 CUTLASS 2.x GEMM 模型和 C++ 模板概念
隐式 GEMM 卷积 - 描述 CUTLASS 中的 2-D 和 3-D 卷积
代码组织 - 描述 CUTLASS 项目的组织和内容
术语 - 描述代码中使用的术语
编程指南 - 编写高效的现代 CUDA C++ 的指南
基本类型 - 描述 CUTLASS 中用于表示数值量和数组的基本 C++ 类
布局 - 描述矩阵和张量在内存中的布局
块迭代器 - 描述用于迭代内存中矩阵块的 C++ 概念
CUTLASS 性能分析器 - 命令行驱动的性能分析应用程序
CUTLASS 实用工具 - 用于促进快速开发的额外模板
依赖内核启动 - 描述 Hopper 中允许在同一流中重叠依赖内核的新特性，及其在 CUTLASS 中的用法

资源

我们还在 2018 年 GPU 技术大会的演讲中描述了一种高效 GEMM 的结构。

构建 CUTLASS

CUTLASS 是一个仅包含头文件的模板库，不需要构建即可被其他项目使用。客户端应用程序应在其包含路径中指定 CUTLASS 的 include/ 目录。

CUTLASS 单元测试、示例和实用程序可以使用 CMake 构建。CMake 的最低版本在快速入门指南中给出。确保 CUDACXX 环境变量指向系统上安装的 CUDA 工具包中的 NVCC。

复制代码

$ export CUDACXX=${CUDA_INSTALL_PATH}/bin/nvcc

在 CUTLASS 项目内创建一个构建目录，然后运行 CMake。默认情况下，CUTLASS 将为 CUDA 架构版本 5.0、6.0、6.1、7.0、7.5、8.0、8.6、8.9 和 9.0 构建内核。为了减少编译时间，您可以通过更改 CMake 配置设置 CUTLASS_NVCC_ARCHS 来指定要为哪些架构构建 CUTLASS。

复制代码

$ mkdir build && cd build
$ cmake .. -DCUTLASS_NVCC_ARCHS=80               # 为 NVIDIA Ampere 架构编译

从 build/ 目录，通过构建目标 test_unit 来编译和运行 CUTLASS 单元测试。

单元测试被组织为多个二进制文件，镜像 CUTLASS 的顶级命名空间，它们可以通过 make 的 -j 命令行参数并行执行。

复制代码

$ make test_unit -j

复制代码

...
...
...
[----------] Global test environment tear-down
[==========] 946 tests from 57 test cases ran. (10812 ms total)
[  PASSED  ] 946 tests.

所有测试应在受支持的平台上通过，尽管确切的测试数量可能随时间变化。

项目结构

CUTLASS 被安排为一个仅包含头文件的库，连同实用工具、工具、示例和单元测试。Doxygen 文档提供了 CUTLASS 项目中定义的所有文件、类和模板概念的完整列表。

源代码组织的详细解释可以在 CUTLASS 文档中找到，但以下几个主要组件总结如下。

CUTLASS 模板库

复制代码

include/                     # 客户端应用程序应在其构建的包含路径中指定此目录

  cutlass/                   # 用于线性代数子程序和求解器的 CUDA 模板 - 仅头文件

    arch/                    # 架构特性的直接暴露（包括指令级 GEMM）

    conv/                    # 专用于卷积的代码

    epilogue/                # 专用于 gemm/卷积收尾工作的代码

    gemm/                    # 专用于通用矩阵乘积计算的代码

    layout/                  # 矩阵、张量和其他数学对象在内存中的布局定义

    platform/                # 支持 CUDA 的标准库组件

    reduction/               # 带宽受限的归约内核，不适合 "gemm" 模型

    thread/                  # 可以在 CUDA 线程内执行的 SIMT 代码

    transform/               # 专用于布局、类型和域转换的代码

    *                        # 核心词汇类型、容器和基本数值操作

  cute/                      # CuTe 布局、布局代数、MMA/Copy 原子、分块 MMA/Copy

    algorithm/               # 核心操作的定义，如 copy、gemm 以及对 cute::tuple 的操作

    arch/                    # 用于拷贝和数学指令的简易 PTX 包装结构体

    atom/                    # 元信息，或链接自或构建自 arch/ 操作符

      mma_atom.hpp           # cute::Mma_Atom 和 cute::TiledMma

      copy_atom.hpp          # cute::Copy_Atom 和 cute::TiledCopy

      *sm*.hpp               # 拷贝和数学操作的特定架构元信息

    *                        # 核心库类型，如 Shape、Stride、Layout、Tensor 以及相关操作

CUTLASS SDK 示例

CUTLASS SDK 示例应用 CUTLASS 模板来实现基本计算。

工具

复制代码

tools/
  library/                   # CUTLASS 实例库 - 包含所有受支持的 CUTLASS 模板的实例化
    include/
      cutlass/
        library/

  profiler/                  # CUTLASS 性能分析器 - 用于在 CUTLASS 库中执行操作的命令行实用程序

  util/                      # CUTLASS 实用工具 - 包含许多用于管理设备内存中张量的辅助类、
    include/                 #                    GEMM 的参考实现、张量的随机初始化以及 I/O。
      cutlass/
        util/

测试

test/unit/ 目录包含使用 Google Test 实现的单元测试，演示了核心 API 组件的基本用法，并完成了 CUTLASS GEMM 计算的全面测试。

构建和运行单元测试的说明在快速入门指南中描述。

性能分析

tools/profiler/ 目录包含一个用于启动每个 GEMM 内核的命令行实用程序。构建方法如下：

复制代码

$ make cutlass_profiler -j16

构建所有 GEMM 和卷积内核（构建时间长）

默认情况下，仅为每种数据类型、数学指令和布局实例化一种分块大小。要实例化全部，请在从空的 build/ 目录运行 CMake 时设置以下环境变量。注意，这会导致数万个内核和很长的构建时间。这也可能导致二进制文件过大，并在某些平台上导致链接器构建库失败。因此，强烈建议仅生成内核子集，如下一节所示。

复制代码

$ cmake .. -DCUTLASS_NVCC_ARCHS=90a -DCUTLASS_LIBRARY_KERNELS=all
...
$ make cutlass_profiler -j16

构建 GEMM 和卷积内核的子集（减少构建时间）

要严格编译一个内核或一小部分内核，可以使用带有通配符的内核名称逗号分隔列表来减少内核集。以下示例展示了为 NVIDIA Ampere 和 Turing 架构构建一个或一部分内核：

构建张量核心 GEMM 内核子集

要编译一个针对 NVIDIA Ampere 和 Turing 架构、使用 FP32 累加和 FP16 输入的张量核心 GEMM 内核子集，使用以下 cmake 命令行：

复制代码

$ cmake .. -DCUTLASS_NVCC_ARCHS='75;80' -DCUTLASS_LIBRARY_KERNELS=cutlass_tensorop_s*gemm_f16_*_nt_align8
...
$ make cutlass_profiler -j16

分析张量核心 GEMM 内核子集的示例命令行如下：

复制代码

./tools/profiler/cutlass_profiler --kernels=cutlass_tensorop_s*gemm_f16_*_nt_align8 --m=3456 --n=4096 --k=4096

构建一个 CUDA 核心 GEMM 内核

要编译一个针对 NVIDIA Ampere 和 Turing 架构的 SGEMM 内核，使用以下 cmake 命令行：

复制代码

$ cmake .. -DCUTLASS_NVCC_ARCHS='75;80' -DCUTLASS_LIBRARY_KERNELS=cutlass_simt_sgemm_128x128_8x2_nn_align1
...
$ make cutlass_profiler -j16

分析单个 SGEMM CUDA 内核的示例命令行如下：

复制代码

$ ./tools/profiler/cutlass_profiler --kernels=sgemm --m=3456 --n=4096 --k=4096

构建张量核心卷积内核子集

要编译一个针对 NVIDIA Ampere 和 Turing 架构、使用 FP32 累加和 FP16 输入、实现前向传播（fprop）的张量核心卷积内核子集，使用以下 cmake 命令行：

复制代码

$ cmake .. -DCUTLASS_NVCC_ARCHS='75;80' -DCUTLASS_LIBRARY_KERNELS=cutlass_tensorop_s*fprop_optimized_f16
...
$ make cutlass_profiler -j16

分析张量核心卷积内核子集的示例命令行如下：

复制代码

$ ./tools/profiler/cutlass_profiler --kernels=cutlass_tensorop_s*fprop_optimized_f16 --n=8 --h=224 --w=224 --c=128 --k=128 --r=3 --s=3

构建一个卷积 CUDA 内核

要编译并运行一个针对 NVIDIA Ampere 和 Turing 架构、使用 F32 累加和 FP32 输入、实现前向传播（fprop）的 CUDA 核心卷积内核，使用以下 cmake 命令行：

复制代码

$ cmake .. -DCUTLASS_NVCC_ARCHS='75;80' -DCUTLASS_LIBRARY_KERNELS=cutlass_simt_sfprop_optimized_128x128_8x2_nhwc
...
$ make cutlass_profiler -j16

分析一个 CUDA 核心卷积内核的示例命令行：

复制代码

$ ./tools/profiler/cutlass_profiler --kernels=cutlass_simt_sfprop_optimized_128x128_8x2_nhwc --n=8 --h=224 --w=224 --c=128 --k=128 --r=3 --s=3

关于编译 CUTLASS 内核和 CUTLASS 性能分析器的更多细节

请访问以下链接获取关于选择性编译 CUTLASS 内核的更多 CMake 示例：
- GEMM CMake 示例
- 隐式 GEMM 卷积 CMake 示例
CUTLASS 性能分析器的进一步细节在此处描述。