minimax-m2-kunlun-INT8/README.md

MiniMax-M2.7 FP8 转昆仑芯 INT8

依据安装版本：

• vllm==0.25.1，vllm-kunlun==0.25.1.dev0，仓库提交 fbb6fa6。
• Linear：KunlunScaledMMLinearKernel。
• MoE：KunlunCompressedTensorsW8A8Int8MoEMethod；保留专家 w1/w2/w3 的原始名称，由 vLLM 完成融合及 TP 切分。
• 输出 compressed-tensors / int-quantized：逐输出通道对称 INT8 权重，逐 token 动态对称 INT8 激活，无需校准数据集。

转换关系：

W_fp32[i,j] = W_fp8[i,j] * weight_scale_inv[i//128,j//128]
s[i,0] = max(abs(W_fp32[i,:])) / 127
W_int8[i,j] = clamp(round(W_fp32[i,j] / s[i,0]), -127, 127)

尽管源 scale 名字有 _inv，其保存值用于乘法反量化，不能取倒数。全零行输出 q=0,s=1。 输出 scale 名称为 weight_scale、FP32 类型、形状 [out_features,1]。 磁盘保存 absmax/127；插件加载后自行乘 127 得到运行时 absmax，不能在转换时提前乘。

Embedding、lm_head、router gate、routing bias 和 norm 保留原始类型和值。脚本读取索引指定的张量，不会把目录里未被索引引用的旧分片一起导入。支持 scale 跨分片读取，分片内逐矩阵处理、矩阵内分行处理；不把完整模型加载进内存，不分配 XPU。

使用

脚本部署位置： /mnt/disk0/models/MiniMax/quant_tools/minimax_m27_kunlun_int8/。

预检只读取配置及所有索引分片的文件头，不写输出：

/opt/vllm_kunlun/bin/python \
  /mnt/data0/models/MiniMax/quant_tools/minimax_m27_kunlun_int8/convert_fp8_to_int8.py \
  --source /mnt/data0/models/MiniMax/MiniMax-M2.7 \
  --output /mnt/data0/models/MiniMax/MiniMax-M2.7-INT8 \
  --dry-run

全量转换：

/opt/vllm_kunlun/bin/python \
  /mnt/data0/models/MiniMax/quant_tools/minimax_m27_kunlun_int8/convert_fp8_to_int8.py \
  --source /mnt/data0/models/MiniMax/MiniMax-M2.7 \
  --output /mnt/data0/models/MiniMax/MiniMax-M2.7-INT8 \
  --threads 8

中断后用同一命令添加 --resume。已完成的分片会检查文件大小、张量名称、类型及形状后跳过；未完成分片重新计算。--chunk-rows 默认为 1024，如需调整，恢复时必须保持一致。源文件位置、大小、时间戳、模型配置或索引变化后会拒绝恢复。恢复检查不包含整文件数据校验和。

预检结果为 47,864 个 FP8 矩阵、125 个输出分片，预计张量数据 214.63 GiB；检查时磁盘剩余 352.09 GiB。转换需要独立输出目录，原始模型保持不变。每完成一个分片都会更新 conversion_state.json，最后生成新的配置、索引和 conversion_report.json。只有打印 Complete 后才启动模型。

转换完成后的首次服务验证可运行：

bash /mnt/disk0/models/MiniMax/quant_tools/minimax_m27_kunlun_int8/serve_int8.sh

启动脚本使用 TP=4、BF16、8192 上下文和 eager 模式，先控制 KV cache 和图编译相关变量。服务启动及生成通过后再调整上下文和并发。

验证

cd /mnt/data0/models/MiniMax/quant_tools/minimax_m27_kunlun_int8
/opt/vllm_kunlun/bin/python test_conversion.py
/opt/vllm_kunlun/bin/python validate_kunlun_contract.py
/opt/vllm_kunlun/bin/python validate_sample_weights.py \
  --source /mnt/data0/models/MiniMax/MiniMax-M2.7 \
  --report sample_validation.json

• test_conversion.py：独立反量化参考值与半个量化步长误差界、全零行、非整块尺寸、非法 scale、跨分片转换、配置与索引、断点恢复、源文件不变及拒绝覆盖。
• validate_kunlun_contract.py：使用小型 CPU 测试层、模拟 TP rank/world size，核实当前插件的配置匹配、Linear/MoE 内核选择、参数布局、scale 转换和忽略名单；不代表完整引擎加载或设备算子执行通过。
• validate_sample_weights.py：真实 layer 0 的 Q/K/V/O 和 expert 0 的 w1/w2/w3，共七个矩阵，检查转换后的逐行舍入误差并记录 relative RMSE。

2026-10-29 完成上述三项验证，全部通过。七个真实矩阵相对于 FP8 乘 scale 后参考权重的 relative RMSE 为 0.85%–1.08%，全部满足半个逐行量化步长的舍入误差界。该指标仅衡量这些矩阵的二次量化误差。

这是从现有 FP8 权重再次量化得到的 absmax INT8 基线，并非从原始高精度权重直接量化。数学误差检查不代表任务质量评测；完整模型转换、P800 推理及任务精度仍需分别验证。