Mamba小白入门：Windows电脑一键跑通官方Mamba代码

本文目标只有一个：
不讲复杂公式，直接让第一次接触 Mamba 的小白把代码运行起来。

官方项目地址：

https://github.com/state-spaces/mamba

本文使用：

Windows + WSL2 + Ubuntu 24.04 + NVIDIA GPU
Python 3.12
PyTorch 2.7.1
mamba-ssm 2.3.2.post1

---

一、Mamba是什么

Mamba是一种用于处理序列数据的神经网络结构，可以用于文本、时间序列、语音和其他长序列任务。

小白只需要先记住：

1. Transformer处理长序列时，计算量通常增长得比较快。
2. Mamba使用状态空间模型处理序列。
3. Mamba的重点是更高效地处理长序列。

本文不推导公式，只运行官方代码。

---

二、为什么Windows要使用WSL2

官方Mamba项目主要面向Linux环境，并依赖PyTorch、CUDA和GPU计算。

因此，不建议小白直接在Windows原生Python中安装。

最省事的路线是：

Windows
  └── WSL2
       └── Ubuntu 24.04
            └── Python + PyTorch + Mamba

WSL2可以理解为Windows中的Linux环境。

---

三、准备条件

需要满足：

Windows 10较新版本或Windows 11
NVIDIA显卡
已经安装较新的NVIDIA Windows驱动
可以正常联网

没有NVIDIA显卡时，不建议按照本文安装官方GPU版本。

---

四、安装WSL2

4.1 打开管理员PowerShell

在Windows开始菜单中搜索：

PowerShell

右键选择：

以管理员身份运行

执行：

wsl --install -d Ubuntu-24.04
wsl --update

执行完成后重启电脑。

4.2 第一次打开Ubuntu

重启后，在开始菜单中打开：

Ubuntu 24.04

第一次打开时，需要设置：

Linux用户名
Linux密码

输入密码时，终端不会显示星号或字符，这是正常现象。

---

五、下载代码包

解压代码包后，可以看到：

Mamba_小白可运行代码包
├── README_先看这里.md
├── 一键安装并运行.sh
├── 再次运行.sh
├── 01_检查环境.py
├── 02_运行Mamba2.py
├── 03_最小分类模型.py
└── Mamba小白入门博文.md

假设文件夹位于Windows下载目录，在Ubuntu中进入目录：

cd /mnt/c/Users/你的Windows用户名/Downloads/Mamba_小白可运行代码包

例如Windows用户名是zhangsan：

cd /mnt/c/Users/zhangsan/Downloads/Mamba_小白可运行代码包

---

六、一键安装并运行

在Ubuntu中执行：

bash 一键安装并运行.sh

脚本会自动完成：

1. 检查NVIDIA显卡
2. 安装Python 3.12基础环境
3. 创建独立虚拟环境
4. 安装PyTorch CUDA版
5. 安装mamba-ssm
6. 运行Mamba-2示例

成功时会看到类似结果：

Mamba-2 运行成功
使用设备:  NVIDIA GeForce RTX 4070 SUPER
输入形状:  (2, 128, 64)
输出形状:  (2, 128, 64)

只要输入形状和输出形状一致，就说明Mamba-2前向计算已经运行成功。

---

七、核心代码解释

完整代码位于：

02_运行Mamba2.py

核心代码只有下面几行：

import torch
from mamba_ssm import Mamba2

device = torch.device("cuda")

x = torch.randn(
    2,      # 一次输入2个样本
    128,    # 每个样本有128个时间步或Token
    64,     # 每个时间步有64个特征
    device=device
)

model = Mamba2(
    d_model=64,
    d_state=64,
    d_conv=4,
    expand=2,
).to(device)

y = model(x)

print(x.shape)
print(y.shape)

输入格式为：

[批次大小, 序列长度, 特征维度]

本例中：

[2, 128, 64]

输出形状仍然是：

[2, 128, 64]

说明Mamba-2读取了一段序列，并为序列中的每个位置生成了新的特征。

---

八、以后怎么再次运行

安装完成后，不需要重复安装。

再次打开Ubuntu，进入代码目录后执行：

bash 再次运行.sh

---

九、运行最小分类模型

代码包还提供了一个简单的序列二分类示例：

source .venv/bin/activate
python 03_最小分类模型.py

它会生成一批人工序列数据，并使用Mamba-2完成：

前向传播
计算损失
反向传播
更新模型参数

看到损失和准确率不断输出，就说明Mamba-2可以正常参与训练。

---

十、常见错误

10.1 CUDA可用为False

错误表现：

CUDA 可用: False

解决方法：

1. 更新Windows中的NVIDIA显卡驱动。
2. 在管理员PowerShell中执行：

wsl --update
wsl --shutdown

3. 重新打开Ubuntu。

不要在WSL2中安装Linux NVIDIA显卡驱动。

10.2 找不到Ubuntu目录

先查看Windows用户名：

echo $env:USERNAME

然后替换命令中的：

你的Windows用户名

10.3 提示没有权限

不要使用：

sudo pip install

本代码包会创建.venv虚拟环境，Python包全部安装在虚拟环境中。

10.4 首次运行停留在某一步

Mamba-2首次运行时可能会编译Triton GPU内核。只要终端没有明确报错，就不要重复关闭窗口或连续执行命令。

---

十一、参数是什么意思

Mamba2(
    d_model=64,
    d_state=64,
    d_conv=4,
    expand=2,
)

简单理解：

参数	小白解释
d_model	每个时间步的特征数量
d_state	模型内部记录序列状态的大小
d_conv	局部卷积窗口大小
expand	模型内部特征扩展倍数

第一次运行时，不需要修改这些参数。

---

十二、总结

小白运行Mamba只需要记住三步：

第一步：安装WSL2和Ubuntu
第二步：进入代码包目录
第三步：执行 bash 一键安装并运行.sh

成功标志：

Mamba-2 运行成功
输入形状和输出形状一致
CUDA 可用为True

到这里，官方Mamba代码已经成功运行。