# Deformable DETR

> Deformable DETR (Zhu et al., ICLR 2021) replaces DETR's dense attention with multi-scale deformable attention: each query samples K = 4 points per head on each of 4 feature levels, giving 43.8 COCO AP in 50 epochs versus 42.0 in 500 for DETR.

Source: https://www.mlfoundry.in/learn/deformable-detr  
Section: Deep Learning › Deep Learning for Computer Vision  
Level: advanced · 8 min read · updated 2026-10-15

**Deformable DETR:** (Zhu, Su, Lu, Li, Wang and Dai, "Deformable DETR: Deformable Transformers for End-to-End Object Detection", ICLR 2021) is a **DETR**-style set-prediction detector in which every attention module over image features is replaced by **multi-scale deformable attention**. A query no longer compares itself with every pixel. It predicts a few sampling offsets around a reference point, reads the features there by bilinear interpolation, and averages them with weights it also predicts.

DETR showed that detection can be end to end, with Hungarian matching and no anchors or NMS. It had two problems. It needs 500 epochs on COCO, and its small-object AP is weak (20.5 AP_S). Both come from dense attention. At initialisation each query spreads its attention almost evenly over all $N_k$ pixels, and learning to focus on a few takes many epochs. The encoder cost is $O(N_q N_k C)$ with $N_q=N_k=HW$, quadratic in the number of pixels, so DETR can only afford the stride-32 map. High-resolution, multi-scale features are exactly what small objects need.

The fix borrows from **Deformable convolution**: sample a small set of learned, input-dependent locations instead of a fixed or exhaustive set. Deformable attention keeps the transformer's multi-head form and applies this idea to it.

## Multi-scale deformable attention

Take query $q$ with feature $z_q$ and a normalised reference point $\hat p_q\in[0,1]^2$. In the encoder, every pixel of every level is a query and its reference point is its own position. In the decoder, $\hat p_q$ is predicted from the object query by a linear layer and a sigmoid. With feature maps $\{x^l\}_{l=1}^{L}$:

$$
\operatorname{MSDeformAttn}\big(z_q,\hat p_q,\{x^l\}\big)=\sum_{m=1}^{M}W_m\Big[\sum_{l=1}^{L}\sum_{k=1}^{K}A_{mlqk}\cdot W'_m\,x^l\big(\phi_l(\hat p_q)+\Delta p_{mlqk}\big)\Big],\qquad \sum_{l=1}^{L}\sum_{k=1}^{K}A_{mlqk}=1
$$

- $M,\,L,\,K$: heads, feature levels, sampling points per head per level; $M=8$, $L=4$, $K=4$
- $\Delta p_{mlqk}$: 2-D sampling offset in level-$l$ pixels, from a linear layer on $z_q$ ($M\!\cdot\!L\!\cdot\!K\!\cdot\!2=256$ outputs); fractional, so $x^l(\cdot)$ is read by bilinear interpolation
- $A_{mlqk}$: attention weight from another linear layer on $z_q$, softmax-normalised over the $L\cdot K=16$ points of head $m$; there is no query–key dot product
- $\phi_l$: rescales the normalised $\hat p_q$ to the coordinates of level $l$, so one query samples the same image region on every scale
- $W_m,\,W'_m$: output and value projections of head $m$, as in standard **Multi-head attention**

Each query reads $M\cdot L\cdot K=128$ values in total, whatever the image size. The paper gives the cost as $O(2N_qC^2+\min(HWC^2,\,N_qKC^2))$ for one level. In the encoder ($N_q=HW$) this is $O(HWC^2)$, linear in the number of pixels. In the decoder's cross-attention it does not depend on $HW$ at all. The decoder's self-attention among the object queries stays dense: it is cheap, and it lets queries suppress duplicates.

> Figure: Deformable DETR. C3–C5 of a ResNet-50 (strides 8, 16, 32) and an extra stride-64 map from a 3×3 stride-2 conv on C5 are projected to 256 channels. The encoder and decoder both use multi-scale deformable attention. Below, one query uses two linear layers to predict 256 offset coordinates and 128 attention weights, samples 4 points on each of 4 levels for each of 8 heads, and sums them. No query–key products are computed.

## The rest of the detector

The levels share one transformer, so a learned **level embedding** $e_l$ is added to the positional encoding to say which scale a token comes from. Sampling points of one query span all levels, so information already moves across scales. The paper found that adding an FPN gave no further gain. The decoder uses $N=300$ queries instead of 100, and focal loss (weight 2) for classification. Each box is predicted relative to the query's reference point: $\hat b=\sigma\big(\Delta b+\sigma^{-1}(\hat p_q)\big)$ for the centre. Hungarian matching and the L1 + GIoU box loss are kept from DETR.

Two variants improve accuracy. **Iterative bounding-box refinement**: each decoder layer refines the box of the previous layer and uses it as the new reference, so later layers sample inside the current box estimate. **Two-stage**: the encoder output first acts as a dense proposal generator, and the top-scoring proposals become the decoder's object queries.

> Figure: One query at the red reference point, sampling a synthetic one-channel feature map on 4 levels of a demo 256×256 input. With the official initialisation, head 1 points along 0° with point k at k + 1 level pixels, and every A = 1/16. The same offsets reach 8× further in image space on C6 than on C3, and the last two C6 points fall off the map and read 0 (zero padding). The head output is 0.4795. Lower panel: at 800×1333 the 4 levels hold 22,223 tokens. Dense attention needs 3.95e9 query–key pairs per layer over 8 heads (15.8 GB of fp32 weights); deformable attention needs 2.84e6, 1389× fewer. With C5 only it is 1,050 tokens and 263× fewer.

**COCO val2017, ResNet-50 (Zhu et al., 2021)**

- **DETR, 500 epochs:** 42.0 AP, AP_S 20.5; 41M params, 86 GFLOPs
- **DETR-DC5, 500 / 50 epochs:** 43.3 AP at 500 epochs; only 35.3 AP when trained for 50
- **Deformable DETR, 50 epochs:** 43.8 AP, AP_S 26.4; 40M params, 173 GFLOPs
- **+ iterative box refinement:** 45.4 AP
- **++ two-stage:** 46.2 AP, AP_S 28.8
- **Defaults:** $M=8$ heads, $L=4$ levels, $K=4$ points, 6 + 6 layers, $d=256$, 300 queries

So in a tenth of the epochs it beats DETR overall, by 5.9 AP on small objects. FLOPs are higher than DETR's, because it processes the stride-8 map. They are lower than DETR-DC5's 187 G, which works at stride 16 only.

## Worked example: one head, one level, K = 2

**Sampling C5 (25×38, from an 800×1216 image) for a query at p̂ = (0.40, 0.56)**

1. Scale the reference point to level pixels: $(0.40\cdot38,\ 0.56\cdot25)=(15.2,\ 14.0)$.
2. Point 1, offset $\Delta p=(1.3,\,-0.6)$: location $(16.5,\ 13.4)$, normalised $(0.4342,\ 0.536)$. Cell centres sit at $i+0.5$, so the grid index is $(u,v)=(16.0,\ 12.9)$. That is exactly column 16, $0.9$ of the way from row 12 to row 13. With $x_{12,16}=0.2$ and $x_{13,16}=0.7$: $0.1\cdot0.2+0.9\cdot0.7=0.65$.
3. Point 2, offset $(-2.2,\,0.5)$: location $(13.0,\ 14.5)$, index $(12.5,\ 14.0)$, halfway between columns 12 and 13 on row 14. With values $0.4$ and $0.2$: $0.5\cdot0.4+0.5\cdot0.2=0.30$.
4. Attention logits $(1.0,\ 0.0)$ from the linear layer: softmax gives $A=(0.7311,\ 0.2689)$.
5. Head output before $W_m$: $0.7311\cdot0.65+0.2689\cdot0.30=0.5559$. Gradients reach $\Delta p$ through the bilinear weights and reach $A$ directly, so both are learned from the detection loss.

Encoder query–key pairs per head per layer at 800×1333 (stride-k maps rounded up)

| Features | Tokens | Dense pairs (N²) | Deformable (16 per query) | Ratio |
| --- | --- | --- | --- | --- |
| C5 only (DETR) | 25×42 = 1,050 | 1,102,500 | 16,800 | 66× |
| dilated C5, stride 16 (DETR-DC5) | 50×84 = 4,200 | 17,640,000 | 67,200 | 262.5× |
| C3–C5 + C6 (Deformable DETR) | 22,223 | 493,861,729 | 355,568 | 1,389× |

```python
import torch
import torch.nn.functional as F

def ms_deform_attn(value, shapes, loc, attn):
    """value: (B, S, M, D) all levels flattened, S = sum(H_l * W_l)
    shapes: [(H_l, W_l)] * L;  loc: (B, Q, M, L, K, 2) normalised (x, y) in [0, 1]
    attn:  (B, Q, M, L, K), softmax-ed over L*K.  Returns (B, Q, M*D)."""
    B, S, M, D = value.shape
    _, Q, _, L, K, _ = loc.shape
    grids = 2 * loc - 1                                   # grid_sample wants [-1, 1]
    sampled = []
    for l, v in enumerate(value.split([h * w for h, w in shapes], dim=1)):
        h, w = shapes[l]
        v = v.flatten(2).transpose(1, 2).reshape(B * M, D, h, w)
        g = grids[:, :, :, l].transpose(1, 2).flatten(0, 1)                  # (B*M, Q, K, 2)
        sampled.append(F.grid_sample(v, g, mode="bilinear", padding_mode="zeros", align_corners=False))
    a = attn.transpose(1, 2).reshape(B * M, 1, Q, L * K)
    out = (torch.stack(sampled, dim=-2).flatten(-2) * a).sum(-1)              # (B*M, D, Q)
    return out.view(B, M * D, Q).transpose(1, 2)

shapes = [(100, 167), (50, 84), (25, 42), (13, 21)]          # 800x1333 input, strides 8..64
S, M, D, L, K, Q = sum(h * w for h, w in shapes), 8, 32, 4, 4, 300
z = torch.randn(1, Q, 256)                                    # decoder queries
ref = torch.rand(1, Q, 1, 1, 1, 2)                            # reference points
offsets = torch.nn.Linear(256, M * L * K * 2)(z).view(1, Q, M, L, K, 2)
norm = torch.tensor([[w, h] for h, w in shapes], dtype=torch.float).view(1, 1, 1, L, 1, 2)
loc = ref + offsets / norm                                     # offsets are in level pixels
attn = torch.nn.Linear(256, M * L * K)(z).view(1, Q, M, L * K).softmax(-1).view(1, Q, M, L, K)
out = ms_deform_attn(torch.randn(1, S, M, D), shapes, loc, attn)
print(S, out.shape)                                            # 22223 torch.Size([1, 300, 256])
```

Pure-PyTorch multi-scale deformable attention core, following the reference implementation in the official repo (not run here; training uses the repo's CUDA kernel)

> **Why it converges ten times faster:** A dense-attention query starts out averaging 22k tokens and has to discover where to look. A deformable query starts with 16 points per head in a small pattern around its reference point. The official initialisation points head $m$ in direction $2\pi m/M$, with point $k$ at $k+1$ level pixels and uniform weights. So the model only has to learn how to move a few nearby samples. The reference point gives each query a spatial prior from the first iteration, and box regression relative to it starts close to the target.

> **Sparse gathers are not free:** FLOPs fall, but bilinear gathers at data-dependent addresses use memory bandwidth poorly. The official repo ships a custom CUDA kernel. The pure `grid_sample` version above is much slower, and export to ONNX or TensorRT needs a plugin or a decomposed implementation. The FLOP count (173 G) also understates the cost of processing the stride-8 map.

**Question:** In deformable attention, how are the attention weights A_mlqk computed?

- A. Softmax of the dot product between the query and each sampled key
- B. By a linear layer on the query feature z_q, softmax-normalised over the L·K points of each head
- C. Fixed to 1/(L·K)
- D. By bilinear interpolation of a learned weight map

**Answer:** B. By a linear layer on the query feature z_q, softmax-normalised over the L·K points of each head — Both the offsets $\Delta p$ and the weights $A$ are predicted from $z_q$ alone, by two linear layers. No keys are compared. That is why the cost per query is constant: 128 samples, against $N_k\approx22$k keys for dense attention at 800×1333. The weights are uniform only at initialisation.

**Question:** Why can Deformable DETR use the stride-8 map when DETR could not?

- A. It uses a smaller backbone
- B. Its encoder cost is linear in the number of pixels, because each pixel-query samples a fixed 128 points instead of attending to all 22k tokens
- C. It downsamples the stride-8 map before the encoder
- D. It removes the encoder

**Answer:** B. Its encoder cost is linear in the number of pixels, because each pixel-query samples a fixed 128 points instead of attending to all 22k tokens — Dense self-attention over 22,223 tokens means 4.9e8 pairs per head per layer, 1389 times the 16 samples per query of deformable attention. With a constant number of samples per query, the high-resolution level that small objects need becomes affordable, and AP_S rises from 20.5 to 26.4.

**Key points**

- Each query samples $K=4$ points per head on each of $L=4$ levels (strides 8–64) around its reference point: 128 bilinear reads, weights and offsets both predicted from the query.
- Encoder cost becomes linear in $HW$, so multi-scale, high-resolution features fit, and no FPN is needed.
- 43.8 COCO AP in 50 epochs vs DETR's 42.0 in 500; AP_S 26.4 vs 20.5; 46.2 AP with box refinement and two stages.
- 300 queries, focal loss, boxes relative to reference points; Hungarian matching and L1 + GIoU are kept from DETR.
- The same multi-scale deformable attention became a standard pixel decoder and encoder block in later detectors and segmenters, such as Mask2Former.

---

From MLFoundry (https://www.mlfoundry.in). The web page adds interactive figures and diagrams.
