DeepSeek V4模型转换为AWQ格式的完整教程

将DeepSeek V4的原始PyTorch权重转换为AWQ格式，是在有限显存条件下实现低延迟、高精度推理的成熟方案。AWQ（激活感知权重量化）的核心原理非常巧妙：它并非对所有参数进行均等压缩，而是通过分析模型在前向传播中的激活分布，精准识别并保留对输出结果影响最显著的“关键权重”。这种方法使得模型即使在4比特甚至3比特的精度下，也能最大限度地保持其原始性能。接下来，我们将详细解析完成这一转换的具体操作流程。

一、搭建量化所需的环境与依赖

工欲善其事，必先利其器。AWQ转换对运行环境有特定要求，版本不匹配极易导致内核编译失败或校准过程出错。首要条件是配置一个支持FP16/INT4混合计算的CUDA环境，并安装与DeepSeek V4的MoE（混合专家）架构兼容的量化工具链。

第一步，创建一个独立的Python虚拟环境并激活：
conda create -n deepseek-awq python=3.10 && conda activate deepseek-awq

第二步，安装与CUDA 12.1兼容的PyTorch版本：
pip install torch==2.3.1+cu121 torchvision==0.18.1+cu121 torchaudio==2.3.1+cu121 --extra-index-url https://download.pytorch.org/whl/cu121

第三步，安装AWQ核心量化库及配套工具：
pip install git+https://github.com/mit-han-lab/awq.git@main
pip install transformers==4.41.2 accelerate==0.30.1 autoawq==0.2.7

最后，验证GPU环境是否准备就绪：
python -c "import torch; print(torch.cuda.is_a vailable(), torch.cuda.get_device_name(0))"

二、下载并准备DeepSeek V4模型权重

目前，DeepSeek官方并未直接提供AWQ格式的模型文件，因此我们需要从Hugging Face平台获取原始的Hugging Face格式模型。这里有一个关键注意事项：DeepSeek V4采用了混合专家模型架构，其配置文件中的num_local_experts和num_experts_per_tok等字段必须被AWQ工具正确识别。如果量化工具无法处理MoE结构，校准过程可能会跳过专家层，导致模型精度严重受损。

首先，执行模型下载命令（需提前配置好Hugging Face访问令牌并启用Git LFS）：
huggingface-cli download --resume-download deepseek-ai/DeepSeek-V4 --local-dir ./deepseek-v4-hf

下载完成后，检查关键模型文件是否完整：
ls ./deepseek-v4-hf/config.json ./deepseek-v4-hf/pytorch_model-00001-of-00003.bin ./deepseek-v4-hf/tokenizer.model

接着，确认模型的架构类型：
grep -E '"architectures"|num_local_experts' ./deepseek-v4-hf/config.json

如果architectures字段显示为"DeepseekV4ForCausalLM"，则权重格式可直接使用。如果显示的是"LlamaForCausalLM"，则可能需要先运行架构适配脚本进行调整，以确保MoE结构被正确识别。

三、执行AWQ校准与量化转换流程

这是整个转换过程的核心步骤。AWQ的“激活感知”特性，意味着它需要一批有代表性的输入样本来“激活”模型，收集每一层神经元输入值的分布情况，从而判断哪些权重更为重要。对于MoE模型而言，校准数据集必须能够充分触发不同的专家路由行为，否则专家权重的量化精度将无法保证。

第一步，准备校准数据集。至少需要256条文本样本，推荐使用DeepSeek官方提供的校准子集：
wget https://huggingface.co/datasets/deepseek-ai/deepseek-calib/resolve/main/deepseek-calib-256.jsonl -O ./calib.jsonl

第二步，运行AWQ量化命令。此处必须指定MoE兼容模式并启用专家层保护参数，以确保混合专家结构得到正确处理：
python -m awq.entry --model_path ./deepseek-v4-hf --w_bit 4 --q_group_size 128 --zero_point --version awq --calib_data ./calib.jsonl --export_path ./deepseek-v4-awq --moa_enable --expert_protect

在量化过程中，请留意日志中是否出现类似的关键提示，这表明专家层正在被正确处理：
[AWQ] Protected layer: model.layers.12.mlp.experts.7.w1
[AWQ] Calibration completed for 42 expert layers

校准与量化完成后，检查输出目录，应能看到以下生成的文件：
ls ./deepseek-v4-awq/awq_model.bin ./deepseek-v4-awq/config.json ./deepseek-v4-awq/tokenizer.model

四、验证AWQ模型权重的完整性与正确性

转换生成.bin权重文件后，强烈建议进行完整性校验。特别是对于MoE模型，必须确保所有专家权重都被成功量化，没有因校准失败或写入中断而丢失。重点检查MoE路由层和专家权重张量是否存在且内容非空。

首先，可以快速加载量化后的模型并查看首层的专家数量：
python -c "from awq import AWQModel; m = AWQModel('./deepseek-v4-awq'); print(len(m.model.model.layers[0].mlp.experts))"

其次，直接检查awq_model.bin文件中关键权重张量的存在性和形状：
python -c "import torch; s = torch.load('./deepseek-v4-awq/awq_model.bin', map_location='cpu'); print('w1_qweight' in s, s['model.layers.0.mlp.experts.0.w1_qweight'].shape)"

最后，进行一次轻量级的前向传播推理测试，这是最直接的验证方法：
python -c "from transformers import AutoTokenizer; from awq import AWQModel; t = AutoTokenizer.from_pretrained('./deepseek-v4-awq'); m = AWQModel('./deepseek-v4-awq'); i = t.encode('Hello', return_tensors='pt'); print(m.model(input_ids=i).logits.shape)"

如果输出形状类似torch.Size([1, 1, 128256])且没有抛出任何运行时错误，那么恭喜你，AWQ权重已成功加载。

五、部署AWQ模型至推理引擎进行服务

需要注意的是，并非所有推理后端都原生支持AWQ格式，尤其是结合了MoE架构的情况。目前，vLLM（截至v0.6.3版本）尚未支持AWQ的专家感知调度，强行使用可能导致MoE路由失效。因此，更稳妥的选择是使用awq-engine自带的AWQRunner，它能保证专家层的调用逻辑与原始Hugging Face实现保持一致。

首先，确保已安装AWQ引擎的运行时依赖：
pip install awq-engine==0.1.4

然后，可以启动一个本地推理服务，例如绑定到8080端口，并启用4-bit的KV缓存以进一步节省显存占用：
awq-runner --model-path ./deepseek-v4-awq --port 8080 --max-total-tokens 4096 --enable-kv-cache --kv-cache-dtype int4

服务成功启动后，发送一个测试请求来验证推理功能是否正常：
curl -X POST http://localhost:8080/generate -H "Content-Type: application/json" -d '{"prompt":"Explain quantum entanglement in simple terms.","max_new_tokens":128}'

观察返回的JSON响应是否包含连贯的"text"内容，同时查看服务端日志。如果出现类似AWQ expert dispatch: activated 8/64 experts的提示，就表明MoE路由机制工作正常。至此，你的DeepSeek V4 AWQ量化模型已经准备就绪，可以用于高效的推理任务了。