快速入门指南 - Quick Start Guide

Language: 简体中文 English

目录 (Table of Contents)

快速入门指南 - Quick Start Guide

环境要求

硬件要求

组件	最低要求	推荐配置
GPU	NVIDIA GPU，计算能力 7.0+	RTX 30 系列或更高
显存	4 GB	8 GB+
系统内存	8 GB	16 GB+
操作系统	Linux / Windows / macOS	Ubuntu 22.04 LTS

软件要求

依赖	最低版本	推荐版本
CUDA Toolkit	11.0	12.0+
CMake	3.18	3.25+
GCC	9.0	11.0+
Python	3.8+	3.10+

验证环境

$ nvcc --version
$ nvidia-smi
$ cmake --version
$ gcc --version

快速开始

1. 克隆仓库

$ git clone https://github.com/LessUp/mini-inference-engine.git
$ cd mini-inference-engine

2. 构建项目（推荐方式）

本项目使用 CMake Presets 简化构建流程：

# Debug 构建（包含测试）
$ cmake --preset default && cmake --build --preset default

# 运行测试
$ ctest --preset default

# Release 构建（性能测试）
$ cmake --preset release && cmake --build --preset release

3. 验证安装

# 运行 benchmark
$ ./build-release/benchmark

# 运行 MNIST 演示
$ ./build-release/mnist_demo

第一个程序

基础 GEMM 示例

#include "common.h"
#include "kernels.cuh"
#include <iostream>
#include <vector>

int main() {
    // 设置 GPU 设备
    CUDA_CHECK(cudaSetDevice(0));
    
    // 定义矩阵维度
    const int M = 1024, N = 1024, K = 1024;
    
    // 分配 GPU 内存
    DeviceMemory d_A(M * K * sizeof(float));
    DeviceMemory d_B(K * N * sizeof(float));
    DeviceMemory d_C(M * N * sizeof(float));
    
    // 创建并初始化主机数据
    std::vector<float> h_A(M * K), h_B(K * N);
    random_init(h_A.data(), h_A.size());
    random_init(h_B.data(), h_B.size());
    
    // 拷贝到 GPU
    d_A.copy_from_host(h_A.data(), M * K * sizeof(float));
    d_B.copy_from_host(h_B.data(), K * N * sizeof(float));
    
    // 执行优化 GEMM
    launch_optimized_gemm(d_A.get(), d_B.get(), d_C.get(), M, N, K);
    
    // 同步等待完成
    CUDA_CHECK(cudaDeviceSynchronize());
    
    // 获取结果
    std::vector<float> h_C(M * N);
    d_C.copy_to_host(h_C.data(), M * N * sizeof(float));
    
    std::cout << "✓ GEMM 完成！C[0] = " << h_C[0] << std::endl;
    
    return 0;
}

编译和运行

# 使用 CMake（推荐）
# 或者手动编译：
$ nvcc -o my_first_gemm my_first_gemm.cu \\
-I../include -L../build -lmini_inference \\
-lcudart -lcublas -std=c++17
$ ./my_first_gemm

验证正确性

#include "common.h"

// CPU 参考实现
std::vector<float> h_C_ref(M * N);
cpu_matmul(h_A.data(), h_B.data(), h_C_ref.data(), M, N, K);

// 比较误差
float max_error = compare_matrices(h_C.data(), h_C_ref.data(), M * N);
std::cout << "最大误差: " << max_error << std::endl;
// 通常应该 < 1e-4

故障排除

编译错误 “Unsupported gpu architecture”

解决方案：修改 CMakeLists.txt 中的 GPU 架构设置：

# 查看 GPU 架构
$ nvidia-smi --query-gpu=compute_cap --format=csv

# 设置对应架构
$ set(CMAKE_CUDA_ARCHITECTURES 86) # RTX 30 系列
$ set(CMAKE_CUDA_ARCHITECTURES 89) # RTX 40 系列

运行时错误 “CUDA out of memory”

解决方案：

减小矩阵大小或 batch size

使用内存池清理缓存：

MemoryPool::instance().clear_cache();

性能低于预期

检查清单：

GPU 电源状态为 P0：

nvidia-smi -q -d PERFORMANCE | grep "Performance State"

GPU 没有被其他程序占用
使用 Release 模式构建
矩阵大小是 2 的倍数（对齐）

下一步

恭喜！你已完成快速入门。接下来可以：

📖 阅读架构设计了解系统原理
⚡ 学习 GEMM 优化详解掌握优化技术
🔧 查看 API 参考了解完整接口
📊 阅读性能调优指南进行深度优化