AMCT DeepSeek-V4 模型量化转换工具实战FP8/MXFP4 权重在 Atlas A2/A3 上的 int8 落地指南【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct导读DeepSeek-V4 模型的 Attention 模块采用 FP8 数据类型、MoE 模块采用 MXFP4 数据类型而 Atlas A2、A3 系列产品暂不支持 FP8/MXFP4 推理。本文围绕 AMCT 仓库中 deepseek-v4 转换工具 展开系统讲解如何将 DeepSeek-V4 的 FP8/MXFP4 权重一键转换为 bfloat16 / W8A8-int / W8A8-mx / W4A8-mx 等目标格式并深入剖析 convert_model.py、convert_config.py、mx_quantize.py 的源码实现帮助开发者在 Atlas A2、A3 系列产品上完整走通权重转换 → 推理验证的实战链路。一、特性背景为什么需要转换DeepSeek-V4 的模型结构极具特殊性Attention 模块权重以 FP8 格式存储每个 128×128 权重块共享一个 scale缩放因子MoE 模块路由专家与共享专家权重以 MXFP4 格式存储两个 4bit 值打包进一个 uint8每 32 个元素按列共享一个 scale。Atlas A2、Atlas A3 系列产品不支持 FP8/MXFP4 这两种数据格式因此无法直接加载原始权重进行推理。本特性将 FP8/MXFP4 权重转换为 int8 数据类型或 bfloat16支撑开发者在 Atlas A2、A3 系列产品上体验 DeepSeek-V4 模型的推理效果。从 AMCT 主仓的模型接入看DeepSeek-V4 已是官方 LLM 量化管线中的一等公民args.py 的模型注册表支持deepseek_v4模型名modeling_deepseek_v4.py 提供了完整的模型实现本转换工具产出的权重与量化参数正是后续 PTQ 与推理的输入基础。二、快速开始环境准备与依赖安装1. 下载模型首先将 DeepSeek-V4 模型下载到本地确保目录中包含分片的*.safetensors权重文件model.safetensors.index.json权重索引convert_model.py 依赖它解析weight_mapconfig.json模型配置解析num_hidden_layers、n_routed_experts、compress_ratios等字段见 convert_model.py。2. 安装依赖pip install -r requirements.txtrequirements.txt 中仅有 4 个核心依赖均为离线转换所需依赖用途torch张量运算与 dtype 转换默认 dtype 设置为 bfloat16torchao提供 FP32→FP4(E2M1) 转换原语_f32_to_floatx_unpacked见 mx_quantize.pysafetensors读写 safetensor 权重文件load_file/save_filetqdm转换进度条展示3. 执行模型转换python convert_model.py \ --input_fp8_hf_path FP8模型路径 \ --output_hf_path 输出路径 \ --quant_type 量化类型转换完成后即可得到目标类型如 int8的权重和量化参数随后基于 Atlas A2、A3 系列产品进行推理验证。三、命令行参数详解参数说明参数必填默认值说明--input_fp8_hf_path是-FP8 模型目录路径--output_hf_path是-输出目录路径--quant_type否w8a8-int量化类型--quant_param_path否None量化参数目录路径源码中预留见 convert_model.py从源码看--quant_type的合法取值在校验逻辑中有严格约束main()开头会断言quant_type in [bfloat16, w8a8-int, w8a8-mx, w4a8-mx]非法取值直接抛错见 convert_model.py。支持的量化类型类型说明bfloat16转换为 BF16无量化仅执行 FP8/MXFP4→BF16 反量化w8a8-intW8A8 整数量化默认MoE 权重 8bit权重格式为 INT8 scalew8a8-mxW8A8 MX 浮点量化权重格式为 MXFP8 scalew4a8-mxW4A8 MX 浮点量化MoE 权重 4bit权重格式为 MXFP4 scale源码中的解析逻辑convert_model.pyw4a8 quant_type.startswith(w4a8) w8a8 quant_type.startswith(w8a8) mx quant_type.endswith(mx)即w4a8控制 MoE 是否降到 4bitmx控制权重采用 MX 浮点格式还是整数格式两者正交组合出上表中的三种量化路径。四、输出结果解析转换完成后output_hf_path目录结构如下output_hf_path/ ├── model-00001-of-000xx.safetensors # 量化后权重 ├── model.safetensors.index.json # 权重索引 ├── config.json # 模型配置含量化参数 └── *.py / *.json / *.jinja # 原目录文件复制原目录中所有.py、.json、.jinja文件会被原样复制到输出目录对应 copy_py_json确保模型推理所需的代码、分词器配置、对话模板等配套文件完整保留。权重变更变更项说明量化层权重INT8 / MXFP4 / MXFP8 格式.scale张量每个量化层对应的新增缩放因子非量化层BF16 格式值得注意原始模型中的.scale如scale_inv张量在遍历时会被跳过见 convert_model.py权重重新量化后由脚本生成新的.scale张量并同步登记进新的weight_map见 convert_model.py。config.json 新增字段字段说明quant_methodcompressed-tensors或mxfp8formatint-quantized或float-quantizedignore跳过量化的层kv_cache_schemeKV cache 量化配置config_groups各层量化参数weight_block_size权重块大小MX 格式config.json 的改写逻辑分两条分支见 convert_model.pyw8a8-mx直接修改原quantization_config将quant_method置为mxfp8移除weight_block_size并写入 KV cache 与 LI cache 的 8bit 浮点量化方案w8a8-int/w4a8-mx移除原quantization_config通过 generate_quant_config 重新生成标准的compressed-tensors配置。config_groups的生成细节convert_config.py非常有参考价值group_0面向[Linear]目标权重采用Per-Channelstrategy: channel、对称symmetric: True、静态dynamic: False量化激活采用Per-Tokenstrategy: token、动态dynamic: True量化A8 恒为 8bitMX 浮点路径下追加group_1面向[MoEGMM]权重位宽为 4bitw4a8或 8bitw8a8并设置weight_block_size: [1, 32]format字段由是否 MX 决定int-quantized整数路径或float-quantizedMX 浮点路径。五、转换说明哪些层被量化哪些层只反量化量化层以下层在quant_type为w8a8-*或w4a8-*时会被重新量化层类型层名模式原始格式MoE Expertslayers.{i}.ffn.experts.{j}.w1/w2/w3MXFP4Shared Expertslayers.{i}.ffn.shared_experts.w1/w2/w3MXFP4Attentionlayers.{i}.attn.wq_a/wkv/wo_a/wq_b/wo_bFP8Indexerlayers.{i}.attn.indexer.wq_bFP8MTPmtp.0.*相关层FP8/MXFP4量化输出格式quant_type输出格式w8a8-intINT8 scalew8a8-mxMXFP8 scalew4a8-mxMXFP4 scale量化层集合由 generate_quant_layers 程序化生成其中有几个值得注意的实现细节位宽分配MoE 路由专家使用moe_bitw4a8 时为 4bit否则 8bit共享专家、Attention、MTP 恒为 8bit条件量化attn.wq_a/wkv/wo_a仅当is_mxTrue即w8a8-mx/w4a8-mx时才量化整数路径下这些层会被加入ignore列表——这对应 generate_ignore_item 中if not is_fp分支的忽略逻辑按压缩比决策layers.{i}.attn.indexer.wq_b仅在compress_ratios[i] 4时量化ratio NUM_BITS_4见 convert_model.pyMTP 模块mtp.0.ffn.experts.*、mtp.0.ffn.shared_experts.*、mtp.0.attn.*、mtp.0.e_proj、mtp.0.h_proj均在量化范围内。非量化层以下层仅执行 FP8→BF16 反量化不重新量化层类型层名模式词嵌入embed.weight输出头head,mtp.0.headIndexer 权重投影layers.{i}.attn.indexer.weights_projCompressorlayers.{i}.attn.indexer.compressor.wgate/wkv,layers.{i}.attn.compressor.wgate/wkv这些层之所以豁免重新量化从源码注释与compress_ratios可取 1/4/128的联动可以推断Indexer 与 Compressor 相关层承担着稀疏注意力路径的关键投影职能且generate_ignore_item在ratio 4或ratio 128时会附加忽略这些层见 convert_config.py保留其 BF16 精度以降低对注意力精度的影响。六、源码级原理权重转换的核心实现原始模型权重格式Attention: FP8每 128×128 权重块共享一个 scaleMoE: MXFP4两个 4bit 值打包存储于一个 uint8每 32 元素按列共享一个 scale。脚本按字典序遍历每个 safetensor 文件中的权重张量处理逻辑分三步1. 缩放因子.scale后缀遍历时直接跳过处理对应权重时通过weight_map按需读取。get_tensor内部做了文件级缓存并采用最多缓存最近 2 个文件的内存管理策略见 convert_model.py 与 L352-L355避免超大模型场景下 OOM。2. FP8 / MXFP4 权重.weight后缀判别条件是weight.element_size() 11 字节/元素见 convert_model.pyFP8dtype 为浮点类型float8_e4m3fn等直接读取随后调用 weight_dequant 以默认block_size128做反量化将 scale 按行、列分别repeat_interleave(128)扩展到与 weight 同维度后逐元素相乘得到 BF16MXFP4dtype 为 int8实际是打包的 uint8需先经 unpack_mxfloat4_to_fp32 解包提取每个字节的低 4 位 0x0F与高 4 位// 16 0x0F再通过 E2M1 查找表[0, 0.5, 1.0, 1.5, 2.0, 3.0, 4.0, 6.0]及其负数映射为 FP32 值元素数量翻倍随后调用weight_dequant(..., block_size32, is_mxTrue)按列方向repeat_interleave(32)扩展 scale 并逐元素相乘若层名在量化列表中且需要量化则在上一步得到 BF16 权重后重新量化见 convert_model.py。3. 其他权重既不是 scale 也不是 1 字节权重的普通张量如未量化的投影、embedding 等原样保留并统一转为 BF16torch.set_default_dtype(torch.bfloat16)全局生效。重新量化分支的实现差异量化分支根据mx标志二选一整数路径w8a8-int调用 int_weight_quant按行dim1Per-Channel求绝对最大值abs_maxscale abs_max / qmaxqmax 2^(bits-1) - 1经roundclamp后输出 int8MX 浮点路径w8a8-mx/w4a8-mx调用 quantize_mx以block_size32、axes[-1]按列计算共享指数8bit 映射为 E4M3max_norm448.0、4bit 映射为 E2M1max_norm6.0real_quantTrue时 8bit 输出float8_e4m3fn uint8 scale4bit 输出经 f32_to_f4_unpacked 与 pack_uint4 打包回 uint8实现与原始 MXFP4 一致的存储格式。输出文件落盘每个分片转换完成后脚本将新的状态字典写回同名model-xxxxx-of-xxxxx.safetensorsmetadata 为{format: pt}并重写model.safetensors.index.json仅保留新的weight_map与config.json随后调用copy_py_json复制配套文件见 convert_model.py。七、注意事项与限制硬件前提本转换的动机即 Atlas A2、A3 系列产品不支持 FP8/MXFP4因此转换后的权重主要用于这两类产品的推理验证支持 FP8/MXFP4 的产品可直接使用原始权重无需本工具输入前提转换依赖model.safetensors.index.json与config.json且config.json必须包含num_hidden_layers、n_routed_experts、compress_ratios三个字段缺失 scale 的处理若某权重缺失对应的.scale张量脚本会打印Warning: Missing scale_inv tensor for ...并跳过该权重的转换见 convert_model.py转换后需自行确认缺失项内存占用虽然脚本对已加载的 safetensor 文件做了 LRU 缓存保留最近 2 个但单分片内仍会常驻current_state_dict与新状态字典超大模型建议按分片顺序关注内存水位推理链路转换产物权重 compressed-tensors/mxfp8量化配置可直接对接 AMCT 主仓的 DeepSeek-V4 模型实现 modeling_deepseek_v4.py 与 LLM 命令行工具配合 示例工程 完成部署与精度验证。八、总结DeepSeek-V4 转换工具以反量化 可选重新量化为内核将 FP8/MXFP4 权重无损地落地为 Atlas A2/A3 可运行的 BF16/INT8/MXFP8/MXFP4 格式非量化层仅做 FP8→BF16 反量化量化层则按 Per-Channel 权重 Per-Token 激活的策略重新量化为 INT8 或 MX 浮点格式并在config.json中生成标准的compressed-tensors/mxfp8量化描述。整个转换流程由 convert_model.py 单脚本驱动、配置生成与 MX 量化原语分别收敛于 convert_config.py 与 mx_quantize.py结构清晰、易于二次定制。对需要在 Atlas A2/A3 上体验 DeepSeek-V4 推理的开发者而言这是一条开箱即用的量化落地路径。【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考