fix(mlx): cast custom norm outputs back to activation dtype#1
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds model-aware discovery of custom normalization modules in the MLX trainer so norm output casting can be applied beyond nn.RMSNorm / nn.LayerNorm, with a regression test covering real-world custom norm classes from optional MLX model packages.
Changes:
- Discover additional “norm-like” module classes from a provided model and include them in the output-casting patch set.
- Track which norm classes have been patched to support clean unpatching.
- Add a test that verifies discovery and dtype-casting behavior for several custom norm implementations.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| unsloth_zoo/mlx/trainer.py | Adds heuristics to find custom norm classes from the loaded model and patches/unpatches their __call__ for dtype casting. |
| tests/test_mlx_pr684_review_fixes.py | Adds coverage ensuring custom norms are discovered and their outputs are cast back to activation dtype when enabled. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mmathew23
added a commit
that referenced
this pull request
May 22, 2026
Multi-reviewer pass on the autocast wrapper / norm-upcast path: - Instance-level forward (#2): an instance attribute `model.forward` (Unsloth runtime forward patching) shadows class-method overrides, so mutating __class__ silently bypassed the wrapper -> fp32 norm met a bf16 linear with no autocast and crashed. Now wrap the instance attribute when present; otherwise subclass as before. - Wrapper gating (unslothai#5, unslothai#7): install the wrapper iff fp32 norm params actually exist (from our upcast, the legacy env upcast, or an external _pre_set_compute_dtype policy) -- not on the upcast DECISION. Fixes the rollback path leaving external fp32 norms exposed, and stops wrapping models with no fp32 norm. Add _unwrap_forward_in_bf16_autocast for re-prepare (unslothai#10). - config.architectures leak (unslothai#8/unslothai#9): keep the original __name__ on the generated subclass (unique __qualname__ for registration) so save_pretrained records the base architecture. - Device detection (unslothai#11): recurse into mapping/list/tuple batches and fall back to the model's parameter device instead of defaulting to "cuda". - Legacy UNSLOTH_UPCAST_LAYERNORM (#1/#3/unslothai#4): route through the shared _cast_named_module + union matcher and honour the external-policy deferral. - Recursive external-ownership guard (unslothai#6): record descendants of tagged modules (the external policy casts recursively). - Fresh-interpreter pickle test (unslothai#12): real subprocess load. Shared helpers: _find_tensor_device_type, _call_forward_with_bf16_autocast, _canonical_module_name, _cast_named_module. Unit suite: 25 passed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds MLX norm output cast-back support for custom norm modules discovered from the loaded model.
The helper now patches base
nn.RMSNorm/nn.LayerNormplus custom norm-like modules whose parameters are selected by the same norm-path rule used by_keep_norm_parameters_float32(). This keeps fp32 norm parameters/math while preventing fp32 norm outputs from promoting downstream activations.The discovery is model-local, so hybrid
mlx-lm/mlx-vlmmodels use whichever implementation is actually loaded.Custom Norms Covered
Verified discovery covers these custom norms:
mlx_lm.models.bailing_moe_linear.GroupRMSNormmlx_lm.models.cohere.LayerNorm2Dmlx_lm.models.falcon_h1.FalconH1RMSNormGatedmlx_lm.models.gemma.RMSNormmlx_lm.models.gemma2.RMSNormmlx_lm.models.gemma3_text.RMSNormmlx_lm.models.granitemoehybrid.GraniteMoeHybridRMSNormGatedmlx_lm.models.mamba2.MambaRMSNormGatedmlx_lm.models.nemotron.NemotronLayerNorm1Pmlx_lm.models.nemotron_h.MambaRMSNormGatedmlx_lm.models.plamo2.RMSNormmlx_lm.models.qwen3_next.Qwen3NextRMSNormGatedmlx_lm.models.recurrent_gemma.RMSNormmlx_lm.models.rwkv7.LayerNormPerHeadmlx_lm.models.stablelm.LayerNormPerHeadmlx_lm.models.step3p5.ZeroCenteredRMSNormmlx_vlm.models.deepseekocr_2.vision.Qwen2RMSNormmlx_vlm.models.dots_ocr.vision.RMSNormmlx_vlm.models.fastvlm.vision.LayerNormChannelmlx_vlm.models.gemma3.language.RMSNormmlx_vlm.models.gemma3n.audio.Gemma3nCumulativeGroupNormmlx_vlm.models.gemma3n.language.Gemma3nRMSNormmlx_vlm.models.gemma3n.vision.RMSNormAct2dmlx_vlm.models.gemma4.audio.AudioRMSNormmlx_vlm.models.gemma4.language.RMSNormZeroShiftmlx_vlm.models.gemma4.vision.RMSNormmlx_vlm.models.gemma4.vision.VisionRMSNormmlx_vlm.models.jina_vlm.language.RMSNormmlx_vlm.models.paligemma.language.RMSNormmlx_vlm.models.qwen3_5.language.Qwen3_5RMSNormGatedmlx_vlm.models.sam3.sam_components.LayerNorm2dmlx_vlm.models.sam3d_body.layers.LayerNorm32