Skip to content

Commit 490d46d

Browse files
authored
Merge pull request #1 from Sunwish/pr/01-mxfp-qat-core
[fsdp, model, training_utils, hardware] feat: add MXFP QAT for dense linear and MoE
2 parents cb367c2 + 19f96b1 commit 490d46d

13 files changed

Lines changed: 1407 additions & 13 deletions

File tree

‎tests/utils/test_mxfp_moe_cpu.py‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
import torch
2+
from torch import nn
3+
4+
from verl.utils.qat.mxfp_linear import MXFPQATConfig
5+
from verl.utils.qat.mxfp_moe import (
6+
_transform_tokens,
7+
_transform_weight,
8+
attach_mxfp_expert_qat,
9+
get_mxfp_expert_qat_config,
10+
prepare_mxfp_fprop_operands,
11+
)
12+
13+
14+
class _FakeMoeBlock(nn.Module):
15+
def __init__(self):
16+
super().__init__()
17+
self.gate = nn.Linear(32, 4, bias=False)
18+
self.experts = nn.Module()
19+
20+
21+
def _config():
22+
return MXFPQATConfig(
23+
mode="mxfp_w8a8",
24+
quant_backend="torch",
25+
fake_quant_targets=("fprop", "dgrad", "wgrad"),
26+
backward_reduction_axis_fake_quant=True,
27+
rotation_enable=True,
28+
rotation_targets=("fprop", "dgrad", "wgrad"),
29+
rotation_block_size=32,
30+
rotation_seed=7,
31+
)
32+
33+
34+
def test_attach_only_marks_moe_blocks():
35+
model = nn.Sequential(_FakeMoeBlock(), nn.Linear(32, 32))
36+
config = _config()
37+
assert attach_mxfp_expert_qat(model, config) == 1
38+
assert get_mxfp_expert_qat_config(model[0]) is config
39+
assert get_mxfp_expert_qat_config(model[1]) is None
40+
41+
42+
def test_grouped_weight_transforms_use_reduction_axis():
43+
config = _config()
44+
weight = torch.randn(4, 32, 64)
45+
transformed = _transform_weight(weight, config, "fprop", config.weight_format, reduction_dim=1)
46+
assert transformed.shape == weight.shape
47+
dgrad_weight = _transform_weight(weight, config, "dgrad", config.weight_format, reduction_dim=2)
48+
assert dgrad_weight.shape == weight.shape
49+
assert torch.isfinite(transformed).all()
50+
assert torch.isfinite(dgrad_weight).all()
51+
52+
53+
def test_wgrad_transform_quantizes_token_reduction_axis():
54+
config = _config()
55+
x = torch.randn(65, 32)
56+
transformed = _transform_tokens(x, config, "wgrad", config.activation_format)
57+
assert transformed.shape == x.shape
58+
assert torch.isfinite(transformed).all()
59+
60+
61+
def test_gate_up_can_share_detached_fprop_input():
62+
config = _config()
63+
x = torch.randn(65, 32, requires_grad=True)
64+
weight = torch.randn(4, 32, 64, requires_grad=True)
65+
x_fprop, weight_fprop = prepare_mxfp_fprop_operands(x, weight, config)
66+
assert x_fprop.shape == x.shape
67+
assert weight_fprop.shape == weight.shape
68+
assert not x_fprop.requires_grad
69+
assert not weight_fprop.requires_grad

‎tests/utils/test_mxfp_quant_cpu.py‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
import pytest
2+
import torch
3+
4+
from verl.utils.qat.mxfp_quant import (
5+
MXFPMode,
6+
dequantize_mxfp4,
7+
dequantize_mxfp8,
8+
fake_quantize,
9+
normalize_mxfp_mode,
10+
quantize_mxfp4,
11+
quantize_mxfp8,
12+
)
13+
from verl.utils.qat.mxfp_rotation import RotationConfig, _matrix, rotate_blocks
14+
from verl.utils.qat.mxfp_linear import MXFPQATConfig, MXFPQATLinear
15+
16+
17+
@pytest.mark.parametrize("mode", ["mxfp_w8a8", "w8a8_mxfp8", "mxfp_w4a8", "mxfp_w4a4"])
18+
def test_mode_names_normalize(mode):
19+
assert normalize_mxfp_mode(mode) in {MXFPMode.W8A8, MXFPMode.W4A8, MXFPMode.W4A4}
20+
21+
22+
@pytest.mark.parametrize("quantize,dequantize", [(quantize_mxfp8, dequantize_mxfp8), (quantize_mxfp4, dequantize_mxfp4)])
23+
def test_mxfp_qdq_preserves_shape_and_is_finite(quantize, dequantize):
24+
x = torch.linspace(-2, 2, 96, dtype=torch.float32).reshape(3, 32)
25+
payload, scale = quantize(x)
26+
y = dequantize(payload, scale, x.dtype)
27+
assert y.shape == x.shape
28+
assert torch.isfinite(y).all()
29+
assert torch.count_nonzero(y).item() > 0
30+
31+
32+
def test_mxfp8_zero_block_stays_zero():
33+
x = torch.zeros((2, 64), dtype=torch.float32)
34+
payload, scale = quantize_mxfp8(x)
35+
assert torch.count_nonzero(dequantize_mxfp8(payload, scale, x.dtype)).item() == 0
36+
37+
38+
@pytest.mark.parametrize("fmt", ["mxfp8", "mxfp4"])
39+
def test_fake_quant_pads_and_restores_non_aligned_dimension(fmt):
40+
x = torch.randn((2, 37), dtype=torch.float32)
41+
y = fake_quantize(x, fmt)
42+
assert y.shape == x.shape
43+
assert torch.isfinite(y).all()
44+
45+
46+
def test_rotation_is_seeded_and_orthogonal():
47+
config = RotationConfig(enable=True, targets=("fprop",), block_size=8, seed=17)
48+
matrix_a = _matrix(8, 17, torch.device("cpu"), torch.float32)
49+
matrix_b = _matrix(8, 17, torch.device("cpu"), torch.float32)
50+
assert torch.equal(matrix_a, matrix_b)
51+
assert torch.allclose(matrix_a @ matrix_a.T, torch.eye(8), atol=1e-6)
52+
x = torch.randn((3, 19))
53+
assert rotate_blocks(x, config).shape == x.shape
54+
55+
56+
def test_linear_replacement_reuses_parameters_and_has_identity_without_transforms():
57+
linear = torch.nn.Linear(32, 64)
58+
config = MXFPQATConfig(
59+
mode="mxfp_w8a8", quant_backend="torch", fake_quant_targets=(), rotation_enable=False
60+
)
61+
qat = MXFPQATLinear.from_linear(linear, config)
62+
assert qat.weight is linear.weight
63+
assert qat.bias is linear.bias
64+
x = torch.randn((3, 32))
65+
assert torch.equal(qat(x), linear(x))
66+
67+
68+
@pytest.mark.parametrize("targets", [("fprop",), ("dgrad",), ("wgrad",), ("fprop", "dgrad", "wgrad")])
69+
@pytest.mark.parametrize("save_backward_axes", [False, True])
70+
def test_linear_backward_targets_keep_gradient_shapes(targets, save_backward_axes):
71+
linear = torch.nn.Linear(32, 64)
72+
config = MXFPQATConfig(
73+
mode="mxfp_w8a8",
74+
quant_backend="torch",
75+
fake_quant_targets=targets,
76+
backward_reduction_axis_fake_quant=save_backward_axes,
77+
)
78+
qat = MXFPQATLinear.from_linear(linear, config)
79+
x = torch.randn((4, 32), requires_grad=True)
80+
qat(x).square().mean().backward()
81+
assert x.grad is not None and x.grad.shape == x.shape and torch.isfinite(x.grad).all()
82+
assert qat.weight.grad is not None and qat.weight.grad.shape == qat.weight.shape
83+
assert torch.isfinite(qat.weight.grad).all()
84+
85+
86+
def test_linear_fprop_rotation_returns_gradients_in_original_coordinates():
87+
linear = torch.nn.Linear(32, 64)
88+
config = MXFPQATConfig(
89+
mode="mxfp_w8a8",
90+
quant_backend="torch",
91+
fake_quant_targets=(),
92+
rotation_enable=True,
93+
rotation_targets=("fprop",),
94+
rotation_seed=23,
95+
)
96+
qat = MXFPQATLinear.from_linear(linear, config)
97+
x = torch.randn((4, 32), requires_grad=True)
98+
qat(x).sum().backward()
99+
assert x.grad.shape == x.shape
100+
assert qat.weight.grad.shape == linear.weight.shape

‎verl/models/transformers/npu_patch.py‎

Lines changed: 49 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,14 @@
2929
from transformers.models.qwen3_next import modeling_qwen3_next
3030
from transformers.models.qwen3_vl import modeling_qwen3_vl
3131
from transformers.models.qwen3_vl_moe import modeling_qwen3_vl_moe
32-
from transformers.utils import logging
32+
from transformers.utils import logging
33+
34+
from verl.utils.qat.mxfp_moe import (
35+
get_mxfp_expert_qat_config,
36+
mxfp_grouped_matmul,
37+
prepare_mxfp_fprop_operands,
38+
prepare_mxfp_weight_fprop,
39+
)
3340

3441
logger = logging.get_logger(__name__)
3542

@@ -193,10 +200,47 @@ def _qwen3_sparse_moe_routed_forward_npu(self, hidden_states: torch.Tensor):
193200
num_experts = self.gate.weight.shape[0]
194201
tokens_per_expert = torch.histc(selected_experts, bins=num_experts, min=0, max=num_experts)
195202

196-
up_res = NPUGmmFunction.apply(permuted_tokens, w1, tokens_per_expert)
197-
gate_res = NPUGmmFunction.apply(permuted_tokens, w2, tokens_per_expert)
198-
act_res = torch_npu.npu_swiglu(torch.cat([gate_res, up_res], dim=-1))
199-
down_res = NPUGmmFunction.apply(act_res, w3, tokens_per_expert)
203+
mxfp_qat_config = get_mxfp_expert_qat_config(self)
204+
if mxfp_qat_config is not None:
205+
permuted_tokens_fprop, w1_fprop = prepare_mxfp_fprop_operands(
206+
permuted_tokens, w1, mxfp_qat_config
207+
)
208+
w2_fprop = prepare_mxfp_weight_fprop(w2, mxfp_qat_config)
209+
up_res = mxfp_grouped_matmul(
210+
permuted_tokens,
211+
w1,
212+
tokens_per_expert,
213+
mxfp_qat_config,
214+
name="gate_up.up_proj",
215+
fprop_x=permuted_tokens_fprop,
216+
fprop_weight=w1_fprop,
217+
)
218+
gate_res = mxfp_grouped_matmul(
219+
permuted_tokens,
220+
w2,
221+
tokens_per_expert,
222+
mxfp_qat_config,
223+
name="gate_up.gate_proj",
224+
fprop_x=permuted_tokens_fprop,
225+
fprop_weight=w2_fprop,
226+
)
227+
else:
228+
up_res = NPUGmmFunction.apply(permuted_tokens, w1, tokens_per_expert)
229+
gate_res = NPUGmmFunction.apply(permuted_tokens, w2, tokens_per_expert)
230+
act_res = torch_npu.npu_swiglu(torch.cat([gate_res, up_res], dim=-1))
231+
if mxfp_qat_config is not None:
232+
act_res_fprop, w3_fprop = prepare_mxfp_fprop_operands(act_res, w3, mxfp_qat_config)
233+
down_res = mxfp_grouped_matmul(
234+
act_res,
235+
w3,
236+
tokens_per_expert,
237+
mxfp_qat_config,
238+
name="down_proj",
239+
fprop_x=act_res_fprop,
240+
fprop_weight=w3_fprop,
241+
)
242+
else:
243+
down_res = NPUGmmFunction.apply(act_res, w3, tokens_per_expert)
200244

201245
routed_hidden_states = torch_npu.npu_moe_token_unpermute(down_res, row_ids_map, probs=routing_weights)
202246

‎verl/trainer/config/engine/fsdp.yaml‎

Lines changed: 56 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,20 @@ strategy: fsdp
6262
# Mixed precision training param dtype
6363
dtype: bfloat16 # ["bfloat16", "float16"]
6464

65-
# QAT (Quantization-Aware Training) configuration
65+
# QAT (Quantization-Aware Training) configuration.
66+
#
67+
# MXFP example (FSDP2):
68+
# strategy: fsdp2
69+
# qat.enable: true
70+
# qat.mode: mxfp_w8a8
71+
# qat.group_size: 32
72+
# qat.quant_backend: npu
73+
# qat.fake_quant_targets: [Fprop, Dgrad, Wgrad]
74+
# qat.backward_reduction_axis_fake_quant: true
75+
# qat.rotation_enable: true
76+
# qat.rotation_targets: [Fprop, Dgrad, Wgrad]
77+
# qat.experts.enable: true
78+
# The MXFP expert path is applied at the packed NPU grouped-matmul boundary.
6679
qat:
6780

6881
# Required when using verl.utils.omega_conf_to_dataclass to instantiate dataclass configs
@@ -71,10 +84,10 @@ qat:
7184
# Whether to enable QAT
7285
enable: false
7386

74-
# Quantization mode: "w4a16" (weight-only). "w4a4" is experimental and not recommended.
87+
# Quantization mode: "w4a16" (legacy weight-only), or "mxfp_w8a8", "mxfp_w4a8", "mxfp_w4a4".
7588
mode: "w4a16"
7689

77-
# Quantization group size (NVFP4 requires 16)
90+
# Quantization group size. MXFP requires 32; legacy NVFP4 uses 16.
7891
group_size: 16
7992

8093
# Patterns to ignore (e.g., lm_head, embed_tokens)
@@ -89,3 +102,43 @@ qat:
89102

90103
# Path to vLLM quantization config JSON file
91104
quantization_config_path: null
105+
106+
# MXFP quantization backend: "npu" for MXFP8 on Ascend, "torch" for MXFP4 or CPU tests.
107+
quant_backend: "npu"
108+
109+
# MXFP rounding mode: rint, round, random, or hash (torch backend only for stochastic modes).
110+
rounding_mode: "rint"
111+
112+
# MXFP pseudo-quantization locations. Valid values are Fprop, Dgrad, and Wgrad.
113+
fake_quant_targets: [Fprop]
114+
115+
# Cache a separately quantized operand for the backward reduction axis when true.
116+
backward_reduction_axis_fake_quant: false
117+
118+
# Enable deterministic block-local rotation before the selected MXFP transforms.
119+
rotation_enable: false
120+
121+
# Rotation locations. Valid values are Fprop, Dgrad, and Wgrad.
122+
rotation_targets: [Fprop]
123+
124+
# Rotation block size. MXFP experiments normally keep this equal to group_size (32).
125+
rotation_block_size: 32
126+
127+
# Seed for the deterministic block rotation matrix.
128+
rotation_seed: 0
129+
130+
# Reserved quantization-error probe switches for the later probe integration.
131+
probe_quant_error: false
132+
probe_quant_error_output_path: null
133+
134+
# Optional per-layer fallback policy. null keeps all eligible layers on the configured MXFP path.
135+
fallback_layers: null
136+
137+
# Packed MoE expert QAT. This is consumed by the FSDP2 NPU grouped-matmul path.
138+
experts:
139+
140+
# Replace the packed expert grouped matmuls with MXFP QAT grouped matmuls.
141+
enable: false
142+
143+
# Current expert implementation. Keep grouped_matmul for the Ascend NPU path.
144+
npu_backend: "grouped_matmul"

‎verl/utils/qat/__init__.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,18 @@
3737
invalidate_all_scales,
3838
load_quantization_config,
3939
)
40+
from verl.utils.qat.mxfp_linear import MXFPQATConfig, MXFPQATLinear
41+
from verl.utils.qat.mxfp_moe import attach_mxfp_expert_qat, mxfp_grouped_matmul
42+
from verl.utils.qat.mxfp_quant import (
43+
MXFPMode,
44+
dequantize_mxfp4,
45+
dequantize_mxfp8,
46+
fake_quantize,
47+
normalize_mxfp_mode,
48+
quantize_mxfp4,
49+
quantize_mxfp8,
50+
)
51+
from verl.utils.qat.mxfp_rotation import RotationConfig, rotate_blocks
4052
from verl.utils.qat.vllm_patch import (
4153
apply_qat_patches,
4254
manual_process_weights_after_loading,
@@ -54,4 +66,17 @@
5466
"apply_qat_patches",
5567
"manual_process_weights_after_loading",
5668
"prepare_qat_for_load_weights",
69+
"MXFPMode",
70+
"MXFPQATConfig",
71+
"MXFPQATLinear",
72+
"mxfp_grouped_matmul",
73+
"attach_mxfp_expert_qat",
74+
"quantize_mxfp8",
75+
"dequantize_mxfp8",
76+
"quantize_mxfp4",
77+
"dequantize_mxfp4",
78+
"fake_quantize",
79+
"normalize_mxfp_mode",
80+
"RotationConfig",
81+
"rotate_blocks",
5782
]

0 commit comments

Comments
 (0)