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 查看更多參數選項。
