@2026__30papers__The Annotated Transformer

# The Annotated Transformer（30papers） ## 位置づけ 30papersは本記事を、Transformer原論文を「動作する読みやすいコード」へ変換した行単位の実行可能な再実装と紹介する。個別ページはHarvard NLPの現行記事をほぼ全文再掲し、Transformer、自己アテンション、マルチヘッドアテンション、エンコーダ、マスキング、位置符号化、ラベル平滑化などに初学者向け説明への導線を付ける。科学的主張の一次出典はTransformer原論文であり、本記事の独自価値は数式・文章・PyTorch実装・実行例の対応づけにある。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]]) ## 著者と版 30papersのカードは「Sasha Rush and others (Harvard NLP)・2018」と表示する。本文は2018年の[[Sasha Rush]]原版を、Austin Huang、Suraj Subramanian、Jonathan Sum、Khalid Almubarak、Stella Bidermanが更新したv2022である。現行版は原論文の一部節を並べ替え・削除し、注釈と実行可能コードを追加したと自己説明する。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], [Harvard NLP現行版](https://nlp.seas.harvard.edu/annotated-transformer/)) > [!note] 書誌年と現行版 > 2018年はSasha Rush原版の公開年であり、30papersが再掲する本文の著者表示はv2022の共同更新者を含む。原版の年と現行版の著者集合を同じ版の書誌情報として混同しない。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]]) ## 文書構成記事は三部構成である。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]]) 1. モデルアーキテクチャ: エンコーダ・デコーダ、自己アテンション、位置ごとのフィードフォワード層、埋め込み、位置符号化、モデル全体の組み立て。 2. モデル訓練: バッチとマスク、訓練ループ、学習率スケジュール、ラベル平滑化、合成コピー課題。 3. 実世界例: Multi30k独英翻訳、PyTorch DDP、復号、BPE・探索・チェックポイント平均、アテンション可視化。 ## アーキテクチャをコードへ写す ### 全体構造 `EncoderDecoder`はエンコーダ、デコーダ、入力・出力埋め込み、出力生成器を統合する。`encode`と`decode`を分け、デコーダへエンコーダ出力と両側のマスクを渡すことで、原論文のデータフローをクラス境界へ写す。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `EncoderDecoder`) `clones`は`copy.deepcopy`で同一構造の層を複製する。`Encoder`と`Decoder`は層を順に適用し、スタック末尾で正規化する。`EncoderLayer`は自己アテンションとフィードフォワード層、`DecoderLayer`はマスク付き自己アテンション、入力系列へのアテンション、フィードフォワード層を持つ。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `clones`, `Encoder`, `Decoder`, `EncoderLayer`, `DecoderLayer`) ### アテンション `attention`は次式をほぼ直接実装する。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `attention`) $ \mathrm{Attention}(Q,K,V)=\mathrm{softmax}\left(\frac{QK^\top}{\sqrt{d_k}}\right)V $ マスク対象を`-1e9`で埋め、softmax後に任意のドロップアウトを適用する。`MultiHeadedAttention`はQ/K/Vを`(batch, head, sequence, d_k)`へ変形し、全ヘッドを一括計算してから連結・最終線形射影する。`d_model`がヘッド数で割り切れることをassertで保証する。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `attention`, `MultiHeadedAttention`) ### フィードフォワード層と位置符号化 `PositionwiseFeedForward`は`Linear(d_model,d_ff)`、ReLU、ドロップアウト、`Linear(d_ff,d_model)`からなる。`PositionalEncoding`は正弦・余弦の値を最大長5000まで事前計算し、学習対象外のバッファとして登録する。`make_model`は既定で6層、`d_model=512`、`d_ff=2048`、8ヘッドを組み立て、Xavier一様分布で重みを初期化する。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `PositionwiseFeedForward`, `PositionalEncoding`, `make_model`) ## 原論文と一致しない正規化位置原論文の本文はサブレイヤー出力を`LayerNorm(x + Sublayer(x))`とするpost-norm構成である。これに対し注釈版の`SublayerConnection.forward`は`x + dropout(sublayer(norm(x)))`であり、正規化をサブレイヤー入力へ移したpre-norm構成である。コードコメントも「簡潔さのため、原論文と逆に正規化を先にした」と明記する。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `SublayerConnection`; [[@2017__NeurIPS__Attention Is All You Need]] §3.1) > [!contradiction] 「行単位の再実装」と正規化位置 > 30papersは本記事を原論文の行単位の再実装と紹介するが、残差・正規化部分は原論文のpost-normを逐語的に実装せず、pre-normへ意図的に変更している。記事自身が差を注記しているため誤りではないが、「完全な再現実装」ではなく教育用の変種として読む必要がある。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `SublayerConnection`; [[@2017__NeurIPS__Attention Is All You Need]] §3.1) ## マスキング `subsequent_mask`は上三角行列を使い、各出力位置から未来の位置を見えなくする。`Batch`はパディングマスクと未来マスクを論理積で結合し、教師系列を入力側`[:, :-1]`と正解側`[:, 1:]`へ1位置ずらす。数式上の因果制約が、形状とブール演算として確認できる点が注釈版の教育的価値である。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `subsequent_mask`, `Batch`) ## 訓練手続き `run_epoch`は順伝播、正規化済み損失、逆伝播、勾配蓄積、最適化、学習率更新を統合する。学習率関数`rate`は原論文のウォームアップ後逆平方根減衰を実装し、ステップ0では負冪を避けるため1へ置き換える。`LabelSmoothing`はKLダイバージェンスを用い、パディングを除く誤答語へ平滑化確率を分配する。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `run_epoch`, `rate`, `LabelSmoothing`) 合成コピー課題は語彙11、2層モデル、20エポックの小さな例で、モデル構築・訓練・貪欲復号を最短経路で確認する。重い例はコメントアウトされており、ページを上から実行するだけで全結果を必ず再生成する設計ではない。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `example_simple_model`) ## Multi30k独英翻訳実世界例はtorchtextとspaCyでMulti30kを読み、独英語彙を構築する。データローダは固定最大長へパディングし、分散時は`DistributedSampler`とPyTorch DDPを使う。既定設定は8エポック、勾配蓄積10、最大長72、ウォームアップ3000である。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], `create_dataloaders`, `train_worker`, `load_trained_model`) BPE、共有埋め込み、ビーム探索、チェックポイント平均は完全な本文内実装から外し、OpenNMT-py等へ委ねる。これらを含むOpenNMT-py再現はWMT英独BLEU 26.9と記され、原論文大型モデルの28.4とは実装・条件の異なる値である。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], “Additional Components”, “Results”) ## アテンション可視化学習済みモデルからエンコーダ自己アテンション、デコーダ自己アテンション、デコーダ・入力間アテンションを取り出し、Altairで層・ヘッド別の行列図を生成する。原典ページでは2026-07-28時点でVegaスクリプトの読込失敗が表示され、一部のインタラクティブ図は描画されなかった。30papersの取得可能な画像は一般的なヒーロー画像だけで、本文図は動的・data URI形式だったため、取り込み規約に従い画像ファイルを採用しなかった。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], “Attention Visualization”) ## その他の不整合 > [!contradiction] 英仏BLEU > 注釈版が転載する原論文の結果節は英仏BLEUを41.0と記す。一方、原論文概要と表2の主要値は41.8である。この数値差は[[@2026__30papers__Attention Is All You Need]]と[[@2017__NeurIPS__Attention Is All You Need]]でも記録済みであり、注釈版は本文側の41.0を保持している。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]], “Results”; [[@2017__NeurIPS__Attention Is All You Need]] 概要, §6.1, 表2) > [!warning] 用語説明のラベル > 30papersでは表示語`residual connection`の説明ボタンが`What is "layer normalization"?`を指す。残差接続とレイヤー正規化は原論文でも別概念であり、用語導線の対応誤りとみられる。(Source: [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]]) ## 関連 - [[@2017__NeurIPS__Attention Is All You Need]] — 原論文 - [[@2026__30papers__Attention Is All You Need]] — 30papersによる原論文再掲 - [[Transformer]] - [[Sasha Rush]] - [[Harvard University]] - [30papers掲載ページ](https://30papers.com/papers/annotated-transformer/) - [Harvard NLP現行版](https://nlp.seas.harvard.edu/annotated-transformer/) - [2018年原版](https://nlp.seas.harvard.edu/2018/04/03/attention.html) - [実装リポジトリ](https://github.com/harvardnlp/annotated-transformer/) ## 出典 - [[.raw/articles/30papers-annotated-transformer-2026-07-28.md]] - [[@2017__NeurIPS__Attention Is All You Need]]