将任天堂 NES 编译进 Qwen 权重：nesformer 项目解析

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 状态就是机器的内存。

超级马里奥兄弟（世界 1-1）

完整游戏，作者 Doug Fraker（标题画面和第一关）

这些运行中的每个 CPU token 都来自模型。对于捆绑的测试游戏，每一帧也与传统 6502 模拟器的输出完全匹配（参见如何检查）。

快速开始

1. 文件夹布局

将 nesformer.zip 和 nesformer-weights.zip 解压到同一个文件夹。权重放在 nesformer/ 包的旁边，而不是里面：

nesformer/              <- run commands from here
├── nesformer/          <- the Python package
├── chipformer/         <- Qwenputer's compiler
├── roms/               <- test ROMs (put your own here too)
├── examples/           <- sample GIFs and frame sheets
├── tests/
├── LICENSE
├── LICENSE.chipformer
├── README.md
├── pyproject.toml
└── weights/            <- from nesformer-weights.zip
    ├── config.json
    ├── generation_config.json
    ├── model.safetensors
    ├── nesformer.json
    └── SHA256SUMS

CLI 会在 nesformer/ 包旁边查找 weights/。要将权重放在其他地方，请将 --weights /path/to/weights 传递给 run、check 或 trace，或者提供 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 pillow

3. 玩游戏

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）。

预计会很慢。第一次运行花费约 20 秒用 numba 编译引擎。之后，一帧需要 1–6 秒，因此 600 帧（10 秒的 NES 时间）大约需要 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                 press Start during frames 60 to 65
right@200-600               hold Right from frame 200 to frame 600
a@250-265+300-315           press A twice
right+b@200-600             hold Right and B together (run, in Super Mario Bros.)

按钮是 a、b、select、start、up、down、left 和 right。帧从开机起以每秒 60 帧计数，因此第 600 帧是 10 秒时。游戏在无法移动的屏幕上忽略输入，因此提前一点按住按钮没有坏处。在超级马里奥兄弟中，更长的 A 键按下会跳得更高。

命令

run 的选项：

run、check 和 trace 都接受 --weights、--engine、--buttons 和 --no-skip。check --tokens N 设置比较的距离（默认 50,000）。trace --tokens N 设置打印的 token 数量（默认 40）。build --out DIR 将检查点写入 weights/ 以外的位置。

工作原理

权重中有什么，没有什么

这种划分遵循 Qwenputer 的 CHIP-8 构建，其宿主注入定时器滴答并根据跟踪绘制显示。宿主除了通过跟踪之外，永远看不到 CPU 的寄存器或 RAM。

内存技巧是这样工作的。每个 DeltaNet 头维护一个 128 × 128 的状态矩阵，delta 规则在每个 token 处更新它。当门保持打开且键为 one-hot 时，一次更新恰好覆盖该矩阵的一行，而 one-hot 查询会将其读回。因此每一行都是一个内存单元，卡带、RAM 和寄存器都存在于行中。

检查点

weights/ 是一个普通的 Hugging Face 文件夹。它用 Qwen3_5ForCausalLM.from_pretrained 加载，不需要自定义代码。

nesformer.json 记录了机器的每个部分由哪一层和哪个头持有。一次运行将卡带、寄存器和 RAM 写入那些 DeltaNet 状态，然后进行贪婪解码。

层计划

跟踪

每条指令变成一个记录，记录的最后一个 token 提交它。如同 Qwenputer 的 RISC-V 核心，PC 是隐含的而非写出的：每个最终 token 携带其指令的长度，三个 DeltaNet 计数器统计自上次跳转以来每种长度的指令数，而 PC 是跳转目标加上该偏移量。完整游戏的摘录：

SEI            P(000100 px0 L1)
LDX #$40       X($40 c0 v0 px0 L2)
STX $4017      IOW($4017=$40 L3)
TXS            S($FF L1)
BIT $2002      IOR($2002) IN($00) P(000110 px0 L3)       <- the host injects IN
BPL $8017      J($8017)
JSR $8279      PSH($FE) PSH($FD) J($8279)                 <- the return address is pushed in-circuit
RTS            PUL($FC) LO($7B) PUL($FD) J($827C)
STA ($72),Y    LO($08) HI($03) ST($00 a7=0 L2)            <- pointer bytes latched, then the store
STA $4014      IOW($4014=$02 L0) DM(0:$FF) … DM(255:$00) NT(L3)   <- OAM DMA

大多数指令占用单个 token；真实游戏代码平均每条指令 1.1–1.3 个 token。nesformer/spec.py 记录了每个 token 家族。

如何检查

• 参考 CPU（nesformer/cpu.py）与 nestest 的黄金日志匹配 3,348 条指令，并与 py65 模拟器在 570 万条游戏代码指令上匹配。

• 精确电路，在 Qwenputer 的评估器中运行并带有其 bf16 精确性检查，预测每个参考 token：所有 nestest 加上两个游戏启动序列的 283,610 个位置。

• 原生 transformers 中的检查点（bf16，CPU）预测 nestest 和完整游戏的 2,651 个位置，没有不匹配。

• 权重自由运行，生成的跟踪与参考 CPU 的相同：

  运行	Token 数	帧数	NES 时间	结果
  nestest（官方操作码）	4,586	—	—	相同，以预期的 HALT 结束
  Thwaite，check	700,000	271	4.5 秒	相同的跟踪和帧
  Thwaite，run	1,916,527	600	10.0 秒	所有 300 个保存的帧匹配
  完整游戏，run	2,645,885	420	7.0 秒	所有 210 个保存的帧匹配

• 空闲循环跳过不会改变任何可见内容：帧和 I/O 写入（包括周期时间戳）与不启用该功能时一致。

速度

默认引擎从 model.safetensors 计算 Qwen3.5 的前向传播，使用 numba 编译并跳过全零块。在构建它的机器的一个 CPU 核心上，它运行速度约为 1,650 tokens/s。纯 numpy 引擎约为 210，原版 transformers 约为 10。真正的 NES 每秒需要约 700,000 个 token。

游戏在每一帧的大部分时间里都处于等待 vblank 的循环中。当主机看到循环体完全重复且没有 RAM 或 I/O 写入时，它会将时钟推进到下一个 PPU 事件之前，剩余的迭代仍会运行。这将 token 数量减少了 2.6 倍到 4.2 倍。总体而言，nesformer 的运行速度比真实主机慢 150–290 倍。

限制

• 仅支持 NROM 卡带（iNES mapper 0）。 CPU 一次只能寻址 32 KB 的程序 ROM。更大的游戏带有 bank 切换芯片（mapper，例如 MMC1 或 MMC3），用于切换 CPU 看到的 ROM 部分。nesformer 的 ROM 读取发生在模型内部，来自固定的 32 KB 表，因此它尚无法跟随 bank 切换。支持 mapper 意味着将整个 ROM 存储在状态中，同时将 bank 寄存器也保存在那里，并添加一个阶段将每个 CPU 地址转换为 ROM 地址。
• 仅支持官方操作码。非官方操作码会发出 HALT。
• 代码必须从卡带 ROM 运行。跳转到 RAM 会发出 HALT。
• 无 IRQ（APU 帧 IRQ、DMC）。BRK 和 NMI 正常工作。
• 对 I/O 寄存器的读-修改-写指令不会产生 I/O 写入，且 $4020–$7FFF 读取为 0（无 PRG-RAM）。
• PPU 和 APU 不在权重中。PPU 一次渲染一条扫描线，因此不会重现扫描线中间的效果。Sprite-0 命中与精灵溢出是近似的，且没有声音。

测试

pip install pytest py65
python -m pytest -q tests

测试需要几分钟。它们将参考 CPU 与 nestest 的日志进行对比，将电路与参考进行对比，将权重自由运行与参考进行对比，并检查空闲循环跳过。

在原版 transformers 中运行检查点

pip install "torch>=2.6" "transformers>=5.22"
python -m nesformer run roms/thwaite.nes --frames 3 --engine hf

nesformer/hfcheck.py 展示了整个过程：加载检查点，解码一个填充 token，将机器状态写入缓存的 DeltaNet 状态，然后一次一个地输入 token。

文件

致谢

• Qwenputer 及其 chipformer 编译器：MIT，© 2026 Divyansh Agrawal（LICENSE.chipformer）。该许可证也涵盖 nesformer/core.py 和 nesformer/weights.py 中改编自 Qwenputer 的代码。其最后一段指的是 Qwenputer 的 CHIP-8 ROM，本仓库不包含这些内容。
• 测试 ROM：nestest 由 Kevin Horton 编写；Full Game 由 Doug Fraker 编写（MIT）；Thwaite 由 Damian Yerrick 编写（GPL-3.0，源代码位于 pinobatch/thwaite-nes）。

许可证

nesformer 在 MIT 许可证下发布（见 LICENSE）。roms/ 中的 ROM 保留其自己的许可证，列在 roms/SOURCES.md 中。