{"record":{"id":"497736027222d020","repo":"PaddlePaddle/PaddleOCR","slug":"incorrect-4d-attention-mask-shape-tuple-attentio-497736","errorCode":null,"errorMessage":"Incorrect 4D attention_mask shape: {tuple(attention_mask.shape)}; expected: {expected_shape}.","messagePattern":"Incorrect 4D attention_mask shape: (.+?); expected: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"ppocr/modeling/heads/rec_unimernet_head.py","lineNumber":452,"sourceCode":"    )\n    key_value_length = input_shape[-1] + past_key_values_length\n\n    shape = attention_mask.shape\n    len_shape = len(shape)\n    if (attention_mask is not None) and (len_shape == 2):\n        attention_mask = attn_mask_converter.to_4d(\n            attention_mask,\n            input_shape[-1],\n            key_value_length=key_value_length,\n            dtype=inputs_embeds.dtype,\n            is_export=is_export,\n        )\n\n        return attention_mask\n    elif attention_mask is not None and len(attention_mask.shape) == 4:\n        expected_shape = (input_shape[0], 1, input_shape[1], key_value_length)\n        if tuple(attention_mask.shape) != expected_shape:\n            raise ValueError(\n                f\"Incorrect 4D attention_mask shape: {tuple(attention_mask.shape)}; expected: {expected_shape}.\"\n            )\n        else:\n            inverted_mask = 1.0 - attention_mask\n            attention_mask = inverted_mask.masked_fill_(\n                inverted_mask.to(paddle.bool), paddle.finfo(inputs_embeds.dtype).min\n            )\n    else:\n        attention_mask = attn_mask_converter.to_causal_4d(\n            input_shape[0],\n            input_shape[-1],\n            key_value_length,\n            dtype=inputs_embeds.dtype,\n        )\n\n    return attention_mask\n\n","sourceCodeStart":434,"sourceCodeEnd":470,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/ppocr/modeling/heads/rec_unimernet_head.py#L434-L470","documentation":"When the caller passes a pre-built 4D attention mask to the UniMERNet head, the code validates its shape against (batch_size, 1, target_len, key_value_length), where key_value_length includes any past cached KV length. Any deviation raises this ValueError, because an incorrectly shaped additive mask would silently broadcast and corrupt attention scores.","triggerScenarios":"Passing attention_mask with 4 dimensions whose shape is not exactly [batch, 1, tgt_len, key_value_length]; common when tgt_len was computed for a different sequence length or past_key_values length was not added to the last dimension.","commonSituations":"Migrating code from HuggingFace transformers where a 4D mask was accepted with slightly different conventions; incremental decoding where the mask last dim must be tgt_len + past_key_values_length but only tgt_len was built; batch dimension squeezed/expanded incorrectly.","solutions":["Pass a 2D attention_mask of shape [batch, seq_len] instead and let attn_mask_converter.to_4d build the 4D mask","If a 4D mask is required, construct it as paddle.ones([bsz, 1, tgt_len, tgt_len + past_kv_len]) and apply your own 0/ -inf logic","Verify inputs_embeds sequence length matches input_shape[-1] used to compute expected_shape"],"exampleFix":"# before\nattention_mask = mask_4d  # shape [bsz, 1, tgt, tgt]\nmodel(input_ids=ids, inputs_embeds=emb, attention_mask=attention_mask)\n# after\nmodel(input_ids=ids, inputs_embeds=emb, attention_mask=mask_2d)  # [bsz, seq_len]","handlingStrategy":"validation","validationCode":"expected = (input_embeds.shape[0], 1, input_embeds.shape[1], input_embeds.shape[1] + past_kv_len)\nassert attention_mask.shape == expected, f'mask {attention_mask.shape} != {expected}'\n# safer: just pass the 2D mask\nif attention_mask is not None and attention_mask.ndim == 4:\n    attention_mask = attention_mask[:, 0, 0, :]  # reduce to 2D if it is a simple key mask","typeGuard":"def is_valid_4d_mask(mask, bsz, tgt_len, kv_len) -> bool:\n    return mask is None or mask.ndim != 4 or tuple(mask.shape) == (bsz, 1, tgt_len, kv_len)","tryCatchPattern":"try:\n    out = head(inputs_embeds=emb, attention_mask=mask)\nexcept ValueError as e:\n    if '4D attention_mask shape' in str(e):\n        out = head(inputs_embeds=emb, attention_mask=mask_2d)  # fall back to 2D\n    else:\n        raise","preventionTips":["Prefer 2D [bsz, seq] masks; let the head expand them","When hand-building 4D masks, derive the last dim as tgt_len + past_key_values_length"],"tags":["paddle","attention-mask","shape-mismatch","validation"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}