Design Docs Are All You Need: An AI-native Machine-Learning Performance Tool
Samuel Kushnir, Kimia Noorbakhsh, Kavya Sreedhar, Liqun Cheng, Ming Liu, Parthasarathy Ranganathan, Mohammad Alizadeh, Fred Kjolstad, Suvinay Subramanian
cs.PL, cs.AI
2026-09-05
SMART用50份文档重生性能库，一次1.5–3小时约100美元，DeepSeek-V3 TPU模型对齐到舍入误差。
机器学习性能建模夹在两层 churn 最快的栈中间。上面是几个月一变的模型结构，MoE 路由、latent attention、prefill 与 decode 两套相位，会让「每层 Transformer 长得一样」这种去年还合理的假设当场过期。下面是一代一换的加速器和互联。框架只能靠重构和打补丁把新结构塞进旧抽象。
补丁会生第二层债。人改代码时几乎从不删掉旧实现、按当前规格从零再写一遍，每次都是拿旧代码当额外输入做增量修补。论文把「增量修补后的系统」和「按当前规格从零生成的系统」之间的距离叫 incremental generation debt。coding agent 进来之后多了一层 context-window myopia：窗口装不下整库，只能喂局部片段，改动局部看起来对，全局结构慢慢散。
SMART 的选择是把代码当成可抛弃的构建产物。人只改自然语言设计文档，实现按文档重生。
主分支几乎没有代码。仓库是一堆 markdown 设计文档，组成一张 DAG（有向无环图，边表示谁必须先生成）。边不手写，由只读 agent 从文档里推断。编排器按拓扑序走图，每个文档派一个 coding 子代理单独实现。生成结果要过手写参考模型的 reconciliation、参数守卫和单测，失败就回到重生，通过才替换上一版构建。人只改文档。
一文一代理有三个直接后果。每个生成任务被限制在单篇文档的上下文里，比把整库塞进一次 prompt 更不容易写崩。编排器日志记下哪些文档让 agent 卡住、哪一波引入了 bug，下一轮人知道该改哪一段散文。核心 DSL 这类基础文档可以路由到更强的模型，下游模型目录用便宜模型就够。
文档写法也很具体。常见控制面是测试和高层 constitution（生成器必须遵守的项目宪法）。SMART 额外要求自底向上的 worked example：把伪代码在具体输入上走一遍，中间 shape、中间值、最终应该得到的闭式代价表达式都写出来。每份带数字的文档末尾还有 reconciliation anchor，一个小预设，期望输出写死，由生成测试卡住。一个 vignette 长这样：2×2×2 带环绕的 torus 上，每节点链路数是 3 不是 6，V 字节的 all-gather 因此代价是……
被生成的对象本身也必须少而稳。IR 只有一种递归 Op。输入输出是带符号 shape 的 Tensor；cost 是按计算、内存、通信分项的 SymPy 表达式（Python 符号计算，数值代入前一直保持闭式）；RRT 是资源预约表，行是硬件资源、列是周期、格子是占用数量；params 要么是带 trip count 的循环，要么是子图，要么是叶子。叶子是软硬件交界：系统侧给这颗叶子标 RRT 和代价。当前叶子按 TPU 塑形，包括 MXU 矩阵乘瓦片（TPU 的矩阵乘单元）、VMEM 载入（片上向量内存）和 ICI 集合通信（芯片间互联）。算法侧把叶子嵌进循环。换一种 attention 或换一代互联，只动自己那一侧的文档。
模型用一层嵌在 Python 里的 tracing DSL 写，人不手搓 Op 节点。@smartloop 是带累加器的 reduction，@smartmaploop 是并行 map。所有维度都是符号，一次 trace 覆盖整个设计空间。FlashAttention 核用同一套循环服务 prefill（查询长度 Tq 与 KV 长度 Tkv 都等于序列长 T）和 flash-decoding（Tq=1，Tkv 等于上下文长），(B,H,Tq,Tkv) 分数矩阵不离开 VMEM。分布式用 sharding 注解而不是手写集合通信：张量每个维度标它切在哪条 mesh 轴上，sharded-einsum 从操作数和输出的切分推断 AllGather 与 ReduceScatter。只有改布局的通信显式写出，DeepSeekMoE 块里把 expert-parallel 轴从 token 维挪到 expert 维的 dispatch all-to-all 就是这一类。
代价往上卷有两种模式。快模式把叶子代价乘上外层 trip count，再用 roofline（屋顶线，用算力上限和带宽上限夹出时间下界）风格的解析调度估通信计算重叠，闭式求值，用来扫几千个设计点。慢模式对每个循环做 modulo scheduling，把循环体按资源容量软件流水线排进 RRT，得到的 initiation interval（每隔多少周期能再发一次循环体）再递归往上卷。数值代入只发生在最外层，一份符号构建服务整次 sweep。设计文档甚至可以写死某次集合通信代价的闭式表达式，生成测试去断言它。
库现在是 50 份设计文档，大约 9000 行规格散文，覆盖 TPU 拓扑、集合通信代价、数值格式、调度器，以及 dense、MoE、latent-attention、机器人 VLA 等模型目录。master 只留文档加少量叶子工具函数。
一次从零重生用 Claude Code，墙钟 1.5–3 小时，API 费用大约 100 美元，大约占 Claude Max 周配额的 20%。重生后的实现与手审参考模型对齐到舍入误差，论文点名的例子是 DeepSeek-V3 在一块 TPU pod slice 上的 serving 模型。
| 项目 | 数字 | 对照 |
| 设计文档 | 50 份，约 9000 行 | 主分支几乎无代码 |
| 全量重生 | 1.5–3 小时 | Claude Code |
| API 费用 | 约 100 美元 / 次 | 约 Claude Max 周配额 20% |
| DeepSeek-V3 TPU serving | 对齐到舍入误差 | 手审参考模型 |
论文没有给出预测延迟对实测硬件的误差表，也没有和现有性能估算器做对照。「对齐到舍入误差」是重生代码对手写参考模型，不是对芯片上的 wall-clock。
给系统组的信号很具体：规格 churn 比代码吸收更快时，把文档当 durable artifact、把实现当 build product，已经是可以跑的工作流，不是口号。技术债被定义成增量修补与从零生成之间的距离，每次全量重生把这个距离按构造清零。模糊意图也更早暴露，因为猜的内容必须写进文档才能活过下一轮生成。
从业者能直接抄的不是这个 TPU IR，是那套文档纪律：一文一代理、worked example、数字文档必须带 reconciliation 测试、编排器日志当文档质量仪表。100 美元、两小时一次的重建成本，说明这件事对这个规模的库已经进入可以当常规 CI 的区间。
IR 本身是 roofline 加 modulo scheduling 的熟食。新意在软件生命周期，不在新的性能模型理论。
论文一共五页，没有实验节。DeepSeek-V3 对齐到舍入误差只出现在摘要和结论，没有误差表、没有失败重生次数、没有「改文档后第几次才过 reconciliation」。对照物是手审参考模型，读者无法判断这些参考本身离真实 TPU 有多远。按构造清零的是「增量修补相对从零生成」的距离，前提是生成器真的实现了文档；如果 agent 读错文档，而测试又是从同一批文档生成的，reconciliation 可能一起错。真正的外锚是那些手写参考，覆盖面文中没交代。
叶子按 TPU 塑形，换 GPU 或别的互联至少要重写系统侧文档，泛化没有证据。全量重生绑在 Claude Code 上，成本和成功率换别的 agent 栈会不会掉一截，文中没测。人并没有从维护里退出，只是维护对象从代码换成了必须写清楚 worked example 的文档。文档写糊，重生会在编排器日志里爆。