cutile-rs（cuTile Rust）是 NVIDIA 出品的、面向 Rust 语言的安全 Tile 内核编程 DSL：它把 Rust 的内存安全与所有权规则扩展到 GPU 端，让你用纯 Rust 写出无数据竞争的 GPU 内核，并通过 CUDA Tile IR 进行 JIT 编译。本教程带你10 分钟完成环境搭建，跑通你的第一个Hello World Tile 内核，再动手实现一个向量加法（vector addition）GPU 内核，快速上手Rust GPU 开发。

为什么选择 cutile-rs？

传统 CUDA C++ 需要手动计算线程索引、做边界检查、保证访存合并，稍有疏忽就是越界或数据竞争。cutile-rs 用「Tile（数据块）」代替「线程」作为编程单位，核心优势如下：

💡 内核在首次调用时被 JIT 编译为 Tile IR 字节码 → cubin，之后同一变体复用缓存，无需手动管理 GPU 二进制。

项目由 6 个核心 crate 组成，日常开发主要面对用户层cutile：

cutile 编写与执行 Tile 内核的用户层入口 ├── cutile-macro 过程宏（#[cutile::module]、#[cutile::entry]） ├── cutile-compiler 将内核编译为可执行 GPU 二进制 ├── cuda-async Rust 异步 API 执行 CUDA 操作 └── cuda-core 地道的安全 CUDA API

一键安装：环境要求 3 分钟确认

开始前，先确认你的机器满足以下条件（README.md 中有完整说明）：

环境配置要点：将CUDA_TOOLKIT_PATH（或CUDA_HOME）指向你的 CUDA 安装目录，例如在.cargo/config.toml中写入：

[env] CUDA_TOOLKIT_PATH = { value = "/usr/local/cuda-13", relative = false }

未设置时，cutile 会自动搜索/usr/local/cuda-13.3、/usr/local/cuda等标准安装路径。

Hello World：跑通第一个 Tile 内核

clone 仓库后，一条命令即可验证安装：

git clone https://gitcode.com/gh_mirrors/cu/cutile-rs cd cutile-rs cargo run -p cutile-examples --example hello_world

成功时你会看到 GPU 打印：

Hello, I am tile <0, 0, 0> in a kernel with <1, 1, 1> tiles.

看看背后的源码（cutile-examples/examples/hello_world.rs），一个完整的 Tile 内核程序分两部分：

① 设备端（GPU 执行）——用#[cutile::module]标记模块、#[cutile::entry()]标记内核入口：

#[cutile::module] mod hello_world_module { use cutile::core::*; #[cutile::entry()] fn hello_world_kernel() { let pid0 = program_id(0); cuda_tile_print!("Hello, I am program <{}>!\n", pid0); } }

② 主机端（CPU 执行）——创建设备与 stream，设置启动网格并发起内核：

fn main() -> Result<(), Error> { let device = Device::new(0)?; // 连接 GPU let stream = device.new_stream()?; // 创建工作队列 let launcher = hello_world_kernel(); // 获取内核启动器 launcher.grid((1, 1, 1)).sync_on(&stream)?; // 启动 1 个 tile 程序 Ok(()) }

📐grid((2, 2, 1))表示启动 2×2×1 =4 个并发 tile 程序，每个程序通过program_id(axis)知道自己负责哪一块数据——这就是 Tile 编程与线程编程的核心心智模型转变。

向量加法内核：掌握 partition + load_like 核心模式

Hello World 跑通后，我们来写一个真正干活的GPU 向量加法内核。完整示例可参考 cutile-book/tutorials/02-vector-addition.md：

#[cutile::module] mod my_module { use cutile::core::*; #[cutile::entry()] fn add<const B: i32>( z: &mut Tensor<f32, { [B] }>, // 独占可变输出：一个 tile 子块 x: &Tensor<f32, { [-1] }>, // 只读输入：完整张量 y: &Tensor<f32, { [-1] }>, ) { let tx = x.load_like(z); // 按 z 的分区自动取出对应 tile let ty = y.load_like(z); z.store(tx + ty); // 相加并写回 } }

主机端只需 3 行核心逻辑：

let x = api::ones::<f32>(&[1024]); let y = api::ones::<f32>(&[1024]); let z = api::zeros::<f32>(&[1024]).partition([128]); // 关键：分区！ let (z, _x, _y) = kernel::add(z, x, y).sync()?; let result = z.unpartition().to_host_vec().sync()?; assert_eq!(result, vec![2.0_f32; 1024]); // ✅ 验证成功

3 个必须理解的关键概念

1. partition 分区：z是可变输出，必须在主机端调用.partition([128])切成 128 元素一块的子张量。1024 ÷ 128 =8 个 tile，cutile 自动推导出启动网格(8, 1, 1)，并保证每个 tile 写入互不重叠的内存区域——这正是安全性的来源。
2. load_like 按形加载：x.load_like(z)让输入x按z相同的形状与坐标取 tile，无需任何手动索引计算，这是逐元素运算的惯用写法。
3. Load → Compute → Store：几乎所有 Tile 内核都遵循这个三段式——从全局内存加载 tile、在寄存器上计算、把结果写回张量。

🧮 想进一步练习？把分区改成[8, 8]处理 32×32 矩阵，你会启动 4×4 = 16 个 tile，每个处理 64 个元素。类似的内核写法还可参考 cutile-examples/examples/saxpy.rs（SAXPY：y = a*x + y）。

内核是如何被编译执行的？

理解这条 JIT 管线，能帮你更快定位报错位置：

1. 编译期：#[cutile::module]宏把你的 Rust 函数捕获为 AST；
2. 首次启动：AST → Tile IR 字节码 → cubin（GPU 二进制）；
3. 缓存：同一变体在进程内复用已编译内核，跳过重复编译；
4. 执行：分区网格上的所有 tile 程序并发执行，.sync()阻塞到完成。

底层 IR 由纯 Rust 实现的 cutile-ir/ 构建与写出，编译逻辑位于 cutile-compiler/，如需深入可查阅 cutile-book/guide/jit-compilation.md。

常见问题速查清单

下一步学习路线 🚀

• 📘 官方教程：Hello World → 向量加法 → 矩阵乘法 → Flash Attention
• 📚 心智模型与张量概念：Useful Mental Models、Tensors and Tiles
• 🧪 异步执行（async/await 与 CUDA Graph）：cuda-async/README.md
• ⚡ 性能调优与基准测试：cutile-benchmarks/、性能指南
• 🔍 调试与 Profiling（Nsight Compute / cuda-gdb）：调试指南

总结：cutile-rs 用partition+load_like两个核心模式，把传统 CUDA 中繁琐易错的索引与边界管理交给编译器，让 Rust 开发者在 10 分钟内就能写出安全、高效的 Tile GPU 内核。从 Hello World 到向量加法，你已经掌握了 90% 的逐元素内核写法——接下来，去挑战矩阵乘法吧！