cuTile Python

cuTile Python 是一种面向 NVIDIA GPU 的编程语言。官方文档可在 docs.nvidia.com 上找到，也可以从位于 docs 文件夹中的源代码构建。

示例

# 本示例使用 CuPy，可通过 `pip install cupy-cuda13x` 安装。
# 请确保已安装 CUDA 工具包 13.1 或更高版本：https://developer.nvidia.com/cuda-downloads

import cuda.tile as ct
import cupy
import numpy as np

TILE_SIZE = 16

# cuTile 内核，用于对两个密集向量进行加法运算。它在 GPU 上并行执行。
@ct.kernel
def vector_add_kernel(a, b, result):
    block_id = ct.bid(0)
    a_tile = ct.load(a, index=(block_id,), shape=(TILE_SIZE,))
    b_tile = ct.load(b, index=(block_id,), shape=(TILE_SIZE,))
    result_tile = a_tile + b_tile
    ct.store(result, index=(block_id,), tile=result_tile)

# 生成输入数组
rng = cupy.random.default_rng()
a = rng.random(128)
b = rng.random(128)
expected = cupy.asnumpy(a) + cupy.asnumpy(b)

# 分配输出数组并启动内核
result = cupy.zeros_like(a)
grid = (ct.cdiv(a.shape[0], TILE_SIZE), 1, 1)
ct.launch(cupy.cuda.get_current_stream(), grid, vector_add_kernel, (a, b, result))

# 验证结果
result_np = cupy.asnumpy(result)
np.testing.assert_array_almost_equal(result_np, expected)

更多示例可在 Samples 和 TileGym 中找到。

系统要求

cuTile Python 基于 Tile IR 生成内核，运行时需要 NVIDIA 驱动程序 r580 或更高版本。此外，tileiras 编译器（版本 13.2）仅支持 Blackwell GPU 以及 Ampere/Ada 架构的 GPU。Hopper 架构的 GPU 将在后续版本中得到支持。完整的依赖列表请参阅 先决条件。

通过 PyPI 安装

cuTile Python 已发布在 PyPI 上，软件包名为 cuda-tile，可使用 pip 安装：

pip install cuda-tile[tileiras]

可选的 tileiras 依赖会将 tileiras 编译器直接安装到您的 Python 环境中。

如果您不希望在 Python 环境中包含 tileiras，可以运行以下命令：

pip install cuda-tile

并单独安装 CUDA 工具包 13.1+。

在基于 Debian 的系统上，若希望避免安装完整的 CUDA 工具包，可使用 apt-get install cuda-tileiras-13.2 cuda-compiler-13.2 替代 apt-get install cuda-toolkit-13.2。

从源代码构建

cuTile 主要以 Python 编写，但也包含一个需要编译的 C++ 扩展模块。您需要：

• 具备 C++17 支持的编译器，例如 GNU C++ 或 MSVC；
• CMake 3.18 或更高版本；
• Linux 上的 GNU Make 或 Windows 上的 msbuild；
• Python 3.10 或更高版本，并带有开发头文件（推荐使用 venv 模块，但非强制）；
• CUDA 工具包 13.1+。

在 Ubuntu 系统上，前四个依赖项可以通过 APT 安装：

sudo apt-get update && sudo apt-get install build-essential cmake python3-dev python3-venv

CMakeLists.txt 脚本还会自动从 GitHub 下载 DLPack 依赖。如果您希望禁用此行为并提供自己的 DLPack 副本，请将 CUDA_TILE_CMAKE_DLPACK_PATH 环境变量设置为本地 DLPack 源码树的路径。

除非您已经使用 Python 虚拟环境，否则建议创建一个虚拟环境，以避免全局安装 cuTile：

python3 -m venv env
source env/bin/activate

一旦构建依赖项就绪，构建 cuTile 的最简单方式是在源代码根目录下以可编辑模式安装：

pip install -e .

这将会创建 build 目录，并调用基于 CMake 的构建流程。在可编辑模式下，编译后的扩展模块会被放置在 build 目录中，随后会在源代码目录中为其创建一个符号链接。这样可以确保只需执行一次上述 pip install -e . 命令，而在对 C++ 代码进行修改后，只需运行 make -C build 即可重新编译扩展模块，速度更快。这一逻辑定义在 setup.py 中。

实验性功能（可选）

cuTile 现在提供了一个实验性软件包，其中包含仍在积极开发中的 API。这些 API 不属于稳定的 cuda.tile API，可能会发生变化。

要在从源代码检出的工作环境中启用实验性功能，可以从仓库根目录安装实验性软件包：

pip install ./experimental

您也可以直接从 GitHub 仓库的子目录安装：

pip install \
  "git+https://github.com/NVIDIA/cutile-python.git#egg=cuda-tile-experimental&subdirectory=experimental"

例如，这将使实验性命名空间可用于自动调优器：

from cuda.tile_experimental import autotune_launch, clear_autotune_cache

运行测试

cuTile 使用 pytest 框架进行测试。测试有额外的依赖项，例如 PyTorch，可通过以下命令安装：

pip install -r test/requirements.txt

测试文件位于 test/ 目录中。要运行特定的测试文件，例如 test_copy.py，可以使用以下命令：

pytest test/test_copy.py

版权与许可信息

版权所有 © 2025 NVIDIA CORPORATION & AFFILIATES。保留所有权利。

cuTile-Python 采用 Apache 2.0 许可证授权。完整许可证文本请参阅 LICENSES 文件夹。

cuTile-Python 快速上手指南

cuTile-Python 是专为 NVIDIA GPU 设计的编程语言，基于 Tile IR 生成高性能内核。本指南将帮助您快速配置环境并运行第一个示例。

环境准备

在开始之前，请确保您的系统满足以下硬件和软件要求：

• GPU 架构支持：
  • 目前支持 Blackwell 和 Ampere/Ada 架构的 GPU。
  • Hopper 架构将在后续版本中支持。
• 驱动程序：必须安装 NVIDIA Driver r580 或更高版本。
• CUDA Toolkit：需要 CUDA Toolkit 13.1+。
  • 下载地址：NVIDIA CUDA Downloads
  • Debian/Ubuntu 用户提示：若不想安装完整 toolkit，可单独安装编译器组件：apt-get install cuda-tileiras-13.2 cuda-compiler-13.2。
• Python 版本：Python 3.10 或更高版本。
• 构建依赖（仅源码编译时需要）：
  • C++17 编译器 (GCC 或 MSVC)
  • CMake 3.18+
  • Python 开发头文件 (python3-dev)

安装步骤

推荐使用 pip 从 PyPI 安装。您可以根据需求选择是否将编译器包含在 Python 环境中。

方式一：标准安装（推荐）

此方式会将 tileiras 编译器直接安装到当前 Python 环境中，配置最简单。

pip install cuda-tile[tileiras]

方式二：最小化安装

如果您已在全局路径配置了 CUDA Toolkit，或希望保持 Python 环境纯净，可选择此方式。

pip install cuda-tile

注意：使用此方式前，请确保系统已正确安装 CUDA Toolkit 13.1+ 且环境变量已配置。

国内加速建议

在中国大陆地区，建议使用国内镜像源加速安装：

pip install cuda-tile[tileiras] -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是一个最简单的示例，演示如何使用 cuTile 编写一个并行向量加法内核。

前置依赖：本示例依赖 cupy，请先安装：

pip install cupy-cuda13x

代码示例 (example.py)：

# This examples uses CuPy which can be installed via `pip install cupy-cuda13x`
# Make sure cuda toolkit 13.1+ is installed: https://developer.nvidia.com/cuda-downloads

import cuda.tile as ct
import cupy
import numpy as np

TILE_SIZE = 16

# cuTile kernel for adding two dense vectors. It runs in parallel on the GPU.
@ct.kernel
def vector_add_kernel(a, b, result):
    block_id = ct.bid(0)
    a_tile = ct.load(a, index=(block_id,), shape=(TILE_SIZE,))
    b_tile = ct.load(b, index=(block_id,), shape=(TILE_SIZE,))
    result_tile = a_tile + b_tile
    ct.store(result, index=(block_id,), tile=result_tile)

# Generate input arrays
rng = cupy.random.default_rng()
a = rng.random(128)
b = rng.random(128)
expected = cupy.asnumpy(a) + cupy.asnumpy(b)

# Allocate an output array and launch the kernel
result = cupy.zeros_like(a)
grid = (ct.cdiv(a.shape[0], TILE_SIZE), 1, 1)
ct.launch(cupy.cuda.get_current_stream(), grid, vector_add_kernel, (a, b, result))

# Verify the results
result_np = cupy.asnumpy(result)
np.testing.assert_array_almost_equal(result_np, expected)

print("Vector addition completed successfully!")

运行测试： 确保 GPU 驱动和 CUDA 环境配置无误后，直接运行脚本：

python example.py

如果未抛出异常且输出成功信息，则表示环境配置正确，cuTile 内核已成功执行。