DeepSeek V4模型权重合并与分片整合导出教程

手头已经下载了DeepSeek V4的分片权重文件，比如那一堆model-00001-of-00008.safetensors，但很多本地推理或部署场景下，一个完整的单文件模型用起来才顺手。这时候，就得把分散的权重“拼图”合并起来。别担心，这事儿有好几种成熟的方法，选一个最适合你当前环境和需求的就行。

一、使用 transformers 库的 convert_checkpoint.py 工具

这是最“正统”的方法之一，尤其适合那些遵循标准Hugging Face格式的分片模型。它利用transformers库内置的转换逻辑，能自动处理索引文件，无论是safetensors还是传统的bin格式都能搞定。

首先，确保你的transformers库是最新的：pip install --upgrade transformers。

然后，检查一下你的模型目录，里面必须包含config.json以及pytorch_model.bin.index.json或model.safetensors.index.json这样的索引文件。有了这些，合并就简单了。

打开终端，执行类似下面的命令：

python -m transformers.models.auto.convert_checkpoint --model_name_or_path ./deepseek-v4-sharded --output_dir ./deepseek-v4-merged --dtype bfloat16

命令跑完后，去你指定的输出目录./deepseek-v4-merged里看看，一个完整的model.safetensors或pytorch_model.bin文件应该已经在那儿等着你了。

二、通过 safetensors 官方工具合并分片

如果你只想进行纯粹的物理文件合并，不涉及模型架构的验证或转换，那么直接使用safetensors格式的官方工具会更直接。这种方法不依赖具体的模型定义，就是简单粗暴地把多个.safetensors文件拼成一个。

第一步，安装工具包：pip install safetensors。

接下来，自己写个简单的Python脚本，比如叫merge_safetensors.py。在脚本里调用safetensors.torch.combine_sharded这个函数，并把所有分片文件的路径列给它，像这样：

["./model-00001-of-00008.safetensors", "./model-00002-of-00008.safetensors", ..., "./model-00008-of-00008.safetensors"]

最后，运行脚本并指定输出路径：python merge_safetensors.py --output ./deepseek-v4-full.safetensors。合并后的单文件就生成了。

三、使用 huggingface_hub 的 snapshot_download + 权重加载导出

这个方法特别适合一种情况：你打算直接从Hugging Face Hub下载模型，并且希望下载完成后自动得到一个合并好的版本，省去手动处理索引文件的麻烦。它的原理是先下载，再加载，最后保存为一个整体。

确保安装必要依赖：pip install huggingface_hub torch。

然后，运行一段Python代码。先用snapshot_download函数把模型从仓库（比如"deepseek-ai/DeepSeek-V4"）完整下载到本地目录（例如./v4-dl）。

接着，用AutoModelForCausalLM.from_pretrained加载这个刚下载的（分片）模型。这里可以指定数据类型，比如torch.bfloat16。

最后，关键一步，调用model.sa ve_pretrained并设置safe_serialization=True。这样，模型就会被重新序列化并保存为一个独立的、合并后的文件夹。

四、基于 openMind Library 的 NPU 适配合并流程

如果你的目标部署平台是华&为昇腾（Ascend）NPU，那么这条路是为你量身定做的。openMind库专门为昇腾生态设计，它的合并过程不仅仅是拼合文件，还能集成算子融合和张量格式转换，确保导出的模型能被CANN工具链直接识别和使用。

从安装开始：pip install openmind。

在代码中，你需要从openMind导入专用的模型类，比如OMModelForCausalLM，并指定设备为"ascend"。

加载模型时有一个便利参数：merge_before_load=True。设置它，库会在加载过程中自动完成分片权重的合并。

加载完成后，你可以直接调用model.export_to_om函数，指定输出路径（如./deepseek-v4-npu.om）和预期的输入张量形状，一键导出为NPU专用的.om模型文件，后续部署就非常顺畅了。