Handwired 执行模型完全解读:4 种指令、分层编译与 Gather 降级规则全解析

原创2026-10-19 10:04:211,899 阅读

Handwired 执行模型完全解读:4 种指令、分层编译与 Gather 降级规则全解析

Handwired 是一个把普通 JavaScript 代码变成神经网络的开源项目:它把 if-else、循环和状态改写成矩阵乘法加 ReGLU(浮点上的加权求和与门控),无需训练、结果精确,却仍是完全可微分的。而 Handwired 执行模型的全部秘密,就藏在 4 种指令、一套分层编译流程和 Gather 降级规则里。这篇教程带你从底层规则到实测数据,一次看懂它的编译原理与优化开关。

Handwired 执行模型演示:HandwiredOS 的 Monitor 窗口展示程序的指令类型、分层与权重统计

上图是 HandwiredOS 的 Monitor 窗口:左侧表格逐行列出程序的 wire 及其指令类型(affine、ReGLU、boolean),底部汇总了 4,646 个 operations、130 个 layers、9,909 个 weights。这张图本身就是执行模型最好的注脚——一个"操作系统"的全部逻辑,就是这几种指令的有序列表。

程序长什么样:源单元格 + 有序指令列表 🧱

一个 Handwired 程序由两部分组成(详见 docs/execution-model.md):

  • 源单元格(source cells):一个 Float32Array,所有状态、常量、浏览器输入都从这里进入;
  • 有序指令列表:每条指令产出 1 个数,追加在源单元格之后。

wire(线)就是位置:某个源单元格或某条指令产物的下标。每条指令只能读取源单元格和更早的指令,永远不能读取后面的指令——这保证整个程序是一张 DAG,也是能按"层"并行执行的前提。

所有算术都是 FP32(32 位浮点),每一步求和与乘法都按 Math.fround 逐次舍入,指令顺序就是舍入顺序。这就是 Handwired 结果"精确"的代价,也是它"可微"的基础。

4 种指令速查表:affine、reglu、boolean、index

Handwired 全部程序只由 4 种指令构成(定义与求值实现见 numeric-ui-core.ts):

指令 计算内容 直觉
affine bias + Σ 系数 × wire(逐项 FP32 舍入) 加权求和,一切的"地基"
reglu(left, gate) f(left × max(0, gate)) 门控非线性,同时是"乘法"
boolean(score) f(f(f(score) + 8_388_609) - 8_388_609),0.5 以下取 0,其余取 1 精确二值化决策
index(form, candidates, ...) 读 candidates[floor(form)],越界按 clamp / zero 规则处理 查表读取

为什么是这 4 种?

  • affine 承载所有加法。小常数会被折叠进 bias,小于 4 项的小和式还会被内联进读取方。
  • reglu 是双重身份。当 left 是常数 1 时它就是 ReLU;当 gate 是 0/1 bit 时它就是精确乘法——连 a × b 都被它吞掉了。
  • boolean 的"大数取整"技巧。8,388,609 是 2^23 + 2^19。在这个量级附近,FP32 相邻可表示值恰好相差 1,所以加上它再减掉它,就把 0..1 的任意连续分数在 0.5 处精确地四舍五入成 0 或 1——这是从"分数"到"决策 bit"的关键一步。
  • index 就是查表。选中的值被原样复制、不做任何舍入,整数和 0/1 bit 穿过表后依然精确;越界侧可按 'clamp' 或 'zero' 规则处理(规则全文见 docs/execution-model.md)。

其余一切——比较 emitCompare、选择 emitSelect、最小值 emitMinimum——都是"宏"(builder 函数),在构建程序时展开为这 4 种指令的组合。宏的精确性契约汇总在 docs/execution-model.md 与 docs/expressions.md。

分层编译:按依赖深度把指令排进 Layer

编译规则只有一句话:同一依赖深度的独立指令共享一个 layer。每个 layer 的执行器按固定流水线运行:

  1. 收集更早的输入值;
  2. 执行稀疏仿射投影(一次稀疏矩阵乘法);
  3. 执行 gather 读、index 读;
  4. 施加 ReGLU 门控与 boolean 取整;
  5. 追加本层输出。

默认策略下,一条指令的 layer 就是它的构建时深度:它读取的最深 wire 再 +1。

recomputeDepths:按编译后依赖重新排层

compileTensorProgram(roots, lowerGathers, {recomputeDepths: true})(numeric-ui-core.ts)换了一种排法:每条存活指令放在"编译后程序中它读取的最深值"之后一层。这在与 Gather 降级配合时非常关键——一个被降级成 gather 的掩码求和,不再排在它替身的那些乘积之后,其后的操作就能整体前移。编译后的程序会跳过没有存活指令的深度,所以被删掉的乘积只在仍有其他指令共享该深度时才占一层。

死代码消除与小和式内联

编译还会删掉到不了任何请求输出的操作,并在紧凑存储中重排独立值(wireOrder 记录重排映射)。两类操作会直接消失:

  • 少于 4 项的普通 affine 和式:被逐词复制到读取方里;
  • 常量 wire:直接折叠进读取方的 bias。

所以 circuit.operations.length 可能高估程序规模——HandwiredOS 构建了 5,028 个操作,编译后只有 4,646 个存活。想统计真实规模,应数编译后程序的 valueCount - sourceSize。

Gather 降级:一次选择,一次读取 ⚡

这是 Handwired 编译器最有价值的一项优化(planGatherLowering,numeric-ui-core.ts)。

触发条件:两条都要满足

条件一:选择必须是声明过的 one-hot 组。 成员是精确 bit、且恰好一个为 1(assumeOneHot 声明;emitArgmax 会自动声明自己的选择)。

条件二:每个候选值都必须有有限 FP32 上界。 因为未选中的 Infinity × 0 会算出 NaN,把稠密求和"毒化"。

编译器识别的求和形态(成员在任一侧均可):

  • Σ multiply(selected[j], height[j]);
  • 写成 ReGLU 的等价形态:f(value × max(0, bit))(候选有界)、f(bit × max(0, value))(候选非负有界),以及允许负值时的一正一负配对。

求和可以带 bias,候选也可以是更早的 gather 读。但只要出现缩放项(如 2 × selected[1] × height[1])、缺成员、或混入另一个 one-hot 组的乘积,整个求和就保持稠密——因为只替换一部分会改变 FP32 的加法顺序。

降级后的语义

gather 返回 f(bias + 选中候选)。执行器先用 Σ j × member[j] 解析出组索引(精确整数),每次 gather 只读 1 个候选。若组允许全 0,候选先乘以成员和,未激活的组就贡献 0。稠密求和与 gather 的值完全一致,唯一差异可能是精确 0 结果的符号(如 -0 vs +0),验证器视两者相等。

一句话:gather 降级只缩短"选择之后的读取"——选择本身和每个候选仍然照常计算。

成本对比:10,000 项表读取

实现方式 存活操作数 存储权重数
ReLU one-hot 掩码求和(启用 gather 降级) 30,002 49,998
index 读(计算出的整数下标) 1 1

这正是"该用哪种读取"的分界线(来自 docs/execution-model.md):

  • 选择已经是声明过的 one-hot(如 emitArgmax 的产物)→ 让编译器做 gather 降级;
  • 下标是一个计算出来的整数(如由滚动位置推出的行号)→ 直接用 circuit.indexRead。

HandwiredOS 实测:4,646 操作、130 层、0.12 ms

回到开头的截图。HandwiredOS 这个用电路写成的迷你桌面系统,其编译后程序:

  • 4,646 个存活操作,分 13 种指令类型分布(1,811 affine、2,776 ReGLU、59 boolean);
  • 130 个 layer,9,909 个存储权重,仅 114 KB;
  • 单次评估约 0.12 ms(CPU 执行器)。

它的 Windows 命中测试展示了声明如何影响成本:指针坐标和窗口几何声明在 1/64 px 网格上后,每个边缘比较只需 2 个操作的"整数 bit";若指针范围放大到 ±65,536 px,同一比较就退化成 13 层 15 操作的符号级联(对比与成本表见 docs/execution-model.md)。

该选哪种执行路径?CPU 数操作,GPU 数层

成本规则是理解所有"树 vs 循环"权衡的钥匙(实测见 lab/runtime-cost/layers.ts):

  • CPU 执行器的时间跟随操作数:同一计算 8~11 µs / 1,000 操作,无论它排成 10,232 层的链还是 230 层的树;
  • 每个 layer 还有固定开销:约 10 µs / 1,000 层(拷贝输入输出),所以"删操作但加层"未必更快;
  • GPU 上树往往更快:树的一层就是一次对所有节点合并的 dispatch。例如 json-search 的同一程序在 WebGPU 上对 100,000 份 JSON 文档并行搜索约 5 ms,而 CPU 上生成的 JavaScript 要 13~14 秒(见 src/json-search/README.md)。

Handwired GPU 输出示例:由编译后的电路逐像素渲染出的文字与排版帧

上图是 pixel-output 实验在 GPU 上渲染的一帧文字——同样的 4 种指令、同一套分层规则,后端换成 WebGPU shader 后,连字形光栅化都由电路直接产出。

新手上手:三步开始玩 🚀

git clone https://gitcode.com/gh_mirrors/ha/handwired
cd handwired && bun install
bun start

推荐学习路径:

  1. 读 docs/tutorial.md——用 template/toggle.ts 的开关开关走一遍"单元格 → 构建代码 → 宿主循环"全流程;
  2. 读 docs/execution-model.md——本文展开的执行模型权威文档,含 4 种指令的求值伪代码与宏契约;
  3. 对照 docs/expressions.md 和 docs/patterns.md 查"某个 JavaScript 表达式/循环在电路里怎么写、花几层几操作"。

最后记住三条底层规则:声明(assumeRange、assumeGrid、assumeOneHot)是调用方的承诺而非证明,编译器信任它;参考求值器(evaluateReference)定义程序语义,编译后程序必须逐值复现;所有精确性契约都由 tests/runtime/ 中的差分测试守住。理解这三点,你就拿到了解读 Handwired 任何源码的钥匙。

登录后查看全文
handwired