deepreinforce-ai/CUDA-L2

<hr> <div align="center"> <picture> <img src="assets/header.png" width="60%" alt="CUDA-L2: Surpassing cuBLAS Performance for Matrix Multiplication through Reinforcement Learning"> </picture> </div> <h1 align="center" style="line-height: 1.3;"> CUDA-L2: Surpassing cuBLAS Performance for Matrix Multiplication through Reinforcement Learning </h1> <!-- --> ## 🥳 Introduction **CUDA-L2** is a system that combines large language models (LLMs) and reinforcement learning (RL) to automatically optimize Half-precision General Matrix Multiply (HGEMM) CUDA kernels. CUDA-L2 systematically outperforms major matmul baselines to date, from the widely-used torch.matmul to state-of-the-art NVIDIA closed-source libraries (cuBLAS, cuBLASLt-heuristic, cuBLASLt-AutoTuning). <a href="https://arxiv.org/pdf/2512.02551">Paper</a> <div align="center"> <img src="assets/benchmark_comparison.png" width="90%" alt="Evaluation Results"> <br> <em>Speedup of CUDA-L2 over torch.matmul, cuBLAS, cuBLASLt-heuristic, and cuBLASLt-AutoTuning across 1000 (M,N,K) configurations on A100.</em> </div> <br> <div align="center"> <img src="assets/table.png" width="90%" alt="Evaluation Results"> <br> <em>Speedup comparison results across 1000 (M,N,K) configurations on A100.</em> </div> ## 🎉 What's New - **[Dec 2, 2025]** Released A100 optimized HGEMM kernels across 1,000 configurations. ## 🗒️ To-Do List - [ ] Release HGEMM with 32-bit accumulator (SM80_16x8x16_F16F16F16F32 and F32F16F16F32 officially) for A100. Current version only support 16-bit accumulator (SM80_16x8x16_F16F16F16F16). - [ ] Support denser matrix configurations (more configurations). - [ ] Extend to more GPUs (Ada Lovelace, Hopper, Blackwell). - [ ] Easy deployment for open-source LLMs. ## FAQ **Q: Do A100 kernels apply to other machines like RTX 3090 or H100?** A: Ideally, kernels trained on A100 should only be used on A100 if you are targeting speedup. They might have speedup on other machines, but it's not guaranteed. We will progressively release kernels trained on different machines. **Q: What if I need matrix dimensions (M, N, K) not found in your configurations?** A: 1. You can find the nearest neighbor configuration (larger than yours) and pad with zeros. 2. Feel free to post your dimensions on GitHub issues. We are happy to release kernels for your configuration. ## Installation & Setup ### 1\. Prerequisites * **Python**: Ensure you have a working Python environment. * **PyTorch**: This project requires PyTorch version **2.6.0** or higher. ### 2\. Clone CUTLASS This project depends on NVIDIA CUTLASS. You must clone specific tag `v4.2.1` into a directory named `cutlass`: ```bash git clone -b v4.2.1 https://github.com/NVIDIA/cutlass.git cutlass ``` > ⚠️ **Warning**: Please ensure you download the correct CUTLASS version (`v4.2.1`) and set the `CUTLASS_DIR` environment variable correctly. Incorrect CUTLASS setup may cause the project to fail silently or produce no results. ### 3\. Environment Variables Before building or running the project, you must configure the following environment variables: * `CUTLASS_DIR`: Points to the directory where you cloned CUTLASS. * `TORCH_CUDA_ARCH_LIST`: Specifies the target GPU architecture (e.g., "8.0" for NVIDIA Ampere / A100 / RTX 30 series). Run the following commands: ```bash export CUTLASS_DIR=/path/to/your/cutlass export TORCH_CUDA_ARCH_LIST="8.0" ``` ## Usage To run the evaluation, use the `eval_one_file.sh` script. Below is an example command for offline mode: ```bash ./eval_one_file.sh --mnk 64_4096_64 --warmup_seconds 5 --benchmark_seconds 10 --base_dir ./results --gpu_device_id 7 --mode offline ``` For server mode, you need to specify `--target_qps`: ```bash ./eval_one_file.sh --mnk 64_4096_64 --warmup_seconds 5 --benchmark_seconds 10 --base_dir ./results --gpu_device_id 7 --mode server --target_qps 100 ``` ### Arguments Reference | Argument | Description | | :--- | :--- | | `--mnk` | Specifies the problem size (e.g., `64_4096_64`). | | `--warmup_seconds` | Duration of warmup in seconds before timing. | | `--benchmark_seconds` | Duration of benchmarking in seconds. | | `--base_dir` | Directory to save the compile and output results. | | `--gpu_device_id` | The ID of the GPU to use (e.g., `7`). | | **`--mode`** | **Execution mode.** Options are:<br>• `offline`: Runs the evaluation in offline/batch processing mode.<br>• `server`: Runs the evaluation in server mode (simulating request-based scenarios). | | `--target_qps` | Target Queries Per Second (QPS) for server mode. Required if mode is `server`. | ## ✉️ Contact If you have any questions, please open a GitHub issue or reach out to us at **[e-mail]**.<hr> <div align="center"> <picture> <img src="assets/header.png" width="60%" alt="CUDA-L2: 通过强化学习实现超越cuBLAS的矩阵乘法性能"> </picture> </div> <h1 align="center" style="line-height: 1.3;"> CUDA-L2: 通过强化学习实现超越cuBLAS的矩阵乘法性能 </h1> <!-- --> ## 🥳 引言 **CUDA-L2** 是一款结合大语言模型（Large Language Model, LLM）与强化学习（Reinforcement Learning, RL）的系统，可自动优化半精度通用矩阵乘法（Half-precision General Matrix Multiply, HGEMM）的CUDA内核。截至目前，CUDA-L2在各项主流矩阵乘法基准测试中均取得系统性领先，涵盖广泛使用的`torch.matmul`，以及英伟达（NVIDIA）闭源的顶尖库（cuBLAS、cuBLASLt-heuristic、cuBLASLt-AutoTuning）。<a href="https://arxiv.org/pdf/2512.02551">论文链接</a> <div align="center"> <img src="assets/benchmark_comparison.png" width="90%" alt="评估结果"> <br> <em>在A100显卡的1000组(M,N,K)配置下，CUDA-L2相较于`torch.matmul`、cuBLAS、cuBLASLt-heuristic及cuBLASLt-AutoTuning的加速比。</em> </div> <br> <div align="center"> <img src="assets/table.png" width="90%" alt="评估结果"> <br> <em>在A100显卡的1000组(M,N,K)配置下的加速比对比结果。</em> </div> ## 🎉 新增内容 - **[2025年12月2日]** 发布针对A100显卡、覆盖1000组配置的优化HGEMM内核。 ## 🗒️ 待办事项 - [ ] 为A100发布支持32位累加器（官方支持SM80_16x8x16_F16F16F16F32与F32F16F16F32）的HGEMM内核。当前版本仅支持16位累加器（SM80_16x8x16_F16F16F16F16）。 - [ ] 支持更密集的矩阵配置（覆盖更多配置场景）。 - [ ] 扩展支持更多GPU型号（Ada Lovelace、Hopper、Blackwell）。 - [ ] 适配开源大语言模型的便捷部署。 ## 常见问题（FAQ） **Q: A100内核是否适用于RTX 3090或H100等其他设备？** A: 若追求最佳加速效果，在A100上训练的内核仅建议在A100显卡上使用。在其他设备上可能也能获得加速，但无法保证。我们将逐步发布针对不同设备训练的内核。 **Q: 若需要的矩阵维度(M,N,K)不在我们提供的配置中该怎么办？** A: 1. 你可以找到最接近的（大于你的配置）现有配置，并用零填充来适配。 2. 欢迎在GitHub Issues中提交你的维度需求，我们将很高兴为你的配置发布专属内核。 ## 安装与配置 ### 1. 前置依赖 * **Python**：确保你已配置可用的Python环境。 * **PyTorch**：本项目要求PyTorch版本为**2.6.0**及以上。 ### 2. 克隆CUTLASS仓库 本项目依赖英伟达（NVIDIA）CUTLASS库，你需要将指定标签`v4.2.1`克隆到名为`cutlass`的目录中： bash git clone -b v4.2.1 https://github.com/NVIDIA/cutlass.git cutlass > ⚠️ **警告**：请务必下载正确的CUTLASS版本（`v4.2.1`）并正确配置`CUTLASS_DIR`环境变量。CUTLASS配置错误可能导致项目静默失败或无输出结果。 ### 3. 环境变量配置 在编译或运行本项目前，你需要配置以下环境变量： * `CUTLASS_DIR`：指向你克隆的CUTLASS库所在目录。 * `TORCH_CUDA_ARCH_LIST`：指定目标GPU架构（例如，针对英伟达Ampere/A100/RTX 30系列，填写"8.0"）。 执行以下命令完成配置： bash export CUTLASS_DIR=/path/to/your/cutlass export TORCH_CUDA_ARCH_LIST="8.0" ## 使用方法 若要运行评估，可使用`eval_one_file.sh`脚本。以下为离线模式的示例命令： bash ./eval_one_file.sh --mnk 64_4096_64 --warmup_seconds 5 --benchmark_seconds 10 --base_dir ./results --gpu_device_id 7 --mode offline 若使用服务器模式，则需指定`--target_qps`参数： bash ./eval_one_file.sh --mnk 64_4096_64 --warmup_seconds 5 --benchmark_seconds 10 --base_dir ./results --gpu_device_id 7 --mode server --target_qps 100 ### 参数说明 | 参数 | 描述 | | :--- | :--- | | `--mnk` | 指定问题规模（例如`64_4096_64`）。 | | `--warmup_seconds` | 计时前的预热时长（单位：秒）。 | | `--benchmark_seconds` | 基准测试的持续时长（单位：秒）。 | | `--base_dir` | 保存编译与输出结果的目录。 | | `--gpu_device_id` | 所用GPU的ID（例如`7`）。 | | **`--mode`** | **执行模式**。可选值包括：<br>• `offline`：以离线/批处理模式运行评估。<br>• `server`：以服务器模式运行评估（模拟基于请求的场景）。 | | `--target_qps` | 服务器模式下的目标每秒查询数（QPS）。若模式为`server`则为必填项。 | ## ✉️ 联系方式 若有任何疑问，请提交GitHub Issue，或通过邮箱**[e-mail]**联系我们。