GGUF（GPT-Generated Unified Format）是一种专为大规模语言模型设计的二进制文件格式，支持将模型分割成多个分片（
*-of-*.gguf）。当从开源社区（如 HuggingFace 或 ModelScope）下载量化模型时，常会遇到分片存储的情况。本教程将引导你使用 llama.cpp 工具包中的llama-gguf-split，将这些分片合并为一个完整的 GGUF 模型文件。
前言与适用场景
- 适用对象：已下载多分片的 GGUF 量化模型用户；
- 使用工具：
llama-gguf-split（合并）及llama-gguf-hash（校验）； - 关键收益：快速、无损地将切分后的模型恢复为单一文件，便于后续推理调用或二次分发。
提示：以下所有 文件路径、版本号、模型名称 等均可根据实际情况替换，请务必自行确认再执行。
环境准备
- 操作系统：Ubuntu 20.04 / 22.04 LTS
- Python 版本：3.8 及以上
sudo apt update
sudo apt install -y unzip # 确保已安装解压工具
工具获取
1. 安装 ModelScope（可选）
如果你尚未下载分片模型，可先安装并使用 ModelScope 客户端：
pip install modelscope
2. 从官方仓库下载 llama.cpp 预编译工具
- 访问 llama.cpp Releases，找到最新版本（示例：
b5162）。 - 执行以下命令：
# 示例版本 b5162，请替换为最新版本号
wget https://github.com/ggerganov/llama.cpp/releases/download/b5162/llama-b5162-bin-ubuntu-vulkan-x64.zipmkdir -p ~/llama_tools # 自定义工具存放目录
unzip -j llama-b5162-bin-ubuntu-vulkan-x64.zip 'build/bin/*' -d ~/llama_tools
chmod +x ~/llama_tools/*
说明：
-j选项可将所有二进制文件直接解压到目标文件夹；- 确保对解压后的文件赋予可执行权限（
chmod +x）。
合并模型分片
-
切换到工具目录：
cd ~/llama_tools -
执行合并命令：
./llama-gguf-split --merge \~/models/DeepSeek-V3-Q3/DeepSeek-V3-0324-Q3_K_M-00001-of-00007.gguf \~/models/DeepSeek-V3-Q3/DeepSeek-V3-Q3_Merged.gguf
参数说明：
--merge：合并模式；- 第一个参数：任意一个分片文件路径；
- 第二个参数：合并后完整 GGUF 文件的输出路径。
合并验证
1. 完整性校验
# 使用内置的哈希校验，确保文件无损
./llama-gguf-hash ~/models/DeepSeek-V3-Q3/DeepSeek-V3-Q3_Merged.gguf
- 校验成功后，会输出对应哈希值；
- 若不匹配，请重新下载或检查分片完整性。
2. 简单加载测试
# 使用 llama.cpp 提供的命令行工具进行推理测试
./llama-cli -m ~/models/DeepSeek-V3-Q3/DeepSeek-V3-Q3_Merged.gguf -p "Hello"
如果出现合理的响应，即代表合并及校验成功，可以正常用于下游任务。
存储空间清理
1. 删除压缩包，仅保留可执行文件
rm ~/llama-b5162-bin-ubuntu-vulkan-x64.zip
ls -lh ~/llama_tools # 确认工具目录中仍有可执行文件
2. 移除原始分片（确认无误后执行）
# 确保合并模型已通过校验与测试
rm ~/models/DeepSeek-V3-Q3/DeepSeek-V3-0324-Q3_K_M-*.gguf
ls -lh ~/models/DeepSeek-V3-Q3/*Merged.gguf
注意：删除分片前，请务必确认单文件模型运行正常。否则会导致不可逆的数据丢失。
小结
至此，你已成功合并并验证 GGUF 模型分片，接下来即可在任何支持 llama.cpp 的环境中使用该完整模型进行高效推理。若有其他疑问或需批量处理不同模型，请参考 llama-gguf-split --help 查看更多参数选项。
