Qwen 权重编译 NES CPU 实现模型内运行游戏
nesformer 项目通过编译器将 NES 6502 CPU、RAM 及 ROM 逻辑直接映射至标准 Qwen3.5 模型权重中,无需训练即可在模型内部模拟执行。该方案利用 Gated DeltaNet 状态作为机器内存,使大语言模型能够逐 token 预测 CPU 执行日志,从而在约 1GB 的权重空间内完整运行《超级马里奥》等经典游戏。
关联知识实体
报道正文
本文目录7 个章节
nesformer
将 NES CPU 编译进标准 Qwen3.5 模型的权重中。
NES 的 6502 CPU(其 2A03 芯片的核心)、2 KB 的工作 RAM 以及卡带的程序 ROM,均运行在标准的 Qwen3_5ForCausalLM 检查点内。这些权重并非经过训练得到,而是由编译器计算生成的。当你玩游戏时,模型会逐个 token 地预测 CPU 的执行日志。一个小型宿主程序负责处理控制台的其他部分:绘制画面、读取控制器输入并触发 vblank 中断。
nesformer 基于 Divyansh Agrawal 开发的 Qwenputer 构建,后者曾将 CHIP-8 和 RISC-V CPU 编译进 Qwen3.5-4B 模型。它复用了 Qwenputer 的编译器及其核心技巧:模型的 Gated DeltaNet 状态即为机器的内存。
| Super Mario Bros. (World 1-1) | Doug Fraker 制作的完整游戏(标题画面及第一关) |
|---|---|
![]() | ![]() |
在这些运行过程中,每一个 CPU token 均由模型生成。对于捆绑的测试游戏,每一帧也与传统 6502 模拟器的输出完全匹配(参见如何验证)。
快速开始
1. 文件夹布局
将 nesformer.zip 和 nesformer-weights.zip 解压到同一文件夹中。权重文件应位于 nesformer/ 包旁边,而不是在其内部:
nesformer/ <- 在此处运行命令
├── nesformer/ <- Python 包
├── chipformer/ <- Qwenputer 的编译器
├── roms/ <- 测试 ROM(也可放入你自己的 ROM)
├── examples/ <- 示例 GIF 和帧表
├── tests/
├── LICENSE
├── LICENSE.chipformer
├── README.md
├── pyproject.toml
└── weights/ <- 来自 nesformer-weights.zip
├── config.json
├── generation_config.json
├── model.safetensors
├── nesformer.json
└── SHA256SUMSCLI 会在 nesformer/ 包旁边查找 weights/ 目录。若要将权重存放在其他位置,请在执行 run、check 或 trace 时传入 --weights /path/to/weights,或在执行 info 时提供该路径。
要确认权重解压是否正确,请从顶层文件夹运行 shasum -a 256 -c weights/SHA256SUMS。
2. 安装
你需要 Python 3.11 或更高版本。
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install numpy scipy numba pillow3. 玩游戏
python -m nesformer run roms/thwaite.nes --frames 600 --show \
--buttons "start@90-95+200-205,a@230-233+250-253+270-273+290-293+310-313+330-333+350-353+370-373+390-393+410-413+430-433+450-453+470-473+490-493+510-513+530-533+550-553+570-573+590-593"--show 会在模型生成每一帧时,在终端中绘制该帧。运行结束后,CLI 会在当前文件夹中保存一个以 ROM 命名的动画 GIF(此处为 thwaite.gif)。
预期速度较慢。首次运行会使用 numba 编译引擎,耗时约 20 秒。此后,每帧需要 1–6 秒,因此 600 帧(相当于 NES 时间中的 10 秒)大约需要 25 分钟。
运行你自己的 ROM
将 run 指向任何使用 NROM 板卡(iNES mapper 0)的 .nes 文件,例如《超级马里奥兄弟》、《大金刚》或《越野摩托》。你需要提供 ROM;nesformer 仅在 roms/ 目录中附带三个自由许可的测试 ROM。
python -m nesformer run roms/smb.nes --frames 600 --show \
--buttons "start@60-65,right@200-600,a@250-265+300-315+360-375+420-435+480-495+540-555"该脚本会启动游戏,然后让马里奥向右行走并大约每秒跳跃一次。CLI 在启动时将 ROM 加载到模型的状态中,因此相同的权重可以在无需重新构建的情况下运行任何 NROM 游戏。其他板卡上的游戏会停止并显示一条消息:参见 局限性。
控制器脚本
--buttons 接受一个逗号分隔的条目列表。每个条目指定一个或多个由 + 连接的按钮,然后是 @,再后是一个或多个由 + 连接的帧范围:
start@60-65 在第 60 到 65 帧期间按下 Start
right@200-600 从第 200 帧到第 600 帧按住 Right
a@250-265+300-315 按两次 A
right+b@200-600 同时按住 Right 和 B(在《超级马里奥兄弟》中即为奔跑)按钮包括 a、b、select、start、up、down、left 和 right。帧数从开机开始计算,每秒 60 帧,因此第 600 帧对应开机后的 10 秒。游戏在无法移动的画面中会忽略输入,因此稍早按住按钮不会造成问题。在《超级马里奥兄弟》中,更长的 A 键按压会使跳跃高度更高。
命令
| 命令 | 功能说明 |
|---|---|
python -m nesformer run ROM | 在权重上运行 ROM 并保存为 GIF |
python -m nesformer check ROM | 并行运行模型权重与参考 CPU,并在出现首个差异时停止 |
python -m nesformer trace ROM | 打印模型的 token 流(默认 40 个 token) |
python -m nesformer build | 编译电路并写入 weights/(约需 10 秒) |
python -m nesformer info | 描述检查点信息 |
run 的选项:
| 选项 | 默认值 | 含义 |
|---|---|---|
--frames N | 120 | 在 N 帧后停止 |
--buttons SCRIPT | 无 | 控制器输入(见上文) |
--show | 关闭 | 在终端中绘制帧(需要 24 位色支持,例如 iTerm2 或 Windows Terminal) |
--gif PATH | ROM 名称 | 指定动画 GIF 的保存路径 |
--png DIR | 关闭 | 将每个保留的帧以 PNG 格式保存到 DIR。若仅使用 --png,则不保存 GIF。添加 --gif 可同时生成两者。 |
--every N | 1 | 每第 N 帧保留一帧 |
--scale N | 2 | 将保存的帧放大 N 倍 |
--engine | fast | 可选 fast (numba)、numpy 或 hf (标准 transformers;需要 torch,约 10 tokens/s) |
--no-skip | 关闭 | 运行空闲等待循环的每次迭代(速度较慢;生成的帧相同) |
--max-tokens N | 无 | 在 N 个 token 后停止 |
--trace FILE | 无 | 保存 token ID |
run、check 和 trace 均接受 --weights、--engine、--buttons 和 --no-skip 参数。
check --tokens N 设置比较的深度(默认 50,000)。trace --tokens N 设置打印的 token 数量(默认 40)。build --out DIR 将检查点写入除 weights/ 以外的其他目录。
(注:更多技术实现细节与完整 API 文档请查阅原项目 README)

