mirage

环境要求

• 支持 CUDA 的 NVIDIA GPU（项目用 Cuda 实现，README 未注明具体版本）
• Python 3 与 pip 环境
• git（需支持 --recursive 拉取子模块）
• 可编译 Cuda 扩展的本地开发环境（pip install -e . 会从源码构建）

安装与启动步骤

1. 1克隆 mpk 分支源码

   README 要求带 --recursive 拉取子模块，并指定 mpk 分支，否则不是 Persistent Kernel 版本。

   git clone --recursive --branch mpk https://www.github.com/mirage-project/mirage

   复制

2. 2进入项目目录

   切换到克隆下来的 mirage 目录，后续安装与运行都在该目录下进行。

   cd mirage

   复制

3. 3源码安装

   以可编辑模式安装 MPK，会从源码构建，耗时较长，加 -v 可看到详细编译日志。

   pip install -e . -v

   复制

4. 4设置 MIRAGE_HOME

   把环境变量指向当前源码根目录，供运行时定位 Mirage 相关文件。

   export MIRAGE_HOME=$(pwd)

   复制

5. 5运行原生内核 demo

   先用原生 Triton 和 FlashInfer 内核跑通 Qwen3-8B demo，作为后续对比基线。

   python demo/qwen3/demo.py

   复制

6. 6编译并运行 MegaKernel

   加上 --use-mirage 让 MPK 把模型编译成 megakernel 后执行，观察延迟变化。

   python demo/qwen3/demo.py --use-mirage

   复制

7. 7开启 profiling

   再加 --profiling 可视化每个任务的执行时间线，用于定位性能瓶颈。

   python demo/qwen3/demo.py --use-mirage --profiling

   复制

关键配置

如何确认成功

demo 脚本正常结束且终端无报错；加 --use-mirage 后能完成 megakernel 编译并输出推理结果。

常见问题

注意事项

• 必须使用 --branch mpk 分支，主分支不是 MPK 版本。
• clone 时不要省略 --recursive，否则子模块缺失会导致安装失败。
• pip install -e . -v 会本地编译 Cuda 扩展，耗时较长，请预留编译时间。
• export MIRAGE_HOME 只在当前 shell 生效，建议写入 shell 配置文件以便持久化。