opendatalab/MinerU · error · ValueError

The hidden size ({config.hidden_size}) is not a multiple of

Error message

The hidden size ({config.hidden_size}) is not a multiple of the number of attention heads ({config.num_attention_heads})

What it means

ValueError raised in PPDocLayoutV2ReadingOrderSelfAttention.__init__ when config.hidden_size is not divisible by config.num_attention_heads (and no 'embedding_size' attribute exists on the config). Multi-head attention splits the hidden size across heads, so a non-divisible pair cannot produce equal head sizes and construction fails immediately.

Source

Thrown at mineru/model/layout/pp_doclayoutv2.py:394

        return torch.cat([relative_coordinates, relative_dim], dim=-1)

    def get_position_embedding(self, x: torch.Tensor, scale: float = 100.0) -> torch.Tensor:
        embedding = (x * scale).unsqueeze(-1) * self.inv_freq
        return torch.cat((embedding.sin(), embedding.cos()), dim=-1).flatten(start_dim=-2).to(x.dtype)

    def forward(self, source_boxes: torch.Tensor, target_boxes: Optional[torch.Tensor] = None) -> torch.Tensor:
        target_boxes = source_boxes if target_boxes is None else target_boxes
        with torch.no_grad():
            relative_encoding = self.box_relative_encoding(source_boxes, target_boxes)
            position_embedding = self.get_position_embedding(relative_encoding, self.scale).permute(0, 3, 1, 2)
        return self.pos_proj(position_embedding)


class PPDocLayoutV2ReadingOrderSelfAttention(nn.Module):
    def __init__(self, config: PPDocLayoutV2ReadingOrderConfig):
        super().__init__()
        if config.hidden_size % config.num_attention_heads != 0 and not hasattr(config, "embedding_size"):
            raise ValueError(
                f"The hidden size ({config.hidden_size}) is not a multiple of the number of attention heads "
                f"({config.num_attention_heads})"
            )

        self.num_attention_heads = config.num_attention_heads
        self.attention_head_size = int(config.hidden_size / config.num_attention_heads)
        self.all_head_size = self.num_attention_heads * self.attention_head_size
        self.query = nn.Linear(config.hidden_size, self.all_head_size)
        self.key = nn.Linear(config.hidden_size, self.all_head_size)
        self.value = nn.Linear(config.hidden_size, self.all_head_size)
        self.dropout = nn.Dropout(config.attention_probs_dropout_prob)
        self.has_relative_attention_bias = config.has_relative_attention_bias
        self.has_spatial_attention_bias = config.has_spatial_attention_bias

    @staticmethod
    def cogview_attention(attention_scores: torch.Tensor, alpha: float = 32.0) -> torch.Tensor:
        scaled_attention_scores = attention_scores / alpha
        max_value = scaled_attention_scores.amax(dim=-1, keepdim=True)

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Restore the original checkpoint config values for hidden_size and num_attention_heads (do not hand-edit them).
2. Choose a num_attention_heads that divides hidden_size (e.g. 768 -> 12 heads, 256 -> 8 heads).
3. Re-download the model/config from the official source to eliminate corruption.
4. If you intentionally added an 'embedding_size' projection, set config.embedding_size so the check is bypassed as designed.

Example fix

# before
cfg = PPDocLayoutV2ReadingOrderConfig(hidden_size=768, num_attention_heads=10)
attn = PPDocLayoutV2ReadingOrderSelfAttention(cfg)  # ValueError

# after
cfg = PPDocLayoutV2ReadingOrderConfig(hidden_size=768, num_attention_heads=12)
attn = PPDocLayoutV2ReadingOrderSelfAttention(cfg)

def validate_head_config(hidden_size: int, num_attention_heads: int) -> None:
    if hidden_size % num_attention_heads != 0:
        raise ValueError(
            f'hidden_size {hidden_size} must be divisible by num_attention_heads {num_attention_heads}'
        )

validate_head_config(cfg.hidden_size, cfg.num_attention_heads)
attn = PPDocLayoutV2ReadingOrderSelfAttention(cfg)

When it happens

Trigger: Loading PP-DocLayoutV2 reading-order weights with a locally modified config (e.g. hidden_size=768, num_attention_heads=10), or constructing PPDocLayoutV2ReadingOrderConfig with custom values that were never validated.

Common situations: Hand-tuned configs for experiments; porting a config from another model family; corrupted/partially edited config.json after download; version mismatches between a checkpoint's config and the code's expected fields.

Related errors

• PP-DocLayoutV2 reading-order mask must be 2D or 4D, got shap
• PP-DocLayoutV2 reading-order inference requires a mask tenso
• PPDocLayoutV2ForObjectDetection only supports inference.
• Attention mask batch size {attention_mask.shape[0]} does not
• Unsupported image type for PP-DocLayoutV2: {type(image)}

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/bafbfce8399094c3. Report an issue: GitHub.