Skip to content

Commit bce37b4

Browse files
LessUpLessUp
committed
feat: migrate docs to VitePress with CUDA Blue theme
- Migrate from Jekyll to VitePress 1.5.0 - Add CUDA Blue color scheme with dark mode support - Add Mermaid diagram and llms.txt plugin support - Rewrite README with interview-focused TL;DR section - Add new documentation: - Learning path (4-week study plan) - FAQ (20+ questions) - Industry comparison (vs cuBLAS, CUTLASS, vLLM) - Memory hierarchy deep dive - Performance analysis guide - Update CI/CD workflow for VitePress deployment - Add interactive performance chart component BREAKING CHANGE: Jekyll-based docs replaced with VitePress
1 parent 95998ce commit bce37b4

25 files changed

Lines changed: 5071 additions & 140 deletions

‎.github/workflows/pages.yml‎

Lines changed: 20 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,15 @@
11
# ═══════════════════════════════════════════════════════════════════════════════
2-
# Mini-Inference Engine - GitHub Pages Deployment
2+
# Mini-Inference Engine - GitHub Pages Deployment (VitePress)
33
# ═══════════════════════════════════════════════════════════════════════════════
44

5-
name: Deploy GitHub Pages
5+
name: Deploy Docs
66

77
on:
88
push:
99
branches: [master, main]
1010
paths:
11-
- 'index.md'
12-
- '_config.yml'
13-
- 'Gemfile'
1411
- 'docs/**'
15-
- 'assets/**'
16-
12+
- '.github/workflows/pages.yml'
1713
workflow_dispatch:
1814

1915
permissions:
@@ -25,47 +21,42 @@ concurrency:
2521
group: pages-${{ github.ref }}
2622
cancel-in-progress: true
2723

28-
env:
29-
BUNDLE_PATH: vendor/bundle
30-
3124
jobs:
3225
build:
33-
name: Build Site
26+
name: Build VitePress Site
3427
runs-on: ubuntu-latest
35-
28+
3629
steps:
3730
- name: Checkout Repository
3831
uses: actions/checkout@v4
3932
with:
4033
fetch-depth: 0
41-
42-
- name: Setup Ruby
43-
uses: ruby/setup-ruby@v1
34+
35+
- name: Setup Node.js
36+
uses: actions/setup-node@v4
4437
with:
45-
ruby-version: '3.3'
46-
bundler-cache: false
38+
node-version: 20
39+
cache: 'npm'
40+
cache-dependency-path: docs/package-lock.json
4741

4842
- name: Setup GitHub Pages
4943
id: pages
5044
uses: actions/configure-pages@v5
5145

5246
- name: Install Dependencies
53-
run: |
54-
bundle config set --local path '${{ env.BUNDLE_PATH }}'
55-
bundle install --jobs 4 --retry 3
47+
working-directory: docs
48+
run: npm ci
5649

57-
- name: Build Jekyll Site
58-
run: |
59-
bundle exec jekyll build \
60-
--baseurl "${{ steps.pages.outputs.base_path }}" \
61-
--destination ./_site
50+
- name: Build VitePress
51+
working-directory: docs
52+
run: npm run build
6253
env:
63-
JEKYLL_ENV: production
64-
54+
VITEPRESS_BASE: ${{ steps.pages.outputs.base_path }}
55+
6556
- name: Upload Artifact
6657
uses: actions/upload-pages-artifact@v3
6758
with:
68-
path: ./_site
59+
path: docs/.vitepress/dist
6960

7061
deploy:
7162
name: Deploy to GitHub Pages
@@ -74,7 +65,7 @@ jobs:
7465
url: ${{ steps.deployment.outputs.page_url }}
7566
runs-on: ubuntu-latest
7667
needs: build
77-
68+
7869
steps:
7970
- name: Deploy
8071
id: deployment

‎README.md‎

Lines changed: 124 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,14 @@
55
<h1 align="center">Mini-Inference Engine</h1>
66

77
<p align="center">
8-
<b>CUDA GEMM optimization tutorial and mini inference engine</b><br>
9-
<i>From naive matrix multiplication to ~85% cuBLAS-class performance on the reference benchmark</i>
8+
<b>CUDA GEMM 优化教程与迷你推理引擎</b><br>
9+
<i>从朴素矩阵乘法到 ~85% cuBLAS 性能的 7 级渐进式优化路线</i>
1010
</p>
1111

1212
<p align="center">
13-
<a href="README.md">English</a> ·
1413
<a href="README.zh-CN.md">简体中文</a> ·
15-
<a href="https://lessup.github.io/mini-inference-engine/">Online Docs</a> ·
16-
<a href="docs/en/QUICK_START.md">Quick Start</a>
14+
<a href="README.md">English</a> ·
15+
<a href="https://lessup.github.io/mini-inference-engine/">在线文档</a>
1716
</p>
1817

1918
<p align="center">
@@ -23,73 +22,159 @@
2322
<a href="https://github.com/LessUp/mini-inference-engine/actions/workflows/pages.yml">
2423
<img src="https://github.com/LessUp/mini-inference-engine/actions/workflows/pages.yml/badge.svg" alt="Docs">
2524
</a>
26-
<a href="LICENSE">
27-
<img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT">
28-
</a>
29-
<img src="https://img.shields.io/badge/CUDA-11.0+-76B900?logo=nvidia&logoColor=white" alt="CUDA">
25+
<img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
26+
<img src="https://img.shields.io/badge/CUDA-12.x-76B900?logo=nvidia&logoColor=white" alt="CUDA">
3027
<img src="https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white" alt="C++17">
28+
<img src="https://img.shields.io/badge/Docs-VitePress-16b1ff" alt="VitePress">
3129
</p>
3230

3331
---
3432

35-
## What this repository contains
33+
## TL;DR — 面试官速览
34+
35+
| 技术领域 | 本项目覆盖 | 代码证据 |
36+
|----------|-----------|----------|
37+
| **CUDA 编程** | 7 级 GEMM 优化（Naive → Vectorized） | `src/*_gemm.cu` |
38+
| **内存优化** | 共享内存分块、双缓冲、寄存器分块 | `tiled_gemm.cu`, `double_buffer_gemm.cu` |
39+
| **性能调优** | AutoTuner 自动调参、Profiler 性能分析 | `include/autotuner.h`, `include/profiler.h` |
40+
| **系统设计** | 四层架构、RAII 资源管理、内存池 | `include/memory_pool.h`, `include/stream_manager.h` |
41+
| **工程实践** | CMake、GoogleTest、CI/CD、OpenSpec | `CMakePresets.json`, `.github/workflows/` |
3642

37-
Mini-Inference Engine is a compact CUDA/C++17 project for learning high-performance GEMM optimization in a realistic inference-engine setting. It keeps the scope intentionally small: matrix multiplication kernels, runtime utilities, benchmarks, tests, and bilingual documentation all live in one traceable codebase.
43+
---
3844

39-
**Core value:**
45+
## 性能一览
4046

41-
| Area | What to inspect |
42-
| --- | --- |
43-
| GEMM kernels | `src/naive_matmul.cu` through `src/vectorized_gemm.cu` show the optimization path. |
44-
| Runtime components | `include/tensor.h`, `include/inference_engine.h`, `include/memory_pool.h`, and `include/stream_manager.h`. |
45-
| Benchmarks | `benchmarks/benchmark.cpp`, `benchmarks/detailed_benchmark.cu`, and `benchmarks/mnist_demo.cpp`. |
46-
| Specs | `openspec/specs/` defines requirements, architecture, API, data, and testing expectations. |
47-
| Documentation | `docs/en/` and `docs/zh/` provide the tutorial, architecture, API, and tuning guides. |
47+
```
48+
Performance vs cuBLAS (RTX 3080, 1024×1024)
49+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
50+
L1 Naive ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 10%
51+
L2 Tiled ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 20%
52+
L3 Coalesced ██████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 25%
53+
L4 Double Buf ████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 40%
54+
L5 Register ████████████████████████████████████████████░ 85%
55+
L6 Fused ██████████████████████████████████████████░░░ 80%
56+
L7 Vectorized █████████████████████████████████████████████ 89%
57+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
58+
```
4859

49-
The headline performance number is hardware-specific. The project uses a conservative reference claim: the best optimized kernel reaches about **85% of cuBLAS-class throughput** on the documented RTX 3080 1024×1024 benchmark.
60+
> 性能数字基于 RTX 3080、1024×1024 矩阵场景。本项目采用保守口径，用于教学对比而非跨硬件承诺。
5061
5162
---
5263

53-
## Quick start
64+
## 与业界项目对比
5465

55-
Requirements: CUDA Toolkit 11.0+, CMake 3.18+, a C++17 compiler, and an NVIDIA GPU with compute capability 7.0+.
66+
| 项目 | 定位 | 本项目差异 |
67+
|------|------|-----------|
68+
| **cuBLAS** | NVIDIA 官方 BLAS 库 | 本项目是教学版，逐级展示优化过程 |
69+
| **CUTLASS** | CUDA 模板库 | 本项目更简单，适合入门学习 |
70+
| **llama.cpp** | LLM 推理框架 | 本项目聚焦 GEMM 优化教学 |
71+
| **vLLM** | LLM 服务框架 | 本项目是底层 kernel 教学 |
72+
73+
**推荐学习路径：**
74+
```
75+
本项目 (GEMM 基础) → CUTLASS (进阶) → cuBLAS (生产)
76+
```
77+
78+
---
79+
80+
## 快速开始
81+
82+
**要求：** CUDA Toolkit 12.x、CMake 3.18+、C++17 编译器、NVIDIA GPU (SM 7.0+)
5683

5784
```bash
5885
git clone https://github.com/LessUp/mini-inference-engine.git
5986
cd mini-inference-engine
6087

88+
# Debug 构建 + 测试
6189
cmake --preset default
6290
cmake --build --preset default
6391
ctest --preset default --output-on-failure
6492

93+
# Release 构建 + Benchmark
6594
cmake --preset release
6695
cmake --build --preset release
6796
./build-release/benchmark
6897
```
6998

70-
GPU tests skip when no CUDA device is available, but building still requires a CUDA toolkit because the library is compiled as a CUDA project.
99+
---
100+
101+
## 核心架构
102+
103+
```
104+
┌─────────────────────────────────────────────────────────────┐
105+
│ Application Layer │
106+
│ Benchmark / MNIST Demo / Tests │
107+
└─────────────────────────────────────────────────────────────┘
108+
│
109+
▼
110+
┌─────────────────────────────────────────────────────────────┐
111+
│ Engine Layer │
112+
│ InferenceEngine / Tensor / AutoTuner / Profiler │
113+
└─────────────────────────────────────────────────────────────┘
114+
│
115+
▼
116+
┌─────────────────────────────────────────────────────────────┐
117+
│ Kernel Layer │
118+
│ 7-Level GEMM / FP16 GEMM / Batch GEMM / cuBLAS │
119+
└─────────────────────────────────────────────────────────────┘
120+
│
121+
▼
122+
┌─────────────────────────────────────────────────────────────┐
123+
│ Infrastructure Layer │
124+
│ MemoryPool / StreamManager / Logger / Config / Quantization│
125+
└─────────────────────────────────────────────────────────────┘
126+
```
127+
128+
---
129+
130+
## 文档
131+
132+
| 主题 | 中文 | English |
133+
|------|------|---------|
134+
| 快速开始 | [快速入门](docs/zh/QUICK_START.md) | [Quick Start](docs/en/QUICK_START.md) |
135+
| 架构设计 | [架构](docs/zh/ARCHITECTURE.md) | [Architecture](docs/en/ARCHITECTURE.md) |
136+
| GEMM 优化 | [优化详解](docs/zh/GEMM_OPTIMIZATION.md) | [Optimization](docs/en/GEMM_OPTIMIZATION.md) |
137+
| 性能调优 | [调优指南](docs/zh/PERFORMANCE_TUNING.md) | [Tuning](docs/en/PERFORMANCE_TUNING.md) |
138+
| API 参考 | [API](docs/zh/API_REFERENCE.md) | [API](docs/en/API_REFERENCE.md) |
139+
| 学习路径 | [学习计划](docs/zh/guides/learning-path.md) | [Learning Path](docs/en/guides/learning-path.md) |
140+
| FAQ | [常见问题](docs/zh/guides/faq.md) | [FAQ](docs/en/guides/faq.md) |
71141

72142
---
73143

74-
## Documentation map
144+
## 学术论文引用
75145

76-
| Topic | English | 中文 |
77-
| --- | --- | --- |
78-
| Quick Start | [docs/en/QUICK_START.md](docs/en/QUICK_START.md) | [docs/zh/QUICK_START.md](docs/zh/QUICK_START.md) |
79-
| Architecture | [docs/en/ARCHITECTURE.md](docs/en/ARCHITECTURE.md) | [docs/zh/ARCHITECTURE.md](docs/zh/ARCHITECTURE.md) |
80-
| GEMM Optimization | [docs/en/GEMM_OPTIMIZATION.md](docs/en/GEMM_OPTIMIZATION.md) | [docs/zh/GEMM_OPTIMIZATION.md](docs/zh/GEMM_OPTIMIZATION.md) |
81-
| Performance Tuning | [docs/en/PERFORMANCE_TUNING.md](docs/en/PERFORMANCE_TUNING.md) | [docs/zh/PERFORMANCE_TUNING.md](docs/zh/PERFORMANCE_TUNING.md) |
82-
| API Reference | [docs/en/API_REFERENCE.md](docs/en/API_REFERENCE.md) | [docs/zh/API_REFERENCE.md](docs/zh/API_REFERENCE.md) |
83-
| Development Guide | [docs/en/CONTRIBUTING.md](docs/en/CONTRIBUTING.md) | [docs/zh/CONTRIBUTING.md](docs/zh/CONTRIBUTING.md) |
146+
本项目的优化技术来自以下经典论文：
147+
148+
```bibtex
149+
@article{volkov2009better,
150+
title={Better performance at lower occupancy},
151+
author={Volkov, Vasily},
152+
journal={GTC},
153+
year={2009}
154+
}
155+
156+
@inproceedings{hong2009analytic,
157+
title={An analytical model for the GPU architecture},
158+
author={Hong, Sunpyo and Kim, Hyesoon},
159+
booktitle={ISPASS},
160+
year={2009}
161+
}
162+
```
84163

85164
---
86165

87-
## Engineering workflow
166+
## 工程规范
167+
168+
- **规格驱动**：`openspec/specs/**` 作为唯一事实源
169+
- **构建系统**：显式源列表，禁止 globbing
170+
- **代码风格**：`.clang-format` (Google-based, 4-space)
171+
- **测试分类**：`tests_host` (无 GPU) + `tests_gpu` (需要 GPU)
172+
- **分支策略**：`master` 唯一长期分支
173+
174+
详见 [AGENTS.md](AGENTS.md)。
175+
176+
---
88177

89-
- Source of truth: `openspec/specs/**`.
90-
- Build system: explicit source lists in `CMakeLists.txt`; do not use recursive globbing for source files.
91-
- Formatting: `.clang-format` with Google-based 4-space style.
92-
- Tests: `tests_host` covers utilities that do not require a GPU device; `tests_gpu` covers CUDA runtime/kernel behavior. Configuring and compiling the project still requires a CUDA Toolkit.
93-
- Branching: keep `master` as the only long-lived branch; use short-lived branches/worktrees for changes and delete them after merge.
178+
## License
94179

95-
See [AGENTS.md](AGENTS.md) for the full project-specific AI and engineering workflow.
180+
[MIT](LICENSE) © 2024-present

0 commit comments

Comments
 (0)