The Annotated Transformer（逐行注解的 Transformer）

Sasha Rush 等 · Harvard NLP · 把 i16 的论文「翻译成可运行代码」的经典示范

论文名片

i17 论文名片
英文题名	The Annotated Transformer
中文常用名	逐行注解的 Transformer
作者与出处	Sasha Rush 等，Harvard NLP
链接	教程 nlp.seas.harvard.edu/annotated-transformer；代码 github.com/harvardnlp/annotated-transformer
一句话概括	论文每一段旁边就是对应的 PyTorch 代码，读完一遍等于把 Transformer 实现完一遍。
系列位置	i17，紧跟 i16，是其最佳伴读材料

Ilya 为什么选它

读懂论文和写出实现，中间隔着一条河。i16 讲清楚了 Transformer 的想法，这份教程把想法摊开成一行行能跑的程序，让「看懂」变成「跑通」。书单把它排在 i16 正后方，用意很明显：想法讲完，立刻看它怎么落地。

更值得学的是它示范的一种读论文姿态——「论文即程序」：论文里的每一句话，原则上都应该能落成一小段程序；如果落不成，多半说明还没真读懂。这种读法不挑论文、不挑领域，学会一次，处处能用。书单里选一份「教学材料」和选十篇「研究论文」并列，本身就是在提醒读者：学习这件事，材料和论文一样重要。

从生活说起

学做菜有两种材料。一种是纯文字配方：「盐少许、翻炒片刻」——看的时候全懂，进了厨房全忘。另一种是菜谱视频：左边是配方文字，右边锅里正在实拍，盐下几克、翻炒几秒都看得见。文字负责讲道理，画面负责给证据，两边互相校对，想学不会都难。

The Annotated Transformer 就是 Transformer 的「菜谱视频」。页面左栏是 i16 论文的段落，旁边是与之对应的 PyTorch 代码（PyTorch 是一个流行的深度学习代码库）：讲到打分，代码里就有打分的那几行；讲到按分数取信息，代码里就有按权重混合的那几行。论文句子和程序代码并排向前推进，一页读完，配方和实操同时过了一遍。

这套形式还有一个隐藏的好处：它把「害怕代码」和「害怕论文」的两拨读者拉到了同一张桌子前。习惯读文字的人可以顺着代码验证自己有没有理解偏；习惯读代码的人可以顺着文字知道每一行「为什么存在」。菜谱和实拍缺一样都会心虚，凑齐了才敢开火。

核心思想拆解

先把形式讲清楚：整份教程按论文顺序推进，每一段论文文字旁边都贴着对应的可运行代码。从最基础的词向量，到词与词打分、分数缩放、按分取信息，再到一层的组装、多层的堆叠，最后拼出完整模型——「注释版论文」这个形式把「读论文」和「写代码」合并成了同一件事：读完即实现完，中间没有断层。

对零基础读者，这里有一个重要提醒：不必逐行学会每个细节，更不必先啃完整本编程书再来。重点只有一件事——亲眼看到「论文里的每句话都能落成一小段程序」。这句话一旦在脑子里成立，论文就不再是天书，而是一份还没写完的代码说明书；反过来，代码也不再是魔法，而是论文句子的逐句翻译。看懂这种对应关系，比记住任何一行代码都值钱。

和 i16 的配套关系也很直白：i16 负责把注意力讲到直觉上通，这份教程负责把它落到程序上。推荐的学习顺序是先读 i16 建立画面，再来这里看画面如何变成代码，两篇算同一套教材的上下册；读完还想往系统层面走，可以接着看本站的 f01 深度解读。

动手算一算

论文里一句「每个词对所有词打分，按分数取信息」，落到代码里大约就是三步。用最小的数字走一遍：假设某词对三个候选词打分，得 4、2、1。第一步打分完成。第二步算占比：4+2+1=7，三个候选各占 4÷7≈57%、2÷7≈29%、1÷7≈14%。

第三步取信息：设三个候选词各带一个信息值 10、20、30，混合结果就是 10×57% + 20×29% + 30×14% ≈ 5.7 + 5.8 + 4.2 = 15.7。看，代码里那些看似神秘的运算，拆开就是打分、算占比、加权混合三步小学算术。Annotated Transformer 的价值，就是让你在真实代码里一眼认出这三步分别住在哪几行——从此代码不再是黑箱，而是这段算术的加长版。

它改变了什么

这份教程改变了很多人读论文的方式：把「实现一个模型」从高门槛的专项工程，变成一场跟着走的逐行讲解。此后「逐行注解」「从零实现」成了社区里常见的学习格式，源头示范正是这篇。对书单来说，它是 i16 的最佳伴读，也是「学论文先学实现」这个主张的最佳证据。

系列内相关阅读：它注解的原论文是 i16 Attention Is All You Need；注意力更早的形态见 i15 注意力机器翻译；系统视角的延伸阅读见 f01 深度解读。

术语小词典

i17 术语小词典
术语	白话解释
逐行注解（Annotated）	把原文切成小段，每段旁边配上对应的代码与说明，边读边对照。
PyTorch	一个流行的深度学习代码库，本教程用它写出可运行的 Transformer。
论文即程序	一种读法：论文每句话都应能落成一小段程序，落不成说明没读懂。
可运行代码（Runnable Code）	能直接跑起来、看到结果的代码，与纸上伪代码相对。
从零实现	不依赖现成模型包，按论文一步步把模型搭出来的学习方式。

原文与代码

教程原文：The Annotated Transformer（Harvard NLP）——http://nlp.seas.harvard.edu/annotated-transformer/
代码仓库：harvardnlp/annotated-transformer——https://github.com/harvardnlp/annotated-transformer/
配套论文解读：i16 Attention Is All You Need——i16-attention-is-all-you-need.html