Integration Examples

本文档展示如何在你的项目中集成和使用 CUDA Kernel Academy 的各个模块。

使用 tensorcraft-core 算子库

方式一：作为子目录

# 你的项目 CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(my_cuda_project LANGUAGES CXX CUDA)

# 添加 tensorcraft-core 作为子目录
add_subdirectory(path/to/02-tensorcraft-core tensorcraft)

# 链接到你的目标
add_executable(my_app main.cu)
target_link_libraries(my_app PRIVATE tensorcraft)

方式二：使用 FetchContent

include(FetchContent)

FetchContent_Declare(
    tensorcraft
    GIT_REPOSITORY https://github.com/LessUp/cuda-kernel-academy.git
    GIT_TAG main
    SOURCE_SUBDIR 02-tensorcraft-core
)

FetchContent_MakeAvailable(tensorcraft)

target_link_libraries(my_app PRIVATE tensorcraft)

方式三：Header-only 直接包含

由于 tensorcraft-core 是 header-only 库，你也可以直接包含头文件：

target_include_directories(my_app PRIVATE 
    path/to/02-tensorcraft-core/include
)

CMake 集成方式

完整的 CMakeLists.txt 示例

cmake_minimum_required(VERSION 3.20)
project(my_cuda_project LANGUAGES CXX CUDA)

# 设置 C++ 和 CUDA 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CUDA_STANDARD 17)
set(CMAKE_CUDA_STANDARD_REQUIRED ON)

# 设置 CUDA 架构
if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
    set(CMAKE_CUDA_ARCHITECTURES 70 75 80 86 89 90)
endif()

# 添加 tensorcraft-core
set(TENSORCRAFT_DIR "${CMAKE_SOURCE_DIR}/../cuda-kernel-academy/02-tensorcraft-core")
add_subdirectory(${TENSORCRAFT_DIR} tensorcraft EXCLUDE_FROM_ALL)

# 你的可执行文件
add_executable(my_app 
    src/main.cu
    src/model.cu
)

target_link_libraries(my_app PRIVATE tensorcraft)

# 可选：启用优化
target_compile_options(my_app PRIVATE 
    $<$<COMPILE_LANGUAGE:CUDA>:
        -O3
        --use_fast_math
        -Xptxas=-v
    >
)

GEMM 调用示例

基本 GEMM 调用

#include <tensorcraft/kernels/gemm.hpp>
#include <tensorcraft/core/cuda_check.hpp>

int main() {
    // 矩阵维度
    const int M = 1024, N = 1024, K = 1024;

    // 分配设备内存
    float *d_A, *d_B, *d_C;
    TC_CUDA_CHECK(cudaMalloc(&d_A, M * K * sizeof(float)));
    TC_CUDA_CHECK(cudaMalloc(&d_B, K * N * sizeof(float)));
    TC_CUDA_CHECK(cudaMalloc(&d_C, M * N * sizeof(float)));

    // 初始化数据...

    // 调用 GEMM
    tensorcraft::kernels::launch_gemm(
        d_A, d_B, d_C,
        M, N, K,
        1.0f,  // alpha
        0.0f,  // beta
        tensorcraft::kernels::GemmVersion::TILED  // 选择优化版本
    );

    TC_CUDA_CHECK(cudaDeviceSynchronize());

    // 清理
    cudaFree(d_A);
    cudaFree(d_B);
    cudaFree(d_C);

    return 0;
}

选择不同的 GEMM 版本

using namespace tensorcraft::kernels;

// Naive 版本 - 用于学习和验证
launch_gemm(A, B, C, M, N, K, 1.0f, 0.0f, GemmVersion::NAIVE);

// Tiled 版本 - 使用 shared memory
launch_gemm(A, B, C, M, N, K, 1.0f, 0.0f, GemmVersion::TILED);

// Double Buffer 版本 - 隐藏内存延迟
launch_gemm(A, B, C, M, N, K, 1.0f, 0.0f, GemmVersion::DOUBLE_BUFFER);

// Tensor Core 版本 - 最高性能
launch_gemm(A, B, C, M, N, K, 1.0f, 0.0f, GemmVersion::TENSOR_CORE);

批量 GEMM

#include <tensorcraft/kernels/gemm.hpp>

// 批量矩阵乘法
const int batch_size = 32;
const int M = 256, N = 256, K = 256;

float **d_A_array, **d_B_array, **d_C_array;
// ... 分配和初始化 ...

tensorcraft::kernels::launch_batched_gemm(
    d_A_array, d_B_array, d_C_array,
    M, N, K,
    batch_size,
    1.0f, 0.0f
);

Attention 调用示例

Flash Attention

#include <tensorcraft/kernels/attention.hpp>

void run_attention() {
    const int batch = 4;
    const int seq_len = 512;
    const int num_heads = 8;
    const int head_dim = 64;

    // Q, K, V 张量 (已在 GPU 上)
    float *d_Q, *d_K, *d_V, *d_O;
    // ... 分配内存 ...

    tensorcraft::kernels::launch_flash_attention(
        d_Q, d_K, d_V, d_O,
        batch, seq_len, num_heads, head_dim,
        1.0f / sqrtf(head_dim)  // scale
    );
}

Multi-Head Attention

#include <tensorcraft/kernels/attention.hpp>

tensorcraft::kernels::MultiHeadAttentionConfig config{
    .batch_size = 4,
    .seq_len = 512,
    .num_heads = 8,
    .head_dim = 64,
    .dropout = 0.1f,
    .causal = true  // 因果注意力
};

tensorcraft::kernels::launch_multi_head_attention(
    d_Q, d_K, d_V, d_O,
    config
);

从 04-inference-engine 学习集成模式

04-inference-engine 展示了如何将 tensorcraft-core 集成到完整的推理框架中。

关键集成点

1. CMakeLists.txt 依赖配置

# 04-inference-engine/CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(mini_inference LANGUAGES CXX CUDA)

# 添加 tensorcraft-core 依赖
set(TENSORCRAFT_ROOT "${CMAKE_SOURCE_DIR}/../02-tensorcraft-core")
add_subdirectory(${TENSORCRAFT_ROOT} tensorcraft)

# 主库
add_library(mini_inference STATIC
    src/inference_engine.cpp
    src/tensor.cu
    # 注意：不再需要 src/naive_matmul.cu 等重复文件
)

target_link_libraries(mini_inference PUBLIC tensorcraft)
target_include_directories(mini_inference PUBLIC include)

2. 代码中使用 tensorcraft

// 04-inference-engine/src/inference_engine.cpp
#include "inference_engine.h"
#include <tensorcraft/kernels/gemm.hpp>
#include <tensorcraft/kernels/elementwise.hpp>

void InferenceEngine::linear_layer(
    const float* input, 
    const float* weight,
    float* output,
    int M, int N, int K
) {
    // 使用 tensorcraft 的 GEMM 而不是本地实现
    tensorcraft::kernels::launch_gemm(
        input, weight, output,
        M, N, K,
        1.0f, 0.0f,
        tensorcraft::kernels::GemmVersion::TILED
    );
}

void InferenceEngine::relu_activation(float* data, int size) {
    tensorcraft::kernels::launch_relu(data, size);
}

3. 移除重复代码

集成后，可以删除以下重复文件：

src/naive_matmul.cu → 使用 tensorcraft::kernels::GemmVersion::NAIVE
src/tiled_gemm.cu → 使用 tensorcraft::kernels::GemmVersion::TILED
src/double_buffer_gemm.cu → 使用 tensorcraft::kernels::GemmVersion::DOUBLE_BUFFER

最佳实践

1. 错误检查

始终使用 tensorcraft 提供的错误检查宏：

#include <tensorcraft/core/cuda_check.hpp>

// 检查 CUDA API 调用
TC_CUDA_CHECK(cudaMalloc(&ptr, size));

// 检查最后一个 CUDA 错误
TC_CUDA_CHECK_LAST();

// 同步并检查
TC_CUDA_SYNC_CHECK();

2. 性能调优

// 根据矩阵大小选择最优版本
GemmVersion select_gemm_version(int M, int N, int K) {
    if (M < 128 || N < 128 || K < 128) {
        return GemmVersion::NAIVE;  // 小矩阵
    } else if (M >= 1024 && N >= 1024) {
        return GemmVersion::TENSOR_CORE;  // 大矩阵用 Tensor Core
    } else {
        return GemmVersion::TILED;  // 中等大小
    }
}

3. 内存管理

结合 tensorcraft 的内存工具：

#include <tensorcraft/memory/memory_pool.hpp>

tensorcraft::memory::MemoryPool pool(1024 * 1024 * 100);  // 100MB

auto ptr = pool.allocate<float>(M * N);
// 使用 ptr...
pool.deallocate(ptr);

常见问题

Q: 如何选择 GEMM 版本？

场景	推荐版本
学习/调试	NAIVE
通用场景	TILED
大矩阵	TENSOR_CORE
内存受限	DOUBLE_BUFFER

Q: 编译时找不到头文件？

确保 include 路径正确：

target_include_directories(my_app PRIVATE 
    ${TENSORCRAFT_ROOT}/include
)

Q: 运行时 CUDA 错误？

检查 GPU 架构是否匹配
使用 TC_CUDA_CHECK 定位错误
确保内存已正确分配

集成示例