quick-start.md
1 # 快速开始指南 2 3 在 10-15 分钟内搭建开发环境并运行首个基准测试。 4 5 ## 📋 需求概览 6 7 ### 硬件要求 8 9 | 模块 | 最低 GPU | 推荐 GPU | 额外说明 | 10 |------|---------|---------|----------| 11 | **01 TVM** | SM70+ (V100) | A100 | 需要 CUDA 12.x | 12 | **02 ORT** | SM70+ (V100) | A100 | 需要 CUDA 12.x | 13 | **03 CUTLASS** | SM80 (A100) | H100 | Hopper 特性需 SM90 | 14 | **04 cuTile** | 无 | — | 仅 CPU 的概念模块 | 15 16 ### 软件要求 17 18 - **Python**: 3.10 或更高版本 19 - **CUDA Toolkit**: 12.x（模块 03 需要 12.2+） 20 - **CMake**: 3.18 或更高版本 21 - **GCC**: 9+ 或 Clang 10+ 22 23 ## 🐳 方式一：Docker（推荐） 24 25 无需手动安装依赖，最快速的入门方式。 26 27 ### CUDA 12.x 环境 28 29 ```bash 30 # 构建 Docker 镜像 31 docker build -f docker/Dockerfile.cuda12 -t ai-opt:cuda12 . 32 33 # 使用 GPU 支持运行并挂载当前目录 34 docker run --gpus all -it -v $(pwd):/workspace ai-opt:cuda12 35 36 # 验证 TVM 模块正常工作 37 python 01_TVM_End2End_Optimization/1_import_and_baseline.py 38 ``` 39 40 ### 可用 Docker 镜像 41 42 | 镜像 | CUDA 版本 | 支持的模块 | 43 |------|----------|-----------| 44 | `ai-opt:cuda12` | 12.2 | TVM, ORT, CUTLASS | 45 | `ai-opt:cuda13` | 12.4 (cuTile 占位) | 全部 (cuTile 模块) | 46 47 ## 💻 方式二：本地安装 48 49 ### 步骤 1：克隆仓库 50 51 ```bash 52 git clone https://github.com/LessUp/ai-system-optimization-series.git 53 cd ai-system-optimization-series 54 ``` 55 56 ### 步骤 2：创建虚拟环境 57 58 ```bash 59 python -m venv venv 60 source venv/bin/activate # Linux/macOS 61 # venv\Scripts\activate # Windows 62 ``` 63 64 ### 步骤 3：安装开发依赖 65 66 ```bash 67 pip install -r requirements-dev.txt 68 ``` 69 70 ### 步骤 4：安装模块特定依赖 71 72 ```bash 73 # TVM 模块 74 pip install -r 01_TVM_End2End_Optimization/requirements.txt 75 76 # ORT 模块 77 pip install -r 02_ORT_Custom_CUDA_Op/requirements.txt 78 79 # cuTile 模块 80 pip install -r 04_CuTile_NextGen_CUDA/requirements.txt 81 ``` 82 83 ### 步骤 5：构建 C++/CUDA 组件 84 85 #### ONNX Runtime 自定义算子 86 87 ```bash 88 cd 02_ORT_Custom_CUDA_Op 89 mkdir -p build && cd build 90 cmake .. -DONNXRUNTIME_ROOT=/path/to/onnxruntime 91 make -j$(nproc) 92 cd ../.. 93 ``` 94 95 #### CUTLASS GEMM 96 97 ```bash 98 cd 03_CUTLASS_Hopper_GEMM 99 mkdir -p build && cd build 100 cmake .. -DCUTLASS_PATH=/path/to/cutlass 101 make -j$(nproc) 102 cd ../.. 103 ``` 104 105 ## 🚀 运行示例 106 107 ### 模块 01：TVM 端到端优化 108 109 ```bash 110 # 基线对比 111 python 01_TVM_End2End_Optimization/1_import_and_baseline.py 112 113 # 自动调度器调优（快速测试，100 次试验） 114 python 01_TVM_End2End_Optimization/2_auto_scheduler_tuning.py --num_trials 100 115 116 # TensorIR 手动调度 117 python 01_TVM_End2End_Optimization/3_tensorir_manual_schedule.py --target cuda --size 1024 118 ``` 119 120 ### 模块 02：ORT 自定义 CUDA 算子 121 122 ```bash 123 # 运行全部 ORT 测试 124 python -m pytest 02_ORT_Custom_CUDA_Op/tests/ -v 125 ``` 126 127 ### 模块 03：CUTLASS Hopper GEMM 128 129 ```bash 130 cd 03_CUTLASS_Hopper_GEMM/build 131 ./hopper_gemm_benchmark 132 ./test_gemm_correctness 133 ``` 134 135 ### 模块 04：cuTile 下一代 CUDA 136 137 ```bash 138 # 运行 tile GEMM 示例 139 python 04_CuTile_NextGen_CUDA/tile_gemm.py 140 141 # 运行 Triton 对比 142 python 04_CuTile_NextGen_CUDA/comparison_triton.py 143 ``` 144 145 ## 🧪 测试 146 147 ### 运行全部测试 148 149 ```bash 150 # Linux/macOS 151 bash scripts/run_tests.sh 152 153 # Windows 154 powershell scripts/run_tests.ps1 155 156 # 直接使用 pytest 157 pytest -v 158 ``` 159 160 ### 使用硬件特定标记运行 161 162 ```bash 163 # 仅 CUDA 测试 164 pytest -m requires_cuda -v 165 166 # 排除硬件依赖测试 167 pytest -m "not requires_cuda and not requires_tvm and not requires_ort" -v 168 169 # 跳过慢速测试 170 pytest -m "not slow" -v 171 ``` 172 173 ## 📊 运行基准测试 174 175 ### 运行全部基准测试 176 177 ```bash 178 # Linux/macOS 179 bash scripts/run_all_benchmarks.sh 180 181 # Windows 182 powershell scripts/run_all_benchmarks.ps1 183 ``` 184 185 结果将以 Markdown 和 JSON 格式保存到 `reports/` 目录。 186 187 ## 🔧 快速问题排查 188 189 | 问题 | 解决方案 | 190 |------|---------| 191 | TVM 安装失败 | `pip install apache-tvm` 或从源码构建 | 192 | 找不到 CUTLASS | 克隆到 `/opt/cutlass` 或设置 `CUTLASS_PATH` | 193 | CUDA 版本不匹配 | 使用 `nvcc --version` 和 `nvidia-smi` 检查 | 194 | 测试大部分被跳过 | 正常，如果依赖不可用；只关注 FAILED | 195 | 找不到 ORT 自定义算子 | 构建 C++ 组件（见步骤 5） | 196 | 权限被拒绝（Linux） | `chmod +x scripts/*.sh` | 197 198 ## 📖 后续步骤 199 200 1. **理解架构** — 阅读 [architecture.md](./architecture) 了解模块如何交互 201 2. **跟随学习路线** — 查看 [learning-path.md](./learning-path) 获取结构化学习计划 202 3. **探索 API** — 查看 [api-reference.md](./api-reference) 获取详细函数文档 203 204 ## 💡 专业提示 205 206 1. **如果不确定依赖**，从 Docker 开始 207 2. **任何 Python 脚本使用 `--help`** 查看命令行选项 208 3. **查看 `reports/` 目录中的日志** 获取详细基准输出 209 4. **遇到问题时开启讨论** — 在 GitHub 上开 issue 210 211 --- 212 213 *详细安装说明请参阅 [前置要求](./prerequisites)。*