封面圖

日期:2026-08-24
適合讀者:研究生、科研新人、希望真正理解 Transformer 代碼的工程讀者
檢索日期:2026-08-24

摘要

很多人第一次接觸 Transformer,是從 nn.TransformerEncoderLayer、BERT 或 Hugging Face 模型開始的:幾行代碼就能得到輸出,卻不容易說清每一維張量為何這樣變化,padding mask 究竟屏蔽誰,殘差連接與 LayerNorm 的順序又為何影響訓練穩定性。

本文不復現原論文在 WMT 機器翻譯上的完整結果,而是完成一個更小、也更適合作為科研起點的目標:只使用 PyTorch 的基礎張量運算和 nn.Linear,實現一個可讀的 Transformer Encoder,包括正弦位置編碼、多頭自注意力、前饋網絡、殘差連接、LayerNorm、padding mask、參數初始化與最小測試。配套腳本還設計了一個“判斷序列首尾 token 是否相同”的合成任務,用來檢查模型是否能建立跨位置關係。

需要先說明證據邊界:當前工作區的 Python 環境沒有安裝 PyTorch,因此本文附帶的腳本已通過語法檢查,但 CPU 訓練與數值結果尚未實際運行,相關輸出應在安裝依賴後人工核驗。本文不會把預期現象寫成實測結論。

目錄

  1. 為什麼要從零復現 Encoder
  2. 原論文中的 Encoder 到底包含什麼
  3. 從公式到張量形狀
  4. 最小 PyTorch 實現怎麼讀
  5. 最小實驗與驗收標準
  6. 與 PyTorch 官方實現對照
  7. 最容易踩的復現陷阱
  8. 可以繼續研究的問題
  9. 總結與參考資料

為什麼要從零復現 Encoder

“會調用 Transformer”和“理解 Transformer”之間,差的往往不是更多公式,而是把公式、張量和代碼逐項對齊的能力。研究生做論文復現時,真正消耗時間的通常不是寫出 model(x),而是回答這些細節:輸入是 [batch, length, hidden] 還是 [length, batch, hidden]?mask 中的 True 表示保留還是屏蔽?多頭拆分後為什麼要 transpose?殘差分支加的是歸一化前還是歸一化後的表示?為什麼輸出形狀正確,loss 卻一直是 nan?

從零實現一個 Encoder 的價值,是建立一份可檢查的“結構賬本”。每個模塊都應有輸入形狀、輸出形狀、數學含義和不變量。這樣再閱讀 BERT、Vision Transformer、CLIP 或多模態模型時,看到的就不再是一組陌生類名,而是同一基本結構在位置編碼、歸一化、激活函數和注意力模式上的變體。

這也決定了本文的復現邊界。原始 Transformer 是編碼器-解碼器機器翻譯系統,論文的 WMT 結果依賴數據處理、訓練預算、學習率調度、label smoothing、beam search 和 checkpoint averaging。一個本地小腳本不可能證明這些結果。我們只復現 Encoder 的計算圖與關鍵不變量,把“大結果復現”拆成可驗證的第一步。

原論文中的 Encoder 到底包含什麼

2017 年的《Attention Is All You Need》用自注意力替代循環網絡和卷積,讓一個序列中的所有位置可以並行計算。原論文的 Encoder 由 N 個相同結構的層堆疊而成,每層包含兩個子層:Multi-Head Self-Attention 和 Position-wise Feed-Forward Network。每個子層外都有殘差連接與 LayerNorm。

對輸入 token 序列,最底部先查 embedding,再乘以 sqrt(d_model),隨後加上同維度的位置編碼。位置編碼是必要的,因為自注意力本身只根據內容計算 token 間關係;如果交換兩個 token,同時交換對應的 Q、K、V,純注意力不會自動知道順序發生了變化。

原論文使用正弦和餘弦函數構造固定位置編碼:

PE(pos,2i)=sin⁡(pos/100002i/dmodel)PE(pos, 2i)=\sin\left(pos/10000^{2i/d_{model}}\right)
PE(pos,2i+1)=cos⁡(pos/100002i/dmodel)PE(pos, 2i+1)=\cos\left(pos/10000^{2i/d_{model}}\right)

偶數維和奇數維使用不同相位,不同維度對應不同頻率。實現時最重要的不是背公式,而是確認 PE 的形狀可廣播到 [B,T,d_model],並作為 buffer 跟隨模型移動設備,卻不參與梯度更新。

Encoder 輸出仍然是長度為 T 的序列表示,而不是一個分類結果。每個位置都已通過自注意力融合全序列信息。BERT 後來把這種雙向 Encoder 表示用於預訓練,再針對分類、問答等任務增加輸出頭;這也是“Encoder 不是隻為機器翻譯服務”的典型例子。

Transformer Encoder 計算流程

從公式到張量形狀

1. Scaled Dot-Product Attention

注意力的核心公式是:

Attention(Q,K,V)=softmax(QKTdk+M)VAttention(Q,K,V)=softmax\left(\frac{QK^T}{\sqrt{d_k}}+M\right)V

若輸入 x 為 [B,T,d_model],先通過線性映射得到 Q、K、V。拆成 h 個頭後,三者形狀都變為 [B,h,T,d_head],其中 d_head=d_model/h。因此 d_model 必須能被頭數整除。

Q @ K.transpose(-2,-1) 得到 [B,h,T,T]。前一個 T 表示“哪個 Query 正在提問”,後一個 T 表示“它能查看哪些 Key”。除以 sqrt(d_head) 是為了控制點積方差;維度增大時,未經縮放的分數容易進入 softmax 的飽和區,梯度會變得不友好。

mask 應在 softmax 前作用於 score。對 padding mask,True 通常表示對應 Key 是填充位置,需把該列 score 設成一個極小值。這裡尤其容易寫反:屏蔽的是 Key 維,也就是 [B,1,1,T] 廣播到所有頭和所有 Query,而不是隨手把輸出位置清零。PyTorch 官方 MultiheadAttention 文檔同樣規定,二值 key_padding_mask 中的 True 表示忽略該 Key。

2. Multi-Head 的意義

單頭注意力只在一個投影空間內計算關係。多頭注意力讓不同頭擁有獨立的 Q、K、V 子空間,再把各頭結果拼回 [B,T,d_model],最後通過輸出投影 W^O 混合。

MultiHead(Q,K,V)=Concat(head1,…,headh)WOMultiHead(Q,K,V)=Concat(head_1,\ldots,head_h)W^O

這不意味著每個頭必然學出人類可命名的語言學關係。注意力權重可以用於診斷,但“某個頭看向某個 token”不能直接等同於因果解釋。下一篇的 Attention 可視化會專門討論這一邊界。

3. Position-wise FFN

前饋網絡獨立作用於每個位置:

FFN(x)=max⁡(0,xW1+b1)W2+b2FFN(x)=\max(0,xW_1+b_1)W_2+b_2

它先把 d_model 擴展到 d_ff,經過 ReLU,再投影回 d_model。注意力負責跨位置混合,FFN 負責對每個位置做非線性特徵變換。兩者分工不同,不能因為“attention is all you need”就刪掉 FFN。

4. 殘差與 LayerNorm

原論文寫法是 LayerNorm(x + Sublayer(x)),即 Post-LN。PyTorch 的 TransformerEncoderLayer 默認 norm_first=False,也對應先做子層與殘差,再歸一化;設置 norm_first=True 則變為 Pre-LN。後續研究表明,兩種順序會改變深層 Transformer 的梯度行為和 warm-up 需求。因此復現時必須把歸一化順序視為實驗變量,不能只看模塊是否都存在。

最小 PyTorch 實現怎麼讀

配套腳本位於 code/minimal_transformer_encoder.py。建議不要從 main() 開始,而按以下路徑閱讀。

第一步看 MultiHeadSelfAttention.forward()。重點追蹤 QKV 合併投影、view、permute、score 矩陣、mask 廣播、softmax、各頭拼接這七個動作。只要其中一次維度交換錯了,代碼可能仍能運行,卻把 batch、head 或 sequence 的語義混在一起。

第二步看 EncoderLayer.forward()。腳本同時保留 Post-LN 和 Pre-LN 兩條路徑,默認使用原論文式 Post-LN。這裡應明確殘差分支中的 x 指向哪一階段,避免無意中把 norm(x) 與未歸一化的殘差相加。

第三步看 TransformerEncoder.forward()。它完成 embedding 縮放、位置編碼和 N 層堆疊。這裡用 ModuleList 創建獨立層,而不是重複引用同一個 layer 對象;否則看起來堆疊了 N 層,實際卻共享全部參數。

第四步看 run_invariant_checks()。它不檢查“模型聰不聰明”,只檢查更基礎、也更可靠的事實:輸出是否為 [2,5,64],每層注意力是否為 [2,4,5,5],softmax 後每行是否求和為 1,被 padding mask 屏蔽的 Key 概率是否為 0。復現項目應先通過這些不變量,再談訓練曲線。

最小實驗與驗收標準

安裝依賴後,可先只運行結構檢查:

python3 -m pip install -r code/requirements.txt
python3 code/minimal_transformer_encoder.py --check-only

再運行合成任務:

python3 code/minimal_transformer_encoder.py --steps 80 --seed 7

任務隨機生成長度為 12 的 token 序列,並平衡構造兩類樣本:正類的首 token 與尾 token 相同,負類則確保兩者不同。分類頭只讀取第一個位置的 Encoder 表示,因此模型若要利用最後一個 token,必須通過層內信息交互把遠端信息傳回首位置。這個任務不是 benchmark,也不能證明實現等價於原論文訓練系統;它只是一個便宜的端到端連通性檢查。

建議把驗收分成四層。

層級 檢查內容 失敗時優先排查
結構 所有張量形狀與頭數一致 view、permute、d_model % n_heads
數值 loss、梯度和 attention 無 nan/inf mask、學習率、初始化、全 padding 行
學習 固定 seed 後 loss 有下降趨勢 標籤構造、梯度是否更新、dropout、任務是否可學
對照 與官方層在相同配置下輸出形狀和 mask 語義一致 batch_first、Pre/Post-LN、激活、bias、dropout

本次實際驗證結果是:腳本已通過 Python 語法編譯;當前環境因缺少 torch,未執行結構斷言和訓練循環。安裝依賴後,首先應運行 --check-only,再觀察 toy loss,而不是直接引用一個未經運行的準確率。

與 PyTorch 官方實現對照

PyTorch 官方 TransformerEncoderLayer 明確由 self-attention 和 feed-forward network 構成,並提供 d_model、nhead、dim_feedforward、dropout、activation、batch_first 與 norm_first 等參數。把本文實現與官方層逐項對照,可以得到一張最實用的閱讀表。

本文模塊 PyTorch 官方對應 需要核對的語義
MultiHeadSelfAttention nn.MultiheadAttention 輸入佈局、mask 中 True 的含義、是否返回每個 head 權重
EncoderLayer nn.TransformerEncoderLayer Post-LN / Pre-LN、激活函數、dropout 位置
ModuleList[layers] nn.TransformerEncoder 層數、參數是否獨立、最終 norm
手寫 attention 公式 scaled_dot_product_attention 數值穩定性、融合 kernel、mask 類型

手寫版本適合學習和插樁,不適合直接替代生產實現。PyTorch 當前教程建議用 scaled_dot_product_attention、Nested Tensor、torch.compile() 和 FlexAttention 等底層組件構建更靈活高效的層。這裡的差異不是“公式變了”,而是官方實現還要處理 kernel 調度、不同 dtype、設備、稀疏長度、編譯和性能快路徑。

最容易踩的復現陷阱

第一,忘記 embedding 縮放或位置編碼。小任務也許仍能擬合,但這已經不是原論文的輸入構造,不能把結果當成同一實現。

第二,softmax 維度寫錯。attention 應沿最後一個 Key 維歸一化。如果沿 head 或 Query 維做 softmax,輸出形狀仍完全正確,錯誤卻很隱蔽。

第三,mask 語義混亂。不同庫可能用 1 表示保留,也可能用 True 表示屏蔽。不要憑記憶轉換;先讀當前版本文檔,再寫一個兩行樣例驗證被屏蔽位置的概率確實為 0。

第四,所有 Key 都被屏蔽。若某個樣本的一行 score 全是極小值,softmax 可能產生無意義分佈,部分實現或 dtype 下還可能出現 nan。數據管線應保證至少有一個有效 token,或顯式定義空序列行為。

第五,混淆 Encoder 自注意力和 Decoder 因果注意力。Encoder 通常允許每個位置查看整個輸入,不應默認加上三角 causal mask。把 Decoder 的“不能看未來”照搬到 BERT 風格 Encoder,會悄悄改變任務定義。

第六,層複製成參數共享。[layer] * N 只是把同一個 Python 對象引用 N 次。若論文沒有明確共享參數,應為每層實例化獨立模塊。

第七,只報告最終 loss。一個可信復現還應記錄 PyTorch 版本、設備、seed、數據生成方式、參數量、訓練步數、優化器與提交版本。toy task 的成功只能說明實現具有基本學習能力,不能外推到翻譯質量、長序列能力或真實語料性能。

可以繼續研究的問題

  1. 在層數從 2 增加到 24 時,Post-LN 與 Pre-LN 的梯度範數、warm-up 需求和收斂速度如何變化?
  2. 固定參數量後,增加 head 數是否總能提升合成關係任務?當 d_head 太小時會發生什麼?
  3. 正弦位置編碼、可學習絕對位置編碼、RoPE 與 ALiBi 在長度外推上的差異,如何用可控數據驗證?
  4. 手寫 attention 與 PyTorch scaled_dot_product_attention 在 CPU、CUDA、不同 dtype 下的數值誤差與速度差異多大?
  5. padding mask、causal mask 和任意稀疏 mask 能否統一為一個經過單元測試的接口?
  6. 注意力權重與模型預測之間是否具有因果關係?遮蔽高權重連接後,輸出變化是否真的更大?

這些問題都適合從本文腳本擴展。研究價值不在於再造一個更大的 Transformer,而在於把一個變量、一個假設和一個測量協議說清楚。

總結

復現 Transformer Encoder 的第一步,不是追求與原論文相同的 BLEU,而是建立公式、張量、代碼和測試之間的對應關係:QKV 如何拆頭,score 為什麼除以 sqrt(d_head),mask 在哪個維度生效,注意力後為何還需要 FFN,殘差與 LayerNorm 的順序又如何成為可研究變量。

本文的最小實現刻意保留可讀性,並用形狀、概率和 mask 不變量約束正確性。它已經完成靜態語法驗證,但由於當前環境沒有 PyTorch,運行時結果仍標註為待人工核驗。這樣的邊界說明不是缺點,而是復現記錄最重要的一部分:只報告真正做過的驗證。

參考資料

檢索日期:2026-08-24。PyTorch 文檔會隨版本變化;正式復現實驗應同時記錄本地 torch.__version__、設備與提交版本。

  1. Vaswani et al., Attention Is All You Need, 2017;arXiv 當前頁面包含 2023 年修訂版本。
  2. Harvard NLP, The Annotated Transformer,帶註釋的 PyTorch 實現與 notebook。
  3. PyTorch, TransformerEncoderLayer,當前官方 API 說明。
  4. PyTorch, MultiheadAttention,輸入形狀、key_padding_mask 與 attn_mask 語義。
  5. PyTorch Tutorials, Transformer building blocks,scaled_dot_product_attention、Nested Tensor 與自定義層的當前建議。
  6. Harvard NLP, the_annotated_transformer.py,位置編碼、模型構造、初始化與訓練代碼路徑。
  7. Devlin et al., BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding, 2018。
  8. Xiong et al., On Layer Normalization in the Transformer Architecture, ICML 2020。