Encoder-Decoder Architecture

The Story That Explains Encoder-Decoder

The Encoder-Decoder architecture (also called sequence-to-sequence or seq2seq) is the backbone of modern machine translation, summarisation, speech recognition, image captioning, and nearly every large language model in use today. Understanding it deeply means understanding how GPT, BERT, T5, and Whisper all work under the hood.

The Big Picture — Architecture Overview

Before diving into components, here is the full data flow from input tokens to output tokens.

The Encoder — Reading and Understanding

Self-Attention — How Every Token Talks to Every Other Token

Self-Attention is the heart of the Encoder. For each token, it computes three vectors: Query (Q), Key (K), and Value (V). Think of it as a soft database lookup: the Query asks a question, the Keys determine relevance, and the Values hold the content.

Multi-Head Attention — Many Perspectives at Once

A single attention head can only focus on one type of relationship at a time. Multi-Head Attention runs h attention heads in parallel, each with its own Q, K, V projections. Their outputs are concatenated and projected back to d_model.

Encoder Layer — Full Walkthrough

The Decoder — Generating Output

Three Sub-Layers of the Decoder

Cross-Attention — The Bridge Between Encoder and Decoder

Cross-Attention is the mechanism that lets the decoder "consult" the encoder. It is the most important part of the Encoder-Decoder architecture — without it, the decoder would generate output in a vacuum.

Positional Encoding — Giving the Model a Sense of Order

The original Transformer uses sinusoidal positional encoding:

Python Implementation — From Scratch with PyTorch

Step 1 — Scaled Dot-Product Attention

import torch
import torch.nn as nn
import torch.nn.functional as F
import math

def scaled_dot_product_attention(Q, K, V, mask=None):
    """
    Q, K, V: [batch, heads, seq_len, d_k]
    mask:    [batch, 1, seq_len, seq_len] — True = keep, False = mask
    """
    d_k = Q.size(-1)

    # Step 1: Dot-product scores and scale
    scores = torch.matmul(Q, K.transpose(-2, -1)) / math.sqrt(d_k)
    # scores: [batch, heads, seq_len, seq_len]

    # Step 2: Apply mask (set masked positions to -inf → 0 after softmax)
    if mask is not None:
        scores = scores.masked_fill(mask == 0, -1e9)

    # Step 3: Softmax to get attention weights
    attn_weights = F.softmax(scores, dim=-1)

    # Step 4: Weighted sum of values
    output = torch.matmul(attn_weights, V)
    return output, attn_weights

Step 2 — Multi-Head Attention

class MultiHeadAttention(nn.Module):
    def __init__(self, d_model, num_heads):
        super().__init__()
        assert d_model % num_heads == 0, "d_model must be divisible by num_heads"

        self.d_model    = d_model
        self.num_heads  = num_heads
        self.d_k        = d_model // num_heads  # dimension per head

        # Learned projection matrices for Q, K, V and the output
        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 split_heads(self, x):
        # x: [batch, seq_len, d_model]
        # → [batch, num_heads, seq_len, d_k]
        batch, seq_len, _ = x.size()
        x = x.view(batch, seq_len, self.num_heads, self.d_k)
        return x.transpose(1, 2)

    def forward(self, Q_in, K_in, V_in, mask=None):
        # Project inputs
        Q = self.split_heads(self.W_Q(Q_in))
        K = self.split_heads(self.W_K(K_in))
        V = self.split_heads(self.W_V(V_in))

        # Attention across all heads in parallel
        attn_out, _ = scaled_dot_product_attention(Q, K, V, mask)

        # Merge heads: [batch, heads, seq_len, d_k] → [batch, seq_len, d_model]
        batch, _, seq_len, _ = attn_out.size()
        attn_out = attn_out.transpose(1, 2).contiguous().view(batch, seq_len, self.d_model)

        return self.W_O(attn_out)  # Final output projection

Step 3 — Encoder Layer

class EncoderLayer(nn.Module):
    def __init__(self, d_model, num_heads, d_ff, dropout=0.1):
        super().__init__()
        self.self_attn  = MultiHeadAttention(d_model, num_heads)
        self.ffn        = nn.Sequential(
            nn.Linear(d_model, d_ff),
            nn.ReLU(),
            nn.Dropout(dropout),
            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, src_mask=None):
        # Self-attention sub-layer (Q = K = V = x)
        attn_out = self.self_attn(x, x, x, src_mask)
        x = self.norm1(x + self.dropout(attn_out))   # Residual + Norm

        # Feed-forward sub-layer
        ffn_out = self.ffn(x)
        x = self.norm2(x + self.dropout(ffn_out))     # Residual + Norm
        return x

Step 4 — Decoder Layer

class DecoderLayer(nn.Module):
    def __init__(self, d_model, num_heads, d_ff, dropout=0.1):
        super().__init__()
        self.masked_self_attn = MultiHeadAttention(d_model, num_heads)
        self.cross_attn       = MultiHeadAttention(d_model, num_heads)
        self.ffn              = nn.Sequential(
            nn.Linear(d_model, d_ff), nn.ReLU(),
            nn.Dropout(dropout), 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_output, src_mask=None, tgt_mask=None):
        # 1. Masked Self-Attention on decoder's own past outputs
        ma_out = self.masked_self_attn(x, x, x, tgt_mask)
        x = self.norm1(x + self.dropout(ma_out))

        # 2. Cross-Attention: Q from decoder, K & V from encoder
        ca_out = self.cross_attn(x, enc_output, enc_output, src_mask)
        x = self.norm2(x + self.dropout(ca_out))

        # 3. Feed-Forward
        ffn_out = self.ffn(x)
        x = self.norm3(x + self.dropout(ffn_out))
        return x

Step 5 — Full Transformer

class Transformer(nn.Module):
    def __init__(self, src_vocab, tgt_vocab, d_model=512, N=6,
                 num_heads=8, d_ff=2048, dropout=0.1, max_len=5000):
        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)  # See below

        self.encoder_layers = nn.ModuleList(
            [EncoderLayer(d_model, num_heads, d_ff, dropout) for _ in range(N)]
        )
        self.decoder_layers = nn.ModuleList(
            [DecoderLayer(d_model, num_heads, d_ff, dropout) for _ in range(N)]
        )
        self.fc_out = nn.Linear(d_model, tgt_vocab)

    def encode(self, src, src_mask):
        x = self.pos_enc(self.src_embed(src))
        for layer in self.encoder_layers:
            x = layer(x, src_mask)
        return x  # [batch, src_len, d_model]

    def decode(self, tgt, enc_out, src_mask, tgt_mask):
        x = self.pos_enc(self.tgt_embed(tgt))
        for layer in self.decoder_layers:
            x = layer(x, enc_out, src_mask, tgt_mask)
        return x

    def forward(self, src, tgt, src_mask, tgt_mask):
        enc_out = self.encode(src, src_mask)
        dec_out = self.decode(tgt, enc_out, src_mask, tgt_mask)
        return self.fc_out(dec_out)   # [batch, tgt_len, tgt_vocab]

class PositionalEncoding(nn.Module):
    def __init__(self, d_model, max_len=5000, dropout=0.1):
        super().__init__()
        self.dropout = nn.Dropout(dropout)
        pe = torch.zeros(max_len, d_model)
        pos = torch.arange(0, max_len).unsqueeze(1).float()
        div = torch.exp(torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model))
        pe[:, 0::2] = torch.sin(pos * div)
        pe[:, 1::2] = torch.cos(pos * div)
        self.register_buffer('pe', pe.unsqueeze(0))

    def forward(self, x):
        x = x + self.pe[:, :x.size(1)]
        return self.dropout(x)

Step 6 — Quick Sanity Check

# Sanity check — forward pass with random data
model = Transformer(src_vocab=10000, tgt_vocab=10000)
model.eval()

batch, src_len, tgt_len = 2, 12, 10
src = torch.randint(0, 10000, (batch, src_len))
tgt = torch.randint(0, 10000, (batch, tgt_len))

# Source mask: no padding (all ones)
src_mask = torch.ones(batch, 1, src_len, src_len)

# Target mask: causal (lower triangular)
tgt_mask = torch.tril(torch.ones(tgt_len, tgt_len)).unsqueeze(0).unsqueeze(0)

with torch.no_grad():
    logits = model(src, tgt, src_mask, tgt_mask)

print(f"Input shape:  {src.shape}")
print(f"Target shape: {tgt.shape}")
print(f"Output shape: {logits.shape}")

Decoding Strategies — How We Generate Text

The raw model output is a probability distribution over the vocabulary. How we sample from it massively affects the quality, creativity, and coherence of the generated text.

Encoder-Only, Decoder-Only, Encoder-Decoder — When to Use Which

The full Encoder-Decoder is just one of three variants. Understanding which to use for your task is critical.

Real-World Applications

Using Hugging Face — Production-Ready in 10 Lines

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
import torch

# ── Translation: English → French using Helsinki-NLP ──────
tokenizer = AutoTokenizer.from_pretrained("Helsinki-NLP/opus-mt-en-fr")
model     = AutoModelForSeq2SeqLM.from_pretrained("Helsinki-NLP/opus-mt-en-fr")

src_text = "The encoder-decoder architecture revolutionised natural language processing."
inputs   = tokenizer(src_text, return_tensors="pt", padding=True)

# Generate with beam search
with torch.no_grad():
    generated_ids = model.generate(
        inputs["input_ids"],
        num_beams=5,
        max_length=100,
        early_stopping=True
    )

translation = tokenizer.decode(generated_ids[0], skip_special_tokens=True)
print(f"EN: {src_text}")
print(f"FR: {translation}")

# ── Summarisation with BART ───────────────────────────────
from transformers import pipeline

summariser = pipeline("summarization", model="facebook/bart-large-cnn")

article = """
    The Transformer architecture, introduced in the landmark 2017 paper
    'Attention Is All You Need' by Vaswani et al., replaced recurrent neural
    networks with self-attention mechanisms. This allowed massively parallel
    computation during training and eliminated the vanishing gradient problem
    that plagued RNNs. The architecture consists of an encoder stack that
    processes the input, and a decoder stack that generates the output,
    connected by cross-attention. Within three years, nearly every
    state-of-the-art NLP system was built on this foundation.
"""

result = summariser(article, max_length=60, min_length=20, do_sample=False)
print(result[0]["summary_text"])

Common Failure Modes and How to Fix Them

Golden Rules for Encoder-Decoder Models