CGXBeta

模型转换指南

- 分钟等级: 高级

DeepSeek-V3 提供了强大的能力用于各种 AI 任务，但要有效使用这些模型，您可能需要将它们转换为不同的格式。本指南解释了 DeepSeek-V3 模型的转换过程，帮助您准备用于本地推理和部署的权重。

了解 DeepSeek-V3 模型权重

在深入转换程序之前，了解 DeepSeek-V3 模型权重的结构是有帮助的。

权重组件

DeepSeek-V3 权重由两个主要组件组成：

  • 主模型权重：包含嵌入层、61 个变压器层和输出层

    • 总参数：671B
    • 每个标记的活跃参数：36.7B

  • 多标记预测（MTP）模块：用于推测解码的附加模块

    • 附加参数：11.5B 独特参数
    • 与主模型共享嵌入和输出层

来源：README_WEIGHTS.md

将 FP8 权重转换为 BF16

DeepSeek-V3 模型原生训练和存储在 FP8 格式中，采用 128x128 块缩放。然而，并非所有框架和硬件都完全支持 FP8 推理。转换为 BF16 格式可实现更广泛的兼容性。

何时转换为 BF16

考虑在以下情况下转换为 BF16：

  • 您的硬件没有高效的 FP8 支持
  • 您使用的框架更适合 BF16
  • 您需要微调模型（大多数微调框架期望 BF16 或 FP16）

FP8 到 BF16 转换过程

转换过程使用缩放因子对 FP8 权重进行去量化以恢复精度。

BASH
cd inference
python fp8_cast_bf16.py --input-fp8-hf-path /path/to/fp8_weights --output-bf16-hf-path /path/to/bf16_weights

转换原理

  1. 脚本加载 FP8 权重及其对应的缩放因子
  2. 它使用公式 weight_block * weight_scale_inv 进行去量化
  3. 生成的 BF16 权重保存到指定的输出目录
  4. 模型索引文件更新，删除对缩放因子的引用

来源：fp8_cast_bf16.py, kernel.py

将 HuggingFace 权重转换为 DeepSeek 格式

要使用 DeepSeek-V3 优化的 DeepSeek 推理引擎或其他专用框架，您需要将 HuggingFace 格式权重转换为 DeepSeek 的自定义格式。

转换过程

convert.py 脚本转换模型结构，为高效并行推理做准备：

BASH
python convert.py --hf-ckpt-path /path/to/DeepSeek-V3 --save-path /path/to/DeepSeek-V3-Demo --n-experts 256 --model-parallel 16

了解关键参数

  • hf-ckpt-path：原始 HuggingFace 模型权重的路径
  • save-path：存储转换后模型的路径
  • n-experts：专家混合架构中的专家总数（DeepSeek-V3 为 256）
  • model-parallel：如何在设备间分割模型（例如，16 表示 16 路并行）

来源：convert.py, README.md

转换内容

  1. 参数重命名：将 HuggingFace 参数名称映射到 DeepSeek 的命名约定

    PYTHON
    mapping = {
    "embed_tokens": ("embed", 0),
    "input_layernorm": ("attn_norm", None),
    "q_proj": ("wq", 0),
    # 更多...
}

  2. 专家分片：将 MoE 专家分布到不同的模型并行等级

    PYTHON
    # 对于专家参数
if "experts" in name and "shared_experts" not in name:
    idx = int(name.split(".")[-3])
    if idx < i * n_local_experts or idx >= (i + 1) * n_local_experts:
        continue

  3. 张量分割：为模型并行分割大矩阵

    PYTHON
    # 对于需要分割的参数
if dim is not None:
    shard_size = param.size(dim) // mp
    new_param = param.narrow(dim, i * shard_size, shard_size).contiguous()

来源：convert.py, convert.py

端到端转换工作流程

以下是设置 DeepSeek-V3 进行推理的完整工作流程：

  1. 从 Hugging Face 下载原始模型权重

    BASH
    # 使用 git-lfs 的示例
git lfs install
git clone https://huggingface.co/deepseek-ai/DeepSeek-V3

  2. 将 FP8 转换为 BF16（如果需要）

    BASH
    cd DeepSeek-V3/inference
python fp8_cast_bf16.py --input-fp8-hf-path ../DeepSeek-V3 --output-bf16-hf-path ../DeepSeek-V3-BF16

  3. 转换为 DeepSeek 格式

    BASH
    # 对于 BF16 权重
python convert.py --hf-ckpt-path ../DeepSeek-V3-BF16 --save-path ../DeepSeek-V3-Demo --n-experts 256 --model-parallel 16
 
# 或直接从 FP8 权重
python convert.py --hf-ckpt-path ../DeepSeek-V3 --save-path ../DeepSeek-V3-Demo --n-experts 256 --model-parallel 16

  4. 运行推理

    BASH
    torchrun --nnodes 2 --nproc-per-node 8 --node-rank $RANK --master-addr $ADDR generate.py --ckpt-path ../DeepSeek-V3-Demo --config configs/config_671B.json --interactive --temperature 0.7 --max-new-tokens 200

来源：README.md

不同框架的转换

不同的推理框架可能需要特定的格式。以下是流行框架的快速指南：

框架FP8 支持BF16 支持备注
DeepSeek-Infer✅✅参考实现
SGLang✅✅也支持 AMD GPU
LMDeploy✅✅高效云部署
TensorRT-LLM即将推出✅支持 INT4/8 量化
vLLM✅✅支持流水线并行
LightLLM✅✅支持多节点部署

来源：README.md

模型大小变体

DeepSeek-V3 模型有不同的变体。在转换时，请确保使用正确的配置文件：

  • DeepSeek-V3-671B：使用 configs/config_671B.json
  • DeepSeek-V3-236B：使用 configs/config_236B.json
  • DeepSeek-V3-16B：使用 configs/config_16B.json

来源：inference/configs/

常见转换问题排查

缺少缩放逆张量

如果在 FP8 到 BF16 转换过程中遇到关于缺少 scale_inv 张量的错误，请检查您的 FP8 权重是否完整。

警告：缺少 [weight_name] 的 scale_inv 张量，跳过转换

这表明相应权重的缩放因子缺失，可能是由于权重文件部分下载或损坏造成的。

模型并行分割错误

在转换为 DeepSeek 格式时，您可能会看到：

AssertionError: 专家数量必须能被模型并行度整除

确保您的 n-experts 参数（DeepSeek-V3 为 256）能被您的 model-parallel 参数整除。

来源：convert.py

结论

转换 DeepSeek-V3 模型权重是本地部署和推理的关键第一步。无论您是需要 BF16 精度以实现更广泛的兼容性，还是在为专用推理引擎准备模型，提供的工具都使转换过程变得简单。

通过了解底层权重结构和转换过程，您可以针对特定硬件和使用案例优化模型，最终实现更高效和有效的使用这些强大的语言模型。

推理API参考
优化推理性能