【LLM】llama.cpp：合并 GGUF 模型分片

GGUF（GPT-Generated Unified Format）是一种专为大规模语言模型设计的二进制文件格式，支持将模型分割成多个分片（*-of-*.gguf）。当从开源社区（如 HuggingFace 或 ModelScope）下载量化模型时，常会遇到分片存储的情况。本教程将引导你使用 llama.cpp 工具包中的 llama-gguf-split，将这些分片合并为一个完整的 GGUF 模型文件。

---

前言与适用场景

• 适用对象：已下载多分片的 GGUF 量化模型用户；
• 使用工具：llama-gguf-split（合并）及 llama-gguf-hash（校验）；
• 关键收益：快速、无损地将切分后的模型恢复为单一文件，便于后续推理调用或二次分发。

提示：以下所有 文件路径、版本号、模型名称 等均可根据实际情况替换，请务必自行确认再执行。

---

环境准备

1. 操作系统：Ubuntu 20.04 / 22.04 LTS
2. Python 版本：3.8 及以上

sudo apt update
sudo apt install -y unzip  # 确保已安装解压工具

---

工具获取

1. 安装 ModelScope（可选）

如果你尚未下载分片模型，可先安装并使用 ModelScope 客户端：

pip install modelscope

2. 从官方仓库下载 llama.cpp 预编译工具

1. 访问 llama.cpp Releases，找到最新版本（示例：b5162）。
2. 执行以下命令：

# 示例版本 b5162，请替换为最新版本号
wget https://github.com/ggerganov/llama.cpp/releases/download/b5162/llama-b5162-bin-ubuntu-vulkan-x64.zip

mkdir -p ~/llama_tools   # 自定义工具存放目录
unzip -j llama-b5162-bin-ubuntu-vulkan-x64.zip 'build/bin/*' -d ~/llama_tools
chmod +x ~/llama_tools/*

说明：

• -j 选项可将所有二进制文件直接解压到目标文件夹；
• 确保对解压后的文件赋予可执行权限（chmod +x）。

---

合并模型分片

1. 切换到工具目录：

   cd ~/llama_tools
   

2. 执行合并命令：

   ./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 查看更多参数选项。