描述

在 amct_pytorch/experimental/fakequant/ 下新增 mxfp4_qat/，提供一个最小可用的 MXFP4 量化感知训练（QAT）实现：MXFP4QATLinear 可直接替换 torch.nn.Linear，前向按 MXFP4 数值伪量化，反向通过 STE（straight-through estimator）把梯度回传到高精度主权重，使模型在训练阶段就适应 MXFP4 的量化误差。

改动原因：现有 mxfp4_ascendc/ 只解决推理侧的伪量化精度验证，缺少训练侧入口。对直转（PTQ）掉点较大的模型，需要 QAT 让权重"适应"MXFP4 后再导出，本 PR 补齐这一环。

所采取的方法：

• STE 用显式 torch.autograd.Function。业界常见写法是 x + (x_q - x).detach()，数值上等价；这里改成显式 forward/backward，一是让梯度路径可读，二是为了能在 backward 里实现 clipped STE。
• 支持 clipped STE（clip_grad=True）。因为 block scale 被强制取整到 2 的幂且可能向下取整，block 内最大值有相当概率超出 6*scale 而被截断，这些位置的梯度方向具有误导性，屏蔽后训练更稳。
• 算子后端自动切换。backend="auto" 在 NPU 张量上自动复用本仓已有的 Ascend-C 算子（按 MXFP4_ASCENDC_PATH → 同级 ../mxfp4_ascendc/python 查找），否则退回纯 PyTorch，两条路径数值 bit-exact 一致。算子未编译或显式指定 backend="npu" 不可用时，抛出带修复指引的 RuntimeError。
• state_dict 与 float 层完全一致。量化器无参数、无 buffer，且 MXFP4QATLinear 是 nn.Linear 子类，因此 float checkpoint 可直接 load 进 QAT 模型，QAT 权重也能 load 回 float 模型交给 deploy 链路。from_linear 接管原 Parameter 对象而非拷贝，转换不额外占显存。
• fake_quant.py 仅依赖 torch，可作为单文件拷进第三方训练框架（Megatron / DeepSpeed / HF Trainer）使用。
• 码本查表用 torch.bucketize（阈值恰为码本中点，落在第几个区间即码本下标）而非多次链式 torch.where，减少 elementwise kernel 数量，对训练热路径有意义。

新增文件：

如何测试

前提条件：torch（CPU 即可）。NPU 后端为可选项，需先在 mxfp4_ascendc/ 执行 bash build.sh 编译算子。

最小验证：

import sys, torch
sys.path.insert(0, "amct_pytorch/experimental/fakequant")
from mxfp4_qat import MXFP4QATConfig, MXFP4QATLinear, convert_to_mxfp4_qat

model = torch.nn.Sequential(torch.nn.Linear(64, 32))
convert_to_mxfp4_qat(model, MXFP4QATConfig(quantize_input=True))
assert isinstance(model[0], MXFP4QATLinear)

model(torch.randn(4, 64)).sum().backward()
assert torch.isfinite(model[0].weight.grad).all()

代码检查：pre-commit run --files <本次改动文件> 全部 12 个 hook 通过（含 OAT 开源合规、ruff check/format、codespell）。

文档更新

• 新增 amct_pytorch/experimental/fakequant/mxfp4_qat/README.md：MXFP4 与 STE 原理、目录结构、快速开始、完整 API 表、接入自有训练框架的三种方式（标准 nn.Linear 一行替换 / Megatron ColumnParallelLinear 等自定义 Linear 挂量化器 / 直接复用可微算子）、训练建议、限制说明。
• 更新 amct_pytorch/experimental/fakequant/README.md：目录树补充 mxfp4_qat/，并说明 mxfp4_ascendc/（推理侧精度验证）与 mxfp4_qat/（训练侧）的分工。
• 更新 amct_pytorch/experimental/fakequant/mxfp4_ascendc/README.md：补充指向 mxfp4_qat/ 的交叉引用。

类型标签

• Bug修复
• 新特性
• 性能优化
• 文档更新
• 代码重构
• 其他，请描述：