尧图网页设计 
1. 从论文到可运行代码Transformer Encoder-Decoder 最小实现到底难在哪《Attention Is All You Need》这篇论文我翻过很多遍每次看都觉得结构清晰但真动手写一个能跑通的 Encoder-Decoder 最小实现时问题就冒出来了。你可能也遇到过论文里公式写得明明白白Scaled Dot-Product Attention 就那几步但落到代码上张量形状对不上、mask 加错位置、位置编码维度不匹配随便一个都能卡半天。这篇内容面向的是想真正把 Transformer 核心结构跑起来的人。不是只读论文而是用尽量少的代码把 Encoder、Decoder、Scaled Dot-Product Attention 复现出来并且通过 TaoToken 统一 Key 调用模型做一次前向验证确认你的实现逻辑和真实模型的输出行为是一致的。适合已经了解 PyTorch 基础、看过论文但还没亲手搭过的读者。核心检索词先明确Transformer 最小实现、Encoder-Decoder 结构、Scaled Dot-Product Attention、TaoToken 统一 Key 调用。这几个词会贯穿全文。我试过直接用现成的 Transformer 库确实方便但调参和排障时完全不知道内部发生了什么。后来自己写了一遍最小版本才发现很多细节论文里一笔带过代码里却必须做决定。比如位置编码到底用 sin/cos 固定式还是可学习式mask 是加在 softmax 之前还是之后多头注意力的头维度怎么切分。这些决定直接影响你能不能跑通。下面我会按这个顺序展开先把论文里的核心结构拆成可编码的模块然后配置 TaoToken 的统一 Key 和 Base URL接着给出完整的可复制代码再通过一次真实请求验证输出形状和注意力权重最后把常见的报错和排查路径列清楚。每一步都有命令和参数你可以跟着操作。2. TaoToken 统一 Key 配置Base URL、API Key 与模型 ID 三件套在开始写代码之前先把调用通道配好。TaoToken 的作用是提供一个统一的 API 入口你不需要为每个模型单独管理 Key 和地址。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。你需要准备三样东西Base URL、API Key、Model ID。这三件套在后面的代码里会直接用到。Base URL 填 https://taotoken.net/api API Key 在控制台创建Model ID 根据你要验证的模型填写。创建 Key 的路径是进入控制台后找到 API Keys 页面。具体操作打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 登录后点击创建新 Key复制保存。这个 Key 只显示一次丢了就得重新建。环境变量配置我建议直接写进 shell 配置文件这样每次开终端都生效。如果你用 bash编辑 ~/.bashrc用 zsh 就编辑 ~/.zshrc。加入下面三行export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEY你的API Key export TAOTOKEN_MODEL_ID你的模型ID保存后执行 source ~/.bashrc 或 source ~/.zshrc 让配置生效。验证是否生效可以用 echo $TAOTOKEN_BASE_URL应该输出 https://taotoken.net/api 。如果你更习惯用 .env 文件管理在项目根目录建一个 .env内容如下TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEY你的API Key TAOTOKEN_MODEL_ID你的模型ID然后在 Python 里用 python-dotenv 加载。两种方式都行选你顺手的。我一般用环境变量因为切换项目时不用改代码。这里注意一点Base URL 后面不要多加斜杠也不要拼 /v1 之类的路径TaoToken 的 API 入口就是 https://taotoken.net/api 具体路径由 SDK 或请求库处理。如果你用 OpenAI 兼容的客户端base_url 参数直接填这个地址即可。Model ID 怎么选如果你只是做前向验证选一个支持文本生成的模型就行。具体可用模型列表在文档里查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里会列出当前支持的模型和对应的 ID 格式。配置完成后你可以先用一个最简单的 curl 请求测试通道是否通curl -X POST $TAOTOKEN_BASE_URL/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL_ID, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回 JSON 里有 choices 字段说明通道正常。如果报 401检查 Key 是否复制完整如果报连接错误检查 Base URL 是否写对。这一步过了再往下走。3. 可复制配置与代码清单Encoder、Decoder、Attention 逐段实现这一节是全文的核心我会把 Transformer 最小实现的代码逐段列出来。你新建一个 Python 文件比如 transformer_minimal.py然后按顺序粘贴。依赖只需要 torch安装命令pip install torch numpy如果你要用 TaoToken 做验证再加一个 requests 或 openaipip install openai先定义超参数。d_model512 是论文里的标准值但为了跑得快你可以先用 64 或 128 测试。头数 n_heads8d_ff2048层数 N6。这些参数在代码开头集中定义方便调整。import torch import torch.nn as nn import torch.nn.functional as F import math d_model 64 n_heads 8 d_ff 256 n_layers 2 dropout 0.1 max_len 100注意 d_model 必须能被 n_heads 整除否则多头切分时会报错。64/88每个头 8 维没问题。接下来是 Scaled Dot-Product Attention。论文里的公式是 Attention(Q,K,V) softmax(QK^T / sqrt(d_k)) V。代码实现时要注意 mask 的处理mask 为 True 的位置填 -infsoftmax 后变成 0。def scaled_dot_product_attention(q, k, v, maskNone): d_k q.size(-1) scores torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(d_k) if mask is not None: scores scores.masked_fill(mask 0, float(-inf)) attn F.softmax(scores, dim-1) output torch.matmul(attn, v) return output, attn这里 q、k、v 的形状是 [batch, n_heads, seq_len, d_k]。mask 的形状要能广播到 scores 上通常是 [batch, 1, 1, seq_len] 或 [batch, 1, seq_len, seq_len]。多头注意力就是把上面的单头并行跑多次再拼接。关键步骤先做线性变换得到 Q、K、V然后 reshape 成多头跑 attention再 reshape 回来最后过一个输出线性层。class MultiHeadAttention(nn.Module): def __init__(self, d_model, n_heads): super().__init__() self.d_model d_model self.n_heads n_heads self.d_k d_model // n_heads self.w_q nn.Linear(d_model, d_model) self.w_k nn.Linear(d_model, d_model) self.w_v nn.Linear(d_model, d_model) self.w_o nn.Linear(d_model, d_model) def forward(self, q, k, v, maskNone): batch_size q.size(0) q self.w_q(q).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) k self.w_k(k).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) v self.w_v(v).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) out, attn scaled_dot_product_attention(q, k, v, mask) out out.transpose(1, 2).contiguous().view(batch_size, -1, self.d_model) return self.w_o(out), attn位置编码用论文里的 sin/cos 固定式。注意偶数维用 sin奇数维用 cos代码里用切片实现。class PositionalEncoding(nn.Module): def __init__(self, d_model, max_len5000): super().__init__() pe torch.zeros(max_len, d_model) position torch.arange(0, max_len).unsqueeze(1).float() div_term torch.exp(torch.arange(0, d_model, 2).float() * -(math.log(10000.0) / d_model)) pe[:, 0::2] torch.sin(position * div_term) pe[:, 1::2] torch.cos(position * div_term) self.register_buffer(pe, pe.unsqueeze(0)) def forward(self, x): return x self.pe[:, :x.size(1)]Encoder 层包含两个子层多头自注意力和前馈网络每个子层后面接残差连接和层归一化。注意 LayerNorm 在 PyTorch 里的输入形状是最后一维所以要先做 norm 再做残差还是先残差再 norm不同实现有差异。论文里是 Post-LN即先子层输出再 Add再 Norm。class EncoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.attn MultiHeadAttention(d_model, n_heads) self.ff nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Linear(d_ff, d_model) ) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, maskNone): attn_out, _ self.attn(x, x, x, mask) x self.norm1(x self.dropout(attn_out)) ff_out self.ff(x) x self.norm2(x self.dropout(ff_out)) return xDecoder 层多了一个 Encoder-Decoder AttentionQ 来自解码器K 和 V 来自编码器输出。另外自注意力层要加 causal mask防止看到未来位置。class DecoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.self_attn MultiHeadAttention(d_model, n_heads) self.cross_attn MultiHeadAttention(d_model, n_heads) self.ff nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Linear(d_ff, d_model) ) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.norm3 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, enc_out, src_maskNone, tgt_maskNone): self_attn_out, _ self.self_attn(x, x, x, tgt_mask) x self.norm1(x self.dropout(self_attn_out)) cross_attn_out, _ self.cross_attn(x, enc_out, enc_out, src_mask) x self.norm2(x self.dropout(cross_attn_out)) ff_out self.ff(x) x self.norm3(x self.dropout(ff_out)) return x把 Encoder 和 Decoder 堆叠起来再加上嵌入层和位置编码就是一个完整的 Transformer。class Transformer(nn.Module): def __init__(self, src_vocab, tgt_vocab, d_model, n_heads, d_ff, n_layers, dropout0.1, max_len100): super().__init__() self.src_embed nn.Embedding(src_vocab, d_model) self.tgt_embed nn.Embedding(tgt_vocab, d_model) self.pos_enc PositionalEncoding(d_model, max_len) self.encoder_layers nn.ModuleList([EncoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(n_layers)]) self.decoder_layers nn.ModuleList([DecoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(n_layers)]) self.fc_out nn.Linear(d_model, tgt_vocab) self.dropout nn.Dropout(dropout) def forward(self, src, tgt, src_maskNone, tgt_maskNone): src self.dropout(self.pos_enc(self.src_embed(src))) for layer in self.encoder_layers: src layer(src, src_mask) tgt self.dropout(self.pos_enc(self.tgt_embed(tgt))) for layer in self.decoder_layers: tgt layer(tgt, src, src_mask, tgt_mask) return self.fc_out(tgt)生成 causal mask 的函数def generate_causal_mask(seq_len): mask torch.tril(torch.ones(seq_len, seq_len)).unsqueeze(0).unsqueeze(0) return mask到这里最小实现就完成了。你可以先跑一个随机输入测试形状model Transformer(src_vocab100, tgt_vocab100, d_model64, n_heads8, d_ff256, n_layers2) src torch.randint(0, 100, (2, 10)) tgt torch.randint(0, 100, (2, 8)) tgt_mask generate_causal_mask(8) out model(src, tgt, tgt_masktgt_mask) print(out.shape)输出应该是 torch.Size([2, 8, 100])表示 batch2目标序列长度 8词表大小 100。如果形状不对检查嵌入层和 fc_out 的维度。4. 验证请求与成功结果用 TaoToken 做前向一致性检查代码写完了怎么确认它和真实模型的行为一致我的做法是用 TaoToken 发一个请求让模型对同一段输入做前向计算然后对比输出形状和注意力权重的统计特征。注意这里不是要求模型输出和你的随机初始化模型完全一样而是验证调用通道正常、返回结构符合预期、注意力权重的分布合理。先写一个调用脚本用 OpenAI 兼容客户端from openai import OpenAI import os client OpenAI( base_urlos.getenv(TAOTOKEN_BASE_URL), api_keyos.getenv(TAOTOKEN_API_KEY) ) response client.chat.completions.create( modelos.getenv(TAOTOKEN_MODEL_ID), messages[ {role: system, content: 你是一个帮助验证 Transformer 结构的助手。}, {role: user, content: 请用一句话解释 Scaled Dot-Product Attention 的计算步骤。} ], max_tokens100, temperature0 ) print(response.choices[0].message.content)运行后如果输出一段通顺的解释说明 TaoToken 通道正常。这一步验证的是 API 连通性不是模型内部结构。如果你想进一步验证注意力权重可以在本地模型里把 attention 输出保存下来检查每一行的权重和是否为 1。model.eval() with torch.no_grad(): src torch.randint(0, 100, (1, 6)) tgt torch.randint(0, 100, (1, 4)) tgt_mask generate_causal_mask(4) out model(src, tgt, tgt_masktgt_mask) print(输出形状:, out.shape) print(输出概率和:, torch.softmax(out, dim-1).sum(dim-1))输出概率和应该接近 1.0。如果明显偏离检查 fc_out 和 softmax 的使用。另外你可以把 MultiHeadAttention 里的 attn 返回出来打印第一层的注意力矩阵观察 causal mask 是否生效上三角区域应该全是 0。attn_weights [] def hook(module, input, output): attn_weights.append(output[1]) handle model.decoder_layers[0].self_attn.register_forward_hook(hook) with torch.no_grad(): model(src, tgt, tgt_masktgt_mask) handle.remove() print(注意力权重形状:, attn_weights[0].shape) print(上三角和:, attn_weights[0].triu(diagonal1).sum().item())上三角和应该为 0说明未来位置被正确屏蔽。如果非 0检查 mask 的生成和传入位置。成功结果的标准API 返回正常文本本地模型输出形状正确注意力权重归一化且 mask 生效。这三项都过了说明你的最小实现和调用通道都没问题。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节列几个我实际遇到过的报错和排查路径。你如果卡住了可以对照着看。401 Unauthorized。这个最常见原因是 API Key 不对或没传。检查三点环境变量是否生效echo $TAOTOKEN_API_KEY 有没有输出、Key 是否复制完整有没有多余空格、请求头格式是否是 Bearer 加空格加 Key。如果用的是 OpenAI 客户端确认 api_key 参数传对了。另外注意 TaoToken 的 Key 和模型 ID 要匹配用错模型的 Key 也可能报 401。local proxy failed。这个报错通常出现在网络层提示本地代理连接失败。检查你的环境变量里有没有 http_proxy 或 https_proxy 设置如果有先 unset 掉再试。命令unset http_proxy unset https_proxy然后重新运行请求。如果还不行检查 Base URL 是否写成了 https://taotoken.net/api 而不是其他地址。注意不要在任何配置里写代理相关的参数。reading choices 相关报错。这个一般出现在解析响应时比如 response.choices 为空或结构不对。先打印完整 response 看返回了什么。常见原因是模型 ID 写错返回了错误信息而不是正常补全。检查 TAOTOKEN_MODEL_ID 是否和文档里列出的 ID 一致。另外 max_tokens 设太小也可能导致 choices 为空调大到 50 以上再试。OAuth 相关报错。如果你用的是某些需要 OAuth 的客户端可能会提示 token 过期或 scope 不对。TaoToken 的 API Key 是直接用的不需要 OAuth 流程。如果你在代码里混用了 OAuth 逻辑去掉它直接用 Bearer Token。检查请求头里不要带多余的 Authorization 字段。还有一个容易忽略的Base URL 末尾多了斜杠。比如写成 https://taotoken.net/api/ 某些客户端会拼成 //v1/chat/completions导致 404。统一写成不带末尾斜杠的形式。如果你用 Claude Code 或类似工具接入配置里需要同时填 Base URL、API Key、Model ID 三件套。缺一个都会报错。具体配置示例{ base_url: https://taotoken.net/api, api_key: 你的API Key, model: 你的模型ID }保存后重启工具再发一个测试请求。如果还报错把完整错误信息复制出来对照上面的分类排查。6. 继续深入从最小实现到可训练模型的下一步最小实现跑通之后你可以做几件事让它更接近论文里的完整模型。第一加上标签平滑和 warmup 学习率调度这两项在论文里对训练稳定性影响很大。第二把嵌入层和 fc_out 的权重共享减少参数量。第三用真实数据集跑一个小的翻译任务观察 loss 下降曲线。如果你只是想验证结构现在这个版本已经够了。注意力权重的可视化可以用 matplotlib 画热力图观察不同头关注的位置模式。我试过把 8 个头的注意力矩阵并排画出来确实能看到有的头关注相邻位置有的头关注句首。调用通道方面TaoToken 的统一 Key 省去了多模型管理的麻烦。你可以在同一个脚本里切换不同 Model ID 做对比Base URL 和 Key 不用改。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要长期做编码或 Agent 任务的可以看 Coding Plan 的额度方案。最后留一个实用技巧调试 Transformer 时先把 d_model 和层数调小比如 d_model32、n_layers1这样单步调试快很多。等结构确认无误再放大到论文参数。位置编码的 max_len 要大于你的最大序列长度否则会报索引越界。mask 的 dtype 要和 scores 一致用 float 而不是 bool避免 masked_fill 报类型错误。这些坑我都踩过你按上面的代码走应该能避开大部分。 从 Attention Is All You Need 出发：用 TaoToken 统一 Key 跑通 Transformer Encoder-Decoder 最小实现
1. 从论文到可运行代码Transformer Encoder-Decoder 最小实现到底难在哪《Attention Is All You Need》这篇论文我翻过很多遍每次看都觉得结构清晰但真动手写一个能跑通的 Encoder-Decoder 最小实现时问题就冒出来了。你可能也遇到过论文里公式写得明明白白Scaled Dot-Product Attention 就那几步但落到代码上张量形状对不上、mask 加错位置、位置编码维度不匹配随便一个都能卡半天。这篇内容面向的是想真正把 Transformer 核心结构跑起来的人。不是只读论文而是用尽量少的代码把 Encoder、Decoder、Scaled Dot-Product Attention 复现出来并且通过 TaoToken 统一 Key 调用模型做一次前向验证确认你的实现逻辑和真实模型的输出行为是一致的。适合已经了解 PyTorch 基础、看过论文但还没亲手搭过的读者。核心检索词先明确Transformer 最小实现、Encoder-Decoder 结构、Scaled Dot-Product Attention、TaoToken 统一 Key 调用。这几个词会贯穿全文。我试过直接用现成的 Transformer 库确实方便但调参和排障时完全不知道内部发生了什么。后来自己写了一遍最小版本才发现很多细节论文里一笔带过代码里却必须做决定。比如位置编码到底用 sin/cos 固定式还是可学习式mask 是加在 softmax 之前还是之后多头注意力的头维度怎么切分。这些决定直接影响你能不能跑通。下面我会按这个顺序展开先把论文里的核心结构拆成可编码的模块然后配置 TaoToken 的统一 Key 和 Base URL接着给出完整的可复制代码再通过一次真实请求验证输出形状和注意力权重最后把常见的报错和排查路径列清楚。每一步都有命令和参数你可以跟着操作。2. TaoToken 统一 Key 配置Base URL、API Key 与模型 ID 三件套在开始写代码之前先把调用通道配好。TaoToken 的作用是提供一个统一的 API 入口你不需要为每个模型单独管理 Key 和地址。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。你需要准备三样东西Base URL、API Key、Model ID。这三件套在后面的代码里会直接用到。Base URL 填 https://taotoken.net/api API Key 在控制台创建Model ID 根据你要验证的模型填写。创建 Key 的路径是进入控制台后找到 API Keys 页面。具体操作打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 登录后点击创建新 Key复制保存。这个 Key 只显示一次丢了就得重新建。环境变量配置我建议直接写进 shell 配置文件这样每次开终端都生效。如果你用 bash编辑 ~/.bashrc用 zsh 就编辑 ~/.zshrc。加入下面三行export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEY你的API Key export TAOTOKEN_MODEL_ID你的模型ID保存后执行 source ~/.bashrc 或 source ~/.zshrc 让配置生效。验证是否生效可以用 echo $TAOTOKEN_BASE_URL应该输出 https://taotoken.net/api 。如果你更习惯用 .env 文件管理在项目根目录建一个 .env内容如下TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEY你的API Key TAOTOKEN_MODEL_ID你的模型ID然后在 Python 里用 python-dotenv 加载。两种方式都行选你顺手的。我一般用环境变量因为切换项目时不用改代码。这里注意一点Base URL 后面不要多加斜杠也不要拼 /v1 之类的路径TaoToken 的 API 入口就是 https://taotoken.net/api 具体路径由 SDK 或请求库处理。如果你用 OpenAI 兼容的客户端base_url 参数直接填这个地址即可。Model ID 怎么选如果你只是做前向验证选一个支持文本生成的模型就行。具体可用模型列表在文档里查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里会列出当前支持的模型和对应的 ID 格式。配置完成后你可以先用一个最简单的 curl 请求测试通道是否通curl -X POST $TAOTOKEN_BASE_URL/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL_ID, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回 JSON 里有 choices 字段说明通道正常。如果报 401检查 Key 是否复制完整如果报连接错误检查 Base URL 是否写对。这一步过了再往下走。3. 可复制配置与代码清单Encoder、Decoder、Attention 逐段实现这一节是全文的核心我会把 Transformer 最小实现的代码逐段列出来。你新建一个 Python 文件比如 transformer_minimal.py然后按顺序粘贴。依赖只需要 torch安装命令pip install torch numpy如果你要用 TaoToken 做验证再加一个 requests 或 openaipip install openai先定义超参数。d_model512 是论文里的标准值但为了跑得快你可以先用 64 或 128 测试。头数 n_heads8d_ff2048层数 N6。这些参数在代码开头集中定义方便调整。import torch import torch.nn as nn import torch.nn.functional as F import math d_model 64 n_heads 8 d_ff 256 n_layers 2 dropout 0.1 max_len 100注意 d_model 必须能被 n_heads 整除否则多头切分时会报错。64/88每个头 8 维没问题。接下来是 Scaled Dot-Product Attention。论文里的公式是 Attention(Q,K,V) softmax(QK^T / sqrt(d_k)) V。代码实现时要注意 mask 的处理mask 为 True 的位置填 -infsoftmax 后变成 0。def scaled_dot_product_attention(q, k, v, maskNone): d_k q.size(-1) scores torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(d_k) if mask is not None: scores scores.masked_fill(mask 0, float(-inf)) attn F.softmax(scores, dim-1) output torch.matmul(attn, v) return output, attn这里 q、k、v 的形状是 [batch, n_heads, seq_len, d_k]。mask 的形状要能广播到 scores 上通常是 [batch, 1, 1, seq_len] 或 [batch, 1, seq_len, seq_len]。多头注意力就是把上面的单头并行跑多次再拼接。关键步骤先做线性变换得到 Q、K、V然后 reshape 成多头跑 attention再 reshape 回来最后过一个输出线性层。class MultiHeadAttention(nn.Module): def __init__(self, d_model, n_heads): super().__init__() self.d_model d_model self.n_heads n_heads self.d_k d_model // n_heads self.w_q nn.Linear(d_model, d_model) self.w_k nn.Linear(d_model, d_model) self.w_v nn.Linear(d_model, d_model) self.w_o nn.Linear(d_model, d_model) def forward(self, q, k, v, maskNone): batch_size q.size(0) q self.w_q(q).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) k self.w_k(k).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) v self.w_v(v).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) out, attn scaled_dot_product_attention(q, k, v, mask) out out.transpose(1, 2).contiguous().view(batch_size, -1, self.d_model) return self.w_o(out), attn位置编码用论文里的 sin/cos 固定式。注意偶数维用 sin奇数维用 cos代码里用切片实现。class PositionalEncoding(nn.Module): def __init__(self, d_model, max_len5000): super().__init__() pe torch.zeros(max_len, d_model) position torch.arange(0, max_len).unsqueeze(1).float() div_term torch.exp(torch.arange(0, d_model, 2).float() * -(math.log(10000.0) / d_model)) pe[:, 0::2] torch.sin(position * div_term) pe[:, 1::2] torch.cos(position * div_term) self.register_buffer(pe, pe.unsqueeze(0)) def forward(self, x): return x self.pe[:, :x.size(1)]Encoder 层包含两个子层多头自注意力和前馈网络每个子层后面接残差连接和层归一化。注意 LayerNorm 在 PyTorch 里的输入形状是最后一维所以要先做 norm 再做残差还是先残差再 norm不同实现有差异。论文里是 Post-LN即先子层输出再 Add再 Norm。class EncoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.attn MultiHeadAttention(d_model, n_heads) self.ff nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Linear(d_ff, d_model) ) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, maskNone): attn_out, _ self.attn(x, x, x, mask) x self.norm1(x self.dropout(attn_out)) ff_out self.ff(x) x self.norm2(x self.dropout(ff_out)) return xDecoder 层多了一个 Encoder-Decoder AttentionQ 来自解码器K 和 V 来自编码器输出。另外自注意力层要加 causal mask防止看到未来位置。class DecoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.self_attn MultiHeadAttention(d_model, n_heads) self.cross_attn MultiHeadAttention(d_model, n_heads) self.ff nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Linear(d_ff, d_model) ) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.norm3 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, enc_out, src_maskNone, tgt_maskNone): self_attn_out, _ self.self_attn(x, x, x, tgt_mask) x self.norm1(x self.dropout(self_attn_out)) cross_attn_out, _ self.cross_attn(x, enc_out, enc_out, src_mask) x self.norm2(x self.dropout(cross_attn_out)) ff_out self.ff(x) x self.norm3(x self.dropout(ff_out)) return x把 Encoder 和 Decoder 堆叠起来再加上嵌入层和位置编码就是一个完整的 Transformer。class Transformer(nn.Module): def __init__(self, src_vocab, tgt_vocab, d_model, n_heads, d_ff, n_layers, dropout0.1, max_len100): super().__init__() self.src_embed nn.Embedding(src_vocab, d_model) self.tgt_embed nn.Embedding(tgt_vocab, d_model) self.pos_enc PositionalEncoding(d_model, max_len) self.encoder_layers nn.ModuleList([EncoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(n_layers)]) self.decoder_layers nn.ModuleList([DecoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(n_layers)]) self.fc_out nn.Linear(d_model, tgt_vocab) self.dropout nn.Dropout(dropout) def forward(self, src, tgt, src_maskNone, tgt_maskNone): src self.dropout(self.pos_enc(self.src_embed(src))) for layer in self.encoder_layers: src layer(src, src_mask) tgt self.dropout(self.pos_enc(self.tgt_embed(tgt))) for layer in self.decoder_layers: tgt layer(tgt, src, src_mask, tgt_mask) return self.fc_out(tgt)生成 causal mask 的函数def generate_causal_mask(seq_len): mask torch.tril(torch.ones(seq_len, seq_len)).unsqueeze(0).unsqueeze(0) return mask到这里最小实现就完成了。你可以先跑一个随机输入测试形状model Transformer(src_vocab100, tgt_vocab100, d_model64, n_heads8, d_ff256, n_layers2) src torch.randint(0, 100, (2, 10)) tgt torch.randint(0, 100, (2, 8)) tgt_mask generate_causal_mask(8) out model(src, tgt, tgt_masktgt_mask) print(out.shape)输出应该是 torch.Size([2, 8, 100])表示 batch2目标序列长度 8词表大小 100。如果形状不对检查嵌入层和 fc_out 的维度。4. 验证请求与成功结果用 TaoToken 做前向一致性检查代码写完了怎么确认它和真实模型的行为一致我的做法是用 TaoToken 发一个请求让模型对同一段输入做前向计算然后对比输出形状和注意力权重的统计特征。注意这里不是要求模型输出和你的随机初始化模型完全一样而是验证调用通道正常、返回结构符合预期、注意力权重的分布合理。先写一个调用脚本用 OpenAI 兼容客户端from openai import OpenAI import os client OpenAI( base_urlos.getenv(TAOTOKEN_BASE_URL), api_keyos.getenv(TAOTOKEN_API_KEY) ) response client.chat.completions.create( modelos.getenv(TAOTOKEN_MODEL_ID), messages[ {role: system, content: 你是一个帮助验证 Transformer 结构的助手。}, {role: user, content: 请用一句话解释 Scaled Dot-Product Attention 的计算步骤。} ], max_tokens100, temperature0 ) print(response.choices[0].message.content)运行后如果输出一段通顺的解释说明 TaoToken 通道正常。这一步验证的是 API 连通性不是模型内部结构。如果你想进一步验证注意力权重可以在本地模型里把 attention 输出保存下来检查每一行的权重和是否为 1。model.eval() with torch.no_grad(): src torch.randint(0, 100, (1, 6)) tgt torch.randint(0, 100, (1, 4)) tgt_mask generate_causal_mask(4) out model(src, tgt, tgt_masktgt_mask) print(输出形状:, out.shape) print(输出概率和:, torch.softmax(out, dim-1).sum(dim-1))输出概率和应该接近 1.0。如果明显偏离检查 fc_out 和 softmax 的使用。另外你可以把 MultiHeadAttention 里的 attn 返回出来打印第一层的注意力矩阵观察 causal mask 是否生效上三角区域应该全是 0。attn_weights [] def hook(module, input, output): attn_weights.append(output[1]) handle model.decoder_layers[0].self_attn.register_forward_hook(hook) with torch.no_grad(): model(src, tgt, tgt_masktgt_mask) handle.remove() print(注意力权重形状:, attn_weights[0].shape) print(上三角和:, attn_weights[0].triu(diagonal1).sum().item())上三角和应该为 0说明未来位置被正确屏蔽。如果非 0检查 mask 的生成和传入位置。成功结果的标准API 返回正常文本本地模型输出形状正确注意力权重归一化且 mask 生效。这三项都过了说明你的最小实现和调用通道都没问题。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节列几个我实际遇到过的报错和排查路径。你如果卡住了可以对照着看。401 Unauthorized。这个最常见原因是 API Key 不对或没传。检查三点环境变量是否生效echo $TAOTOKEN_API_KEY 有没有输出、Key 是否复制完整有没有多余空格、请求头格式是否是 Bearer 加空格加 Key。如果用的是 OpenAI 客户端确认 api_key 参数传对了。另外注意 TaoToken 的 Key 和模型 ID 要匹配用错模型的 Key 也可能报 401。local proxy failed。这个报错通常出现在网络层提示本地代理连接失败。检查你的环境变量里有没有 http_proxy 或 https_proxy 设置如果有先 unset 掉再试。命令unset http_proxy unset https_proxy然后重新运行请求。如果还不行检查 Base URL 是否写成了 https://taotoken.net/api 而不是其他地址。注意不要在任何配置里写代理相关的参数。reading choices 相关报错。这个一般出现在解析响应时比如 response.choices 为空或结构不对。先打印完整 response 看返回了什么。常见原因是模型 ID 写错返回了错误信息而不是正常补全。检查 TAOTOKEN_MODEL_ID 是否和文档里列出的 ID 一致。另外 max_tokens 设太小也可能导致 choices 为空调大到 50 以上再试。OAuth 相关报错。如果你用的是某些需要 OAuth 的客户端可能会提示 token 过期或 scope 不对。TaoToken 的 API Key 是直接用的不需要 OAuth 流程。如果你在代码里混用了 OAuth 逻辑去掉它直接用 Bearer Token。检查请求头里不要带多余的 Authorization 字段。还有一个容易忽略的Base URL 末尾多了斜杠。比如写成 https://taotoken.net/api/ 某些客户端会拼成 //v1/chat/completions导致 404。统一写成不带末尾斜杠的形式。如果你用 Claude Code 或类似工具接入配置里需要同时填 Base URL、API Key、Model ID 三件套。缺一个都会报错。具体配置示例{ base_url: https://taotoken.net/api, api_key: 你的API Key, model: 你的模型ID }保存后重启工具再发一个测试请求。如果还报错把完整错误信息复制出来对照上面的分类排查。6. 继续深入从最小实现到可训练模型的下一步最小实现跑通之后你可以做几件事让它更接近论文里的完整模型。第一加上标签平滑和 warmup 学习率调度这两项在论文里对训练稳定性影响很大。第二把嵌入层和 fc_out 的权重共享减少参数量。第三用真实数据集跑一个小的翻译任务观察 loss 下降曲线。如果你只是想验证结构现在这个版本已经够了。注意力权重的可视化可以用 matplotlib 画热力图观察不同头关注的位置模式。我试过把 8 个头的注意力矩阵并排画出来确实能看到有的头关注相邻位置有的头关注句首。调用通道方面TaoToken 的统一 Key 省去了多模型管理的麻烦。你可以在同一个脚本里切换不同 Model ID 做对比Base URL 和 Key 不用改。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要长期做编码或 Agent 任务的可以看 Coding Plan 的额度方案。最后留一个实用技巧调试 Transformer 时先把 d_model 和层数调小比如 d_model32、n_layers1这样单步调试快很多。等结构确认无误再放大到论文参数。位置编码的 max_len 要大于你的最大序列长度否则会报索引越界。mask 的 dtype 要和 scores 一致用 float 而不是 bool避免 masked_fill 报类型错误。这些坑我都踩过你按上面的代码走应该能避开大部分。