opendatalab/MinerU · warning · DeprecationWarning

The function 'replace_sub()' is deprecated, please use 'upgr

Error message

The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead.

What it means

rec_pphgnetv2.py deliberately raises DeprecationWarning (as an exception) from replace_sub(), a legacy PaddlePaddle-style layer-replacement API that was not ported to the PyTorch implementation. The message points to upgrade_sublayer(), the supported replacement that applies handle_func to layers matching a name pattern.

Source

Thrown at mineru/model/utils/pytorchocr/modeling/backbones/rec_pphgnetv2.py:539

            return_patterns = stages_pattern
        # return_stages is int or bool
        if type(return_stages) is int:
            return_stages = [return_stages]
        if isinstance(return_stages, list):
            if max(return_stages) > len(stages_pattern) or min(return_stages) < 0:
                return_stages = [
                    val
                    for val in return_stages
                    if val >= 0 and val < len(stages_pattern)
                ]
            return_patterns = [stages_pattern[i] for i in return_stages]

        if return_patterns:
            self.update_res(return_patterns)

    def replace_sub(self, *args, **kwargs) -> None:
        msg = "The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead."
        raise DeprecationWarning(msg)

    def upgrade_sublayer(
        self,
        layer_name_pattern: Union[str, List[str]],
        handle_func: Callable[[nn.Module, str], nn.Module],
    ) -> Dict[str, nn.Module]:
        """use 'handle_func' to modify the sub-layer(s) specified by 'layer_name_pattern'.

        Args:
            layer_name_pattern (Union[str, List[str]]): The name of layer to be modified by 'handle_func'.
            handle_func (Callable[[nn.Module, str], nn.Module]): The function to modify target layer specified by 'layer_name_pattern'. The formal params are the layer(nn.Module) and pattern(str) that is (a member of) layer_name_pattern (when layer_name_pattern is List type). And the return is the layer processed.

        Returns:
            Dict[str, nn.Module]: The key is the pattern and corresponding value is the result returned by 'handle_func()'.

        Examples:

            from paddle import nn

View on GitHub (pinned to 4fe4bde114)

Solutions

Replace replace_sub(sep, pattern, func) with upgrade_sublayer(pattern, func) which returns the modified modules dict.
If the call was optional (feature tuning), drop it for inference-only usage.
For direct module edits, use normal PyTorch APIs: named_modules() + setattr.

Example fix

# before
backbone.replace_sub(r".*relu.*", convert_to_hswish)

# after
backbone.upgrade_sublayer(r".*relu.*", convert_to_hswish)

Defensive patterns

Strategy: type-guard

Validate before calling

if hasattr(backbone, "upgrade_sublayer"):
    backbone.upgrade_sublayer(pattern, fn)
elif hasattr(backbone, "replace_sub"):
    backbone.replace_sub(pattern, fn)  # legacy path

Type guard

def supports_upgrade_sublayer(module) -> bool:
    return callable(getattr(module, "upgrade_sublayer", None))

Try / catch

try:
    backbone.replace_sub(pattern, fn)
except DeprecationWarning:
    backbone.upgrade_sublayer(pattern, fn)

Prevention

Audit PaddleOCR-derived scripts for replace_sub before porting
Prefer upgrade_sublayer or vanilla named_modules() edits on PyTorch ports

When it happens

Trigger: Calling backbone.replace_sub(...) on the PPHGNetV2 recognition backbone — usually code copied from PaddleOCR examples or older mineru forks that still used the Paddle API.

Common situations: Migrating PaddleOCR training/export scripts to the pytorchocr port; reusing a fine-tune script that swaps ReLU for another activation via replace_sub.

Related errors

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