PaddlePaddle/PaddleOCR · error · NotImplementedError

Sliding window is currently only implemented for causal mask

Error message

Sliding window is currently only implemented for causal masking

What it means

This NotImplementedError is raised while building the 4D attention mask inside the UniMERNet recognition head (a port of HuggingFace transformer masking logic into PaddleOCR). A sliding window attention config (self.sliding_window) is only supported when the mask is built via the causal path (_make_causal_mask). If attention is not causal (no is_causal condition) but sliding_window is set, the library refuses to guess the correct windowed mask.

Source

Thrown at ppocr/modeling/heads/rec_unimernet_head.py:359

        input_shape = (attention_mask_2d.shape[0], query_length)
        causal_4d_mask = None
        if (input_shape[-1] > 1 or self.sliding_window is not None) and self.is_causal:
            if key_value_length is None:
                raise ValueError(
                    "This attention mask converter is causal. Make sure to pass `key_value_length` to correctly create a causal mask."
                )

            past_key_values_length = key_value_length - query_length

            causal_4d_mask = self._make_causal_mask(
                input_shape,
                dtype,
                past_key_values_length=past_key_values_length,
                sliding_window=self.sliding_window,
                is_export=is_export,
            )
        elif self.sliding_window is not None:
            raise NotImplementedError(
                "Sliding window is currently only implemented for causal masking"
            )

        expanded_attn_mask = self._expand_mask(
            attention_mask_2d, dtype, tgt_len=input_shape[-1]
        )

        if causal_4d_mask is not None:
            if is_export:
                expanded_attn_mask = causal_4d_mask
                return expanded_attn_mask
            else:
                expanded_attn_mask = causal_4d_mask.masked_fill_(
                    expanded_attn_mask.cast(paddle.bool), paddle.finfo(dtype).min
                )

        expanded_4d_mask = expanded_attn_mask

View on GitHub (pinned to 2661c7c0ef)

Solutions

Remove sliding_window (leave it None / unset) from the model config used by rec_unimernet_head
Keep sliding_window but ensure the causal path is taken (is_causal=True / causal input condition) so _make_causal_mask handles the window
If bidirectional sliding-window attention is genuinely required, implement a non-causal sliding-window mask and patch the elif branch in _update_causal_mask

Example fix

// before (config dict)
{'Model': {'head': {'sliding_window': 512, ...}}}
// after
{'Model': {'head': {'sliding_window': null, ...}}}

Defensive patterns

Strategy: validation

Validate before calling

cfg = head_config
if cfg.get('sliding_window') is not None and not cfg.get('is_causal', False):
    raise SystemExit('sliding_window requires causal masking; remove it or set is_causal')

Type guard

def supports_sliding_window(cfg: dict) -> bool:
    return cfg.get('sliding_window') is None or bool(cfg.get('is_causal', False))

Try / catch

try:
    out = model(...)
except NotImplementedError as e:
    if 'Sliding window' in str(e):
        cfg['sliding_window'] = None  # retry without windowing
        out = model(...)
    else:
        raise

Prevention

Keep sliding_window unset unless you know the head runs its causal path
Add a config lint step that rejects sliding_window for non-causal UniMERNet setups

When it happens

Trigger: Calling the UniMERnet head / its mask-preparation code with a config that sets sliding_window to a non-None value while the input is processed with a non-causal (bidirectional/padding-only) attention mask path, i.e. is_causal is falsy and a 2D attention_mask is supplied.

Common situations: Copying a HF config (e.g. Qwen2/ Mistral-style) that includes sliding_window into the UniMERNet head config; upgrading configs from a version that ignored sliding_window to one that validates it.

Related errors

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/2de9e3be60adfce1. Report an issue: GitHub.