{"record":{"id":"971a9c5a2231c6e8","repo":"hiyouga/LlamaFactory","slug":"npurmsnormkernel-requires-torch-npu","errorCode":null,"errorMessage":"NpuRMSNormKernel requires torch_npu.","messagePattern":"NpuRMSNormKernel requires torch_npu\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/plugins/model_plugins/kernels/ops/rms_norm/npu_rms_norm.py","lineNumber":171,"sourceCode":"        \"Qwen3_5MoeRMSNormGated\": npu_gated_rms_norm_forward,\n    },\n}\n\n\n@KernelPlugin(\"npu_fused_rmsnorm\").register()\nclass NpuRMSNormKernel(BaseKernel):\n    \"\"\"NPU kernel wrapper for RMSNorm that applies the replacement within a model.\"\"\"\n\n    @staticmethod\n    def check_device() -> None:\n        current = get_current_accelerator().type\n        if current != DeviceType.NPU:\n            raise RuntimeError(f\"NpuRMSNormKernel requires NPU, current accelerator is {current}.\")\n\n    @staticmethod\n    def check_deps() -> None:\n        if _TORCH_NPU_IMPORT_ERROR is not None:\n            raise RuntimeError(\"NpuRMSNormKernel requires torch_npu.\") from _TORCH_NPU_IMPORT_ERROR\n\n    @staticmethod\n    def _get_patch_forward(model_type: str, module: torch.nn.Module):\n        \"\"\"Return the NPU forward function for a matched RMSNorm module.\"\"\"\n        model_patches = _MODEL_TYPE_TO_PATCHES.get(model_type, {})\n        return model_patches.get(module.__class__.__name__)\n\n    @staticmethod\n    def _apply(**kwargs) -> \"HFModel\":\n        \"\"\"Iterate the model and apply NPU-optimized forward to matched RMSNorm modules.\n\n        Matches modules configured for the current model type, then binds the corresponding\n        NPU-optimized forward function as an instance method via ``types.MethodType`` to\n        replace the original ``forward``.\n\n        Args:\n            **kwargs: Keyword arguments containing the model.\n","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/plugins/model_plugins/kernels/ops/rms_norm/npu_rms_norm.py#L153-L189","documentation":"The npu_fused_rmsnorm plugin depends on torch_npu for torch_npu.npu_rms_norm. If the import failed at module load, check_deps() raises RuntimeError chained to the stored ImportError when the plugin is applied.","triggerScenarios":"Applying npu_fused_rmsnorm in an environment where `import torch_npu` raises — wheel missing, torch version mismatch, or CANN toolkit environment not sourced.","commonSituations":"Ascend containers with mismatched torch/torch_npu/CANN triples; pip upgrading torch and silently breaking torch_npu's pinned ABI.","solutions":["Install the torch_npu build matching torch and CANN; verify `import torch_npu` succeeds","Read the chained __cause__ ImportError for the precise broken symbol/module","Source CANN set_env.sh in the container/launch environment"],"exampleFix":"# before\n# RuntimeError: NpuRMSNormKernel requires torch_npu.\n# after\npip install torch_npu==<matching> && source /usr/local/Ascend/ascend-toolkit/set_env.sh","handlingStrategy":"validation","validationCode":"try:\n    import torch_npu  # noqa: F401\nexcept ImportError:\n    kernels = [k for k in kernels if k != \"npu_fused_rmsnorm\"]","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin torch_npu/torch/CANN as a matched triple in requirements","Preflight import checks in launch scripts"],"tags":["dependencies","npu","torch-npu","rmsnorm"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}