1. 从论文公式到可运行代码为什么单层 self-attention 值得先跑通《Attention is all you need》这篇论文里最容易被读过去、但动手时最容易卡住的其实是 multi-head attention 的维度拆分与拼接逻辑。论文公式写得很干净把 Q、K、V 各自投影到低维做 h 次 scaled dot-product attention再把 h 个 head 的输出 concat 起来最后过一层线性投影回到 d_model。但真正落到代码里问题就来了——投影后的维度到底是多少head 之间怎么切分concat 之后为什么还能和残差连接对上这篇内容聚焦一个最小切口只复现 encoder 的单层 self-attention不碰 decoder、不碰 masked attention、不碰位置编码的完整实现先把 multi-head attention 的维度流转跑通。适合已经读过论文、但还没亲手验证过 attention 权重形状的读者。我会用 TaoToken 统一 Key 作为模型调用通道在本地脚本里完成一次 attention 权重形状校验把论文里的公式变成可打印、可断点、可对照的中间结果。核心检索词先摆出来transformer、attention、self-attention、multi-head attention、encoder。这几个词在论文里反复出现但真正动手时你需要的是能跑的最小验证而不是再读一遍公式。下面从环境准备开始一步步把 config.toml、环境变量读取、attention 形状校验串起来。2. TaoToken 前置统一 Key 与 API 通道准备在开始写 attention 代码之前先把模型调用通道准备好。TaoToken 在这里的角色是统一 Key 和 API 入口让你在本地脚本里通过一个稳定的通道调用模型用来做辅助验证和结果对照。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你需要先拿到 API Key。进入控制台创建 Key 的路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完成后在 API Keys 页面复制你的 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。这个 Key 后面会通过环境变量读取不写死在代码里。如果你只是想先验证模型对话是否通可以直接用模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。但本篇的重点是本地 attention 实验所以模型调用只作为辅助校验核心还是 PyTorch 里的张量形状。注意API Key 不要提交到 Git也不要写在 config.toml 里明文保存。推荐用环境变量注入config.toml 只放非敏感配置。3. 可复制配置config.toml 骨架与环境变量读取先建一个最小项目目录结构如下attention-min/ ├── config.toml ├── .env ├── attention.py └── check_shape.pyconfig.toml 只放模型参数和 API 基础配置不放 Key[model] d_model 512 n_heads 8 d_k 64 d_v 64 dropout 0.1 [api] base_url https://taotoken.net/api model_name gpt-4o-mini timeout 30 [env] key_name TAOTOKEN_API_KEY这里 d_model512、n_heads8、d_kd_v64正好对应论文里的设置512 / 8 64。这个除法关系是后面形状校验的关键。环境变量读取用 python-dotenv.env 文件只写一行TAOTOKEN_API_KEY你的Key读取代码import os import tomllib from dotenv import load_dotenv load_dotenv() with open(config.toml, rb) as f: cfg tomllib.load(f) api_key os.getenv(cfg[env][key_name]) assert api_key, TAOTOKEN_API_KEY 未设置 d_model cfg[model][d_model] n_heads cfg[model][n_heads] d_k cfg[model][d_k] d_v cfg[model][d_v] print(fd_model{d_model}, n_heads{n_heads}, d_k{d_k}, d_v{d_v}) print(fd_model / n_heads {d_model / n_heads})运行后应该输出d_model512, n_heads8, d_k64, d_v64 d_model / n_heads 64.0这一步确认了论文里的维度关系每个 head 的投影维度等于 d_model 除以 head 数。如果这个除法不是整数后面的 reshape 就会出问题。4. 最小 self-attention 实现与形状校验现在写核心的 multi-head attention。先不引入位置编码和残差只做 Q、K、V 投影、分头、scaled dot-product、concat、输出投影。import torch import torch.nn as nn import math class MultiHeadAttention(nn.Module): def __init__(self, d_model, n_heads, d_k, d_v, dropout0.1): super().__init__() self.d_model d_model self.n_heads n_heads self.d_k d_k self.d_v d_v self.w_q nn.Linear(d_model, n_heads * d_k) self.w_k nn.Linear(d_model, n_heads * d_k) self.w_v nn.Linear(d_model, n_heads * d_v) self.w_o nn.Linear(n_heads * d_v, d_model) self.dropout nn.Dropout(dropout) def forward(self, x): batch_size, seq_len, _ x.shape q self.w_q(x) k self.w_k(x) v self.w_v(x) q q.view(batch_size, seq_len, self.n_heads, self.d_k).transpose(1, 2) k k.view(batch_size, seq_len, self.n_heads, self.d_k).transpose(1, 2) v v.view(batch_size, seq_len, self.n_heads, self.d_v).transpose(1, 2) scores torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(self.d_k) attn torch.softmax(scores, dim-1) attn self.dropout(attn) out torch.matmul(attn, v) out out.transpose(1, 2).contiguous().view(batch_size, seq_len, self.n_heads * self.d_v) out self.w_o(out) return out, attn关键形状变化用表格对照阶段张量形状说明输入 x(B, L, d_model)Bbatch, L序列长度q/k/v 投影后(B, L, n_heads * d_k)线性层输出view transpose(B, n_heads, L, d_k)分头scores(B, n_heads, L, L)QK^T / sqrt(d_k)attn(B, n_heads, L, L)softmax 后out(B, n_heads, L, d_v)attn Vconcat 后(B, L, n_heads * d_v)transpose view最终输出(B, L, d_model)w_o 投影写一个校验脚本from attention import MultiHeadAttention mha MultiHeadAttention(d_model512, n_heads8, d_k64, d_v64) x torch.randn(2, 10, 512) out, attn mha(x) print(输入形状:, x.shape) print(输出形状:, out.shape) print(attention 权重形状:, attn.shape) print(每个 head 的 d_k:, 512 // 8)预期输出输入形状: torch.Size([2, 10, 512]) 输出形状: torch.Size([2, 10, 512]) attention 权重形状: torch.Size([2, 8, 10, 10]) 每个 head 的 d_k: 64这里 attention 权重形状 (2, 8, 10, 10) 就是校验重点batch2、head8、序列长度10每个 head 都有一个 10x10 的注意力矩阵。如果你把 n_heads 改成 4d_k 就应该变成 128attention 形状变成 (2, 4, 10, 10)。这个对照能帮你确认维度拆分逻辑是否正确。5. 验证请求用 TaoToken 通道做一次结果对照本地形状校验通过后可以用 TaoToken 的 API 通道做一次辅助验证。目的不是让模型算 attention而是确认你的 Key 和通道可用同时可以问模型一个关于 multi-head attention 维度的问题对照你自己的理解。import os import tomllib from dotenv import load_dotenv from openai import OpenAI load_dotenv() with open(config.toml, rb) as f: cfg tomllib.load(f) client OpenAI( api_keyos.getenv(cfg[env][key_name]), base_urlcfg[api][base_url] ) resp client.chat.completions.create( modelcfg[api][model_name], messages[ {role: user, content: multi-head attention 中 d_model512, n_heads8, 每个 head 的 d_k 是多少} ], timeoutcfg[api][timeout] ) print(resp.choices[0].message.content)成功时会返回类似“每个 head 的 d_k 512 / 8 64”的内容。这一步的意义是你的 API 通道通了后面如果要做更复杂的对照实验可以直接复用这个 client。如果你更想直接在网页上验证模型对话可以用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。如果你打算长期做编码类实验可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 本篇常见错排查形状不匹配view 报错最常见的是view(batch_size, seq_len, n_heads, d_k)时报错原因通常是n_heads * d_k ! d_model。检查 config.toml 里这三个值是否满足乘法关系。如果你改了 n_heads 但没改 d_k就会在这里炸。transpose 后忘记 contiguousout.transpose(1, 2).contiguous().view(...)里的 contiguous 不能省。transpose 后张量在内存里不连续直接 view 会报错。这是 PyTorch 里非常经典的坑。attention 权重形状对不上如果你期望 (B, n_heads, L, L) 但拿到 (B, L, n_heads, L)说明 transpose 顺序错了。检查是不是在 scores 计算前就做了 transpose而不是在 view 之后。API 调用返回 401检查 .env 里的 Key 是否和 config.toml 里的 key_name 一致以及 load_dotenv 是否在读取环境变量之前执行。另外确认 base_url 是 https://taotoken.net/api 不要多加路径。softmax 维度写错torch.softmax(scores, dim-1)是对最后一维做归一化也就是对 key 维度。如果写成 dim-2注意力权重就不对了。这个错误不会报形状错但数值会完全错建议打印 attn.sum(-1) 确认每行和为 1。d_k 和 d_v 混用论文里 d_k 和 d_v 可以不同但本篇为了最小验证设成相等。如果你改成不等注意 scores 用 d_k 缩放concat 时用 d_v 拼接w_o 的输入维度是 n_heads * d_v。7. 继续深入的方向与通道选择单层 self-attention 跑通后下一步可以加位置编码、加残差和 LayerNorm、堆叠多层 encoder再往后才是 decoder 的 masked multi-head attention。每一步都建议先做形状校验再跑数值。论文里的公式看起来对称但代码里的 transpose、view、contiguous 顺序一旦错了形状可能对但语义不对。如果你在接入过程中遇到 Key 或通道问题优先看 API Keys 页面和接入文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 、https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你要长期做编码类实验Coding Plan 会更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。只想快速验证模型对话就用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。最后留一个实用技巧每次改完 n_heads 或 d_model先跑一遍形状校验脚本把 attention 权重形状打印出来对照 (B, n_heads, L, L) 这个目标。形状对了再去看数值和梯度。这样能把大部分维度拆分与拼接的坑挡在调试早期。