{"record":{"id":"c93d72ac2807317c","repo":"opendatalab/MinerU","slug":"the-function-replace-sub-is-deprecated-please","errorCode":null,"errorMessage":"The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead.","messagePattern":"The function 'replace_sub\\(\\)' is deprecated, please use 'upgrade_sublayer\\(\\)' instead\\.","errorType":"exception","errorClass":"DeprecationWarning","httpStatus":null,"severity":"warning","filePath":"mineru/model/utils/pytorchocr/modeling/backbones/rec_pphgnetv2.py","lineNumber":539,"sourceCode":"            return_patterns = stages_pattern\n        # return_stages is int or bool\n        if type(return_stages) is int:\n            return_stages = [return_stages]\n        if isinstance(return_stages, list):\n            if max(return_stages) > len(stages_pattern) or min(return_stages) < 0:\n                return_stages = [\n                    val\n                    for val in return_stages\n                    if val >= 0 and val < len(stages_pattern)\n                ]\n            return_patterns = [stages_pattern[i] for i in return_stages]\n\n        if return_patterns:\n            self.update_res(return_patterns)\n\n    def replace_sub(self, *args, **kwargs) -> None:\n        msg = \"The function 'replace_sub()' is deprecated, please use 'upgrade_sublayer()' instead.\"\n        raise DeprecationWarning(msg)\n\n    def upgrade_sublayer(\n        self,\n        layer_name_pattern: Union[str, List[str]],\n        handle_func: Callable[[nn.Module, str], nn.Module],\n    ) -> Dict[str, nn.Module]:\n        \"\"\"use 'handle_func' to modify the sub-layer(s) specified by 'layer_name_pattern'.\n\n        Args:\n            layer_name_pattern (Union[str, List[str]]): The name of layer to be modified by 'handle_func'.\n            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.\n\n        Returns:\n            Dict[str, nn.Module]: The key is the pattern and corresponding value is the result returned by 'handle_func()'.\n\n        Examples:\n\n            from paddle import nn","sourceCodeStart":521,"sourceCodeEnd":557,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/model/utils/pytorchocr/modeling/backbones/rec_pphgnetv2.py#L521-L557","documentation":"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.","triggerScenarios":"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.","commonSituations":"Migrating PaddleOCR training/export scripts to the pytorchocr port; reusing a fine-tune script that swaps ReLU for another activation via replace_sub.","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."],"exampleFix":"# before\nbackbone.replace_sub(r\".*relu.*\", convert_to_hswish)\n\n# after\nbackbone.upgrade_sublayer(r\".*relu.*\", convert_to_hswish)","handlingStrategy":"type-guard","validationCode":"if hasattr(backbone, \"upgrade_sublayer\"):\n    backbone.upgrade_sublayer(pattern, fn)\nelif hasattr(backbone, \"replace_sub\"):\n    backbone.replace_sub(pattern, fn)  # legacy path","typeGuard":"def supports_upgrade_sublayer(module) -> bool:\n    return callable(getattr(module, \"upgrade_sublayer\", None))","tryCatchPattern":"try:\n    backbone.replace_sub(pattern, fn)\nexcept DeprecationWarning:\n    backbone.upgrade_sublayer(pattern, fn)","preventionTips":["Audit PaddleOCR-derived scripts for replace_sub before porting","Prefer upgrade_sublayer or vanilla named_modules() edits on PyTorch ports"],"tags":["ocr","backbone","pphgnet","deprecated-api","migration"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}