msmodelslim-model-dequant

name	msmodelslim-model-dequant
description	为 msModelSlim 适配流程注入反量化能力。先识别模型权重是否可反量化，再实现反量化脚本并接入 model_adapter。当前仅覆盖 FP8 的 per-block 与 per-channel 两类；若格式不确定或无公开反量化规则，要求用户提供反量化脚本或浮点权重。

msModelSlim 反量化接入 Skill

本 Skill 用于在模型适配前处理 FP8 量化权重，将可识别权重恢复为 bf16/fp16 再进入后续适配与量化流程。

适用范围

• 支持：
  • FP8 per-block（块级 scale）
  • FP8 per-channel（通道级 scale）
• 不支持（默认阻塞）：
  • 无法确认反量化规则的自定义量化格式
  • 缺少必要 scale/shape 元数据的量化权重
  • 仅有推理框架专用格式且无训练侧可逆映射说明
  • 非 FP8（例如 INT4/INT8/FP4）在本 Skill 中默认不处理

必需输入

• 模型目录（至少含 config.json、model.safetensors.index.json）
• 目标模型的 model_adapter.py

硬门禁：先识别“可接受反量化权重”

在编写任何脚本前，必须先判定是否属于可接受类型：

1. 读取 config.json，提取可用量化配置字段（如量化类型、group/block 相关参数）
2. 读取 model.safetensors.index.json 的 weight_map
3. 按键名模式识别：
   • FP8 per-block 可接受：存在与权重匹配的块级 scale（常见键后缀如 xxx.weight_scale_inv / xxx.scale），且可推导块大小 block_size
   • FP8 per-channel 可接受：存在与权重某一维匹配的通道级 scale（常见形态如 [out_features]、[in_features] 或可广播到对应通道维）
4. 用 scale 形状对权重形状做一致性检查：
   • per-block：M 与 N 可按 block_size 分块并与 scale 网格对应
   • per-channel：scale 的长度或广播维度与指定 channel axis 一致
5. 若未命中上述模式，标记为 未知/不接受格式 并停止实现

必须输出判定依据（命中的键模式、样例键名、对应文件）。

工作流

1) 识别与分流

• 未量化：直接跳过反量化步骤，进入后续适配
• 可接受量化（FP8 per-block/per-channel）：进入脚本实现与适配器接入
• 未知/不接受量化：阻塞并向用户提出材料请求（见“阻塞话术”）

2) 实现反量化脚本（convert_*_to_bf16.py）

按 FP8 模式创建脚本，最小要求：

• 提供 convert_* 主转换函数（必须带可见进度条与异常提示）
• 脚本只需覆盖当前模型确认的量化模式（可仅实现 per-block）
• 将结果统一转换到 torch.bfloat16（或项目默认浮点 dtype）
• 参数回写必须 dtype-safe（强约束）：
  • 若原始权重存储 dtype 为 FP8，禁止直接将反量化得到的 BF16/F16 张量回写到该 FP8 存储；否则会发生静默类型回退
  • 必须先将“原参数存储”提升到目标浮点 dtype（如 BF16），再执行赋值/拷贝
  • 允许不同代码风格实现（原地改写或整体替换），但必须保证 dtype 与 device 一致
  • 回写后必须有显式校验（断言或日志）确认最终参数 dtype 已是目标浮点类型，而非 FP8
• 对 index 与 safetensors 不匹配场景给出 warning 并安全跳过
• 进度条要求：
  • 必须使用 tqdm（或等价方案）显示转换进度，禁止仅打印日志让用户等待
  • total 必须可追踪（例如按待转换参数个数/层数），并实时更新 desc（如当前层名）
  • 长耗时阶段（扫描权重、逐层反量化、保存结果）至少覆盖主耗时环节中的一个；优先覆盖逐层反量化主循环
• 导出件要求： -如果反量化脚本可以离线运行，即可以先运行反量化导出浮点权重，则导出件中必须包含原生权重中的所有文件，特别是 chat_template.jinja 文件，该文件缺失会导致服务化异常。

建议函数骨架：

@lru_cache(maxsize=1)
def get_weight_map(model_path: str) -> Dict[str, str]:
    ...

@torch.no_grad()
def convert_module_xxx_to_bf16(name: str, module: nn.Module, model_path: str, weight_map: Dict[str, str]):
    ...

per-block 示例：

def decode_fp8_per_block(weight: torch.Tensor, scale: torch.Tensor, block_size: int = 128) -> torch.Tensor:
    m, n = weight.shape
    scale_expanded = scale.repeat_interleave(block_size, dim=0).repeat_interleave(block_size, dim=1)[:m, :n]
    return (weight.float() * scale_expanded.float()).to(torch.bfloat16)

参数回写（通用伪代码）：

dequant_weight = dequantize(fp8_weight, scale_info)   # dequant_weight: BF16/F16
if original_param_storage_is_fp8:
    promote_original_param_storage_to_target_float_dtype()
assign_or_copy_with_device_dtype_alignment(dequant_weight)
verify_param_dtype_is_target_float_dtype_not_fp8()

可选工具脚本（用于判定权重/scale 形状）：

• scripts/inspect_safetensors.py
• 用法：
  • python scripts/inspect_safetensors.py -m /path/to/model
  • python scripts/inspect_safetensors.py -m /path/to/model -p "model.layers.*.mlp*.weight*"

3) 接入 model_adapter.py

在适配器中注入反量化调用，要求：

• 在调用 transformers 加载模型前，先检查模型目录 config.json 是否包含量化字段（如 quantization_config、quant_method、fmt、weight_block_size、modules_to_not_convert 等）
• 若检测到量化字段，必须主动删除这些字段后再进行加载，避免 transformers 按量化方式装载权重
• 删除原因必须在日志中说明：昇腾当前不支持 FP8 量化权重直载，若不清理配置会导致错误加载路径
• 可接受实现方式：
  • 直接修改模型目录下 config.json 后加载；或
  • 生成去量化字段的临时 config 并确保后续加载明确使用该配置
• 无论采用哪种方式，都必须保证“最终传给 transformers 的 config 不包含量化相关字段”
• 在模型权重可用后、量化流程前调用 convert_*_to_bf16
• 仅对命中的量化子模块执行，避免全模型无谓遍历
• 转换失败不应静默吞掉；至少记录 warning 与原因

接入示例：

from .convert_fp8_to_bf16 import convert_module_fp8_to_bf16

def init_model(...):
    model = ...
    convert_module_fp8_to_bf16(name="", module=model, model_path=model_path, weight_map=...)
    return model

4) 最小验证

• 校验可读性：脚本能读取 index 与目标 safetensors
• 校验转换：目标层权重 dtype 由 FP8 变为 bf16/fp16
• 校验接入：adapter 初始化路径已触发自动转换函数
• 校验回退：非量化权重或不匹配键时不报致命错误
• 校验模式：输出明确 per-block 或 per-channel 判定结果
• 校验赋值安全：确认未出现“BF16 copy_ 到 FP8 存储后仍为 FP8”的回退问题

阻塞话术（必须原样遵循语义）

当量化格式不确定或缺反量化规则时，必须明确告知：

• 当前权重格式无法确认可逆反量化规则，不能安全实现通用反量化。
• 请用户二选一提供：
  1. 官方/已验证的反量化脚本（含权重键映射与scale定义）
  2. 对应浮点权重（bf16/fp16/fp32）
• 在补齐材料前，不进入模型适配代码改写阶段。

输出模板

Agent 每次执行本 Skill 后，输出以下结构：

## 反量化判定结果
- 量化状态：未量化 | FP8 per-block(可接受) | FP8 per-channel(可接受) | 未知(阻塞)
- 判定依据：{keys/file evidence}

## 反量化实现动作
- 新增/复用脚本：{path}
- 核心函数：{functions}
- 适配器接入点：{adapter_path + function}

## 验证结果
- 读取校验：通过/失败
- dtype 校验：通过/失败
- 适配器触发校验：通过/失败

## 后续动作
- 若阻塞：请求用户提供反量化脚本或浮点权重
- 若通过：进入模型适配主流程