dbreunig/nesformer

来源：https://github.com/dbreunig/nesformer

nesformer

一个 NES CPU 被编译进了原版 Qwen3.5 模型的权重之中。

NES 的 6502 CPU（2A03 芯片的核心）、2 KB 工作内存以及卡带的程序 ROM，全部运行在一个标准的 Qwen3_5ForCausalLM 检查点内。没有任何人训练过这些权重——每一个权重都是由编译器计算得出的。当你玩游戏时，模型会逐个 token 预测 CPU 的执行日志。一个小的宿主程序则负责模拟主机的其余部分：绘制画面、读取手柄输入、触发 vblank 中断。

nesformer 建立在 Divyansh Agrawal (https://divagr.com/blog/qwenputer) 的 Qwenputer (https://github.com/divagr18/qwenputer) 之上，后者将 CHIP-8 和 RISC-V CPU 编译进了 Qwen3.5-4B。nesformer 复用了 Qwenputer 的编译器及其核心技巧：模型的 Gated DeltaNet 状态就是机器的内存。

这些运行中的每一个 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 └── SHA256SUMS

CLI 会在 nesformer/ 包旁边查找 weights/ 目录。如果想把权重放在其他位置，请在 run、check 或 trace 命令中传入 --weights /path/to/weights，或向 info 命令提供路径。

要确认权重解压正确，请在顶层目录运行 shasum -a 256 -c weights/SHA256SUMS。

2. 安装

需要 Python 3.11 或更高版本。

bash python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install numpy scipy numba pillow

3. 玩游戏

bash 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 命名的动图文件（此处为 thwaite.gif）。

请做好慢速运行的准备。首次运行时，numba 编译引擎约需 20 秒。之后每帧需要 1–6 秒，因此 600 帧（相当于 10 秒的 NES 游戏时间）大约需要 25 分钟。

运行你自己的 ROM

将 run 指向任何使用 NROM 卡板（iNES mapper 0）的 .nes 文件即可，例如 Super Mario Bros.、Donkey Kong 或 Excitebike。ROM 由你自行准备；nesformer 仅附带 roms/ 中三个自由许可的测试 ROM。

bash 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 帧 a@250-265+300-315 按两次 A right+b@200-600 同时按住方向右和 B（在 Super Mario Bros. 中为奔跑）

可用按键为 a、b、select、start、up、down、left 和 right。帧从开机起计数，每秒 60 帧，因此第 600 帧是开机后 10 秒。游戏在无法移动的画面上会忽略输入，所以提前一点按住按键没有坏处。在 Super Mario Bros. 中，按住 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 的寄存器或内存。

内存技巧的原理如下。每个 DeltaNet 头维护一个 128 × 128 的状态矩阵，delta 规则在每个 token 时更新它。当门保持打开且 key 为独热向量时，一次更新恰好覆盖该矩阵的一行，而独热 query 则可以将其读回。因此每一行就是一个存储单元，卡带、RAM 和寄存器都存在于这些行中。

检查点

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

nesformer.json 记录了机器的各部分分别存放在哪一层和哪个头中。运行时将卡带、寄存器和 RAM 写入相应的 DeltaNet 状态，然后进行贪心解码。

层规划

执行轨迹

每条指令变成一条记录，记录的最后一个 token 提交它。与 Qwenputer 的 RISC-V 核心一样，PC 是隐含的而非显式写入的：每个最终 token 携带其指令的长度，三个 DeltaNet 计数器统计自上次跳转以来各长度指令的数量，PC 等于跳转目标加上该偏移。以下摘自 Full Game：

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) <- 宿主程序注入 IN BPL $8017 J($8017) JSR $8279 PSH($FE) PSH($FD) J($8279) <- 返回地址在电路内被压栈 RTS PUL($FC) LO($7B) PUL($FD) J($827C) STA ($72),Y LO($08) HI($03) ST($00 a7=0 L2) <- 先锁存指针字节，然后存储 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）在 3,348 条指令上与 nestest 的黄金日志一致，并在 570 万条游戏代码指令上与 py65 模拟器一致。

• 精确电路在 Qwenputer 的评估器中运行（带 bf16 精确性检查），预测了每一个参考 token：包括完整的 nestest 以及两个游戏启动序列的 283,610 个位置。

• 原版 transformers 中的检查点（bf16，CPU）在 nestest 和 Full Game 的 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 帧保存帧均匹配
  Full Game，run	2,645,885	420	7.0 秒	全部 210 帧保存帧均匹配

• 空闲循环跳过不改变任何可见内容：帧画面和 I/O 写入（包括周期时间戳）与未启用跳过的运行完全一致。

速度

默认引擎从 model.safetensors 计算 Qwen3.5 的前向传播，用 numba 编译并跳过全零块。在构建机器的单个 CPU 核上，速度约为 1,650 token/s。纯 numpy 引擎约 210 token/s，原版 transformers 约 10 token/s。真实的 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 逐扫描线渲染，因此无法重现扫描线中途的效果。精灵 0 命中和精灵溢出是近似模拟的，且没有声音。

测试

bash pip install pytest py65 python -m pytest -q tests

测试需要几分钟。它们将参考 CPU 与 nestest 日志对比、电路与参考对比、自由运行的权重与参考对比，以及空闲循环跳过功能进行验证。

在原版 transformers 中运行检查点

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

nesformer/hfcheck.py 展示了完整流程：加载检查点、解码一个 padding token、将机器状态写入缓存的 DeltaNet 状态，然后逐个喂入 token。

文件

致谢

• Qwenputer (https://github.com/divagr18/qwenputer) 及其 chipformer 编译器：MIT 许可，© 2026 Divyansh Agrawal（LICENSE.chipformer）。该许可证同样适用于 nesformer/core.py 和 nesformer/weights.py 中从 Qwenputer 改编的代码。其最后一段提到的是 Qwenputer 的 CHIP-8 ROM，本仓库并未包含这些 ROM。
• 测试 ROM：nestest 由 Kevin Horton 开发；Full Game 由 Doug Fraker 开发（MIT）；Thwaite 由 Damian Yerrick 开发（GPL-3.0，源码位于 pinobatch/thwaite-nes (https://github.com/pinobatch/thwaite-nes)）。

许可证

nesformer 以 MIT 许可证发布（参见 LICENSE）。roms/ 中的 ROM 保留各自的许可证，列于 roms/SOURCES.md。