llama.cpp 是 Ollama、LMStudio 和其他很多熱門專案的底層實現，也是 GPUStack 所支援的推理引擎之一，它提供了 GGUF 模型檔案格式。GGUF (General Gaussian U-Net Format) 是一種用於儲存模型以進行推理的檔案格式，旨在針對推理進行最佳化，可以快速載入和執行模型。
llama.cpp 還支援量化模型，在保持較高的模型精度的同時，減少模型的儲存和計算需求，使大模型能夠在桌面端、嵌入式裝置和資源受限的環境中高效部署，並提高推理速度。
今天帶來一篇介紹如何製作並量化 GGUF 模型，將模型上傳到 HuggingFace 和 ModelScope 模型倉庫的操作教程。
註冊與配置 HuggingFace 和 ModelScope
- 註冊 HuggingFace
訪問 https://huggingface.co/join 註冊 HuggingFace 賬號（需要某上網條件）
- 配置 HuggingFace SSH 公鑰
將本地環境的 SSH 公鑰新增到 HuggingFace，檢視本地環境的 SSH 公鑰（如果沒有可以用 ssh-keygen -t rsa -b 4096 命令生成）：
cat ~/.ssh/id_rsa.pub
在 HuggingFace 的右上角點選頭像，選擇 Settings - SSH and GPG Keys，新增上面的公鑰，用於後面上傳模型時的認證。
- 註冊 ModelScope
訪問 https://www.modelscope.cn/register?back=%2Fhome 註冊 ModelScope 賬號
- 獲取 ModelScope Token
訪問 https://www.modelscope.cn/my/myaccesstoken，將 Git 訪問令牌複製儲存，用於後面上傳模型時的認證。
準備 llama.cpp 環境
建立並啟用 Conda 環境（沒有安裝的參考 Miniconda 安裝：https://docs.anaconda.com/miniconda/）：
conda create -n llama-cpp python=3.12 -y
conda activate llama-cpp
which python
pip -V
克隆 llama.cpp 的最新分支程式碼，編譯量化所需的二進位制檔案：
cd ~
git clone -b b4034 https://github.com/ggerganov/llama.cpp.git
cd llama.cpp/
pip install -r requirements.txt
brew install cmake
make
編譯完成後，可以執行以下命令確認量化所需要的二進位制檔案 llama-quantize 是否可用：
./llama-quantize --help
下載原始模型
下載需要轉換為 GGUF 格式並量化的原始模型。
從 HuggingFace 下載模型，透過 HuggingFace 提供的 huggingface-cli 命令下載，首先安裝依賴：
pip install -U huggingface_hub
國內網路配置下載映象源：
export HF_ENDPOINT=https://hf-mirror.com
這裡下載 meta-llama/Llama-3.2-3B-Instruct 模型，該模型是 Gated model，需要在 HuggingFace 填寫申請並確認獲得訪問授權：
在 HuggingFace 的右上角點選頭像，選擇 Access Tokens，建立一個 Read 許可權的 Token，儲存下來：
下載 meta-llama/Llama-3.2-3B-Instruct 模型，--local-dir 指定儲存到當前目錄，--token 指定上面建立的訪問 Token：
mkdir ~/huggingface.co
cd ~/huggingface.co/
huggingface-cli download meta-llama/Llama-3.2-3B-Instruct --local-dir Llama-3.2-3B-Instruct --token hf_abcdefghijklmnopqrstuvwxyz
轉換為 GGUF 格式與量化模型
建立 GGUF 格式與量化模型的指令碼：
cd ~/huggingface.co/
vim quantize.sh
填入以下指令碼內容，並把 llama.cpp 和 huggingface.co 的目錄路徑修改為當前環境的實際路徑，需要為絕對路徑，將 d 變數中的 gpustack 修改為 HuggingFace 使用者名稱：
#!/usr/bin/env bash
llama_cpp="/Users/gpustack/llama.cpp"
b="/Users/gpustack/huggingface.co"
export PATH="$PATH:${llama_cpp}"
s="$1"
n="$(echo "${s}" | cut -d'/' -f2)"
d="gpustack/${n}-GGUF"
# prepare
mkdir -p ${b}/${d} 1>/dev/null 2>&1
pushd ${b}/${d} 1>/dev/null 2>&1
git init . 1>/dev/null 2>&1
if [[ ! -f .gitattributes ]]; then
cp -f ${b}/${s}/.gitattributes . 1>/dev/null 2>&1 || true
echo "*.gguf filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
fi
if [[ ! -d assets ]]; then
cp -rf ${b}/${s}/assets . 1>/dev/null 2>&1 || true
fi
if [[ ! -d images ]]; then
cp -rf ${b}/${s}/images . 1>/dev/null 2>&1 || true
fi
if [[ ! -d imgs ]]; then
cp -rf ${b}/${s}/imgs . 1>/dev/null 2>&1 || true
fi
if [[ ! -f README.md ]]; then
cp -f ${b}/${s}/README.md . 1>/dev/null 2>&1 || true
fi
set -e
pushd ${llama_cpp} 1>/dev/null 2>&1
# convert
[[ -f venv/bin/activate ]] && source venv/bin/activate
echo "#### convert_hf_to_gguf.py ${b}/${s} --outfile ${b}/${d}/${n}-FP16.gguf"
python3 convert_hf_to_gguf.py ${b}/${s} --outfile ${b}/${d}/${n}-FP16.gguf
# quantize
qs=(
"Q8_0"
"Q6_K"
"Q5_K_M"
"Q5_0"
"Q4_K_M"
"Q4_0"
"Q3_K"
"Q2_K"
)
for q in "${qs[@]}"; do
echo "#### llama-quantize ${b}/${d}/${n}-FP16.gguf ${b}/${d}/${n}-${q}.gguf ${q}"
llama-quantize ${b}/${d}/${n}-FP16.gguf ${b}/${d}/${n}-${q}.gguf ${q}
ls -lth ${b}/${d}
sleep 3
done
popd 1>/dev/null 2>&1
set +e
開始將模型轉換為 FP16 精度的 GGUF 模型，並分別用 Q8_0、Q6_K、Q5_K_M、Q5_0、Q4_K_M、Q4_0、Q3_K、Q2_K 方法來量化模型：
bash quantize.sh Llama-3.2-3B-Instruct
指令碼執行完後，確認成功轉換為 FP16 精度的 GGUF 模型和量化後的 GGUF 模型：
模型被儲存在對應使用者名稱的目錄下：
ll gpustack/Llama-3.2-3B-Instruct-GGUF/
上傳模型到 HuggingFace
在 HuggingFace 右上角點選頭像，選擇 New Model 建立同名的模型倉庫，格式為 原始模型名-GGUF：
更新模型的 README：
cd ~/huggingface.co/gpustack/Llama-3.2-3B-Instruct-GGUF
vim README.md
為了維護性，在開頭的後設資料之後，記錄原始模型和 llama.cpp 的分支程式碼 Commit 資訊，注意按照原始模型的資訊和llama.cpp 的分支程式碼 Commit 資訊更改：
# Llama-3.2-3B-Instruct-GGUF
**Model creator**: [meta-llama](https://huggingface.co/meta-llama)<br/>
**Original model**: [Llama-3.2-3B-Instruct](https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct)<br/>
**GGUF quantization**: based on llama.cpp release [b8deef0e](https://github.com/ggerganov/llama.cpp/commit/b8deef0ec0af5febac1d2cfd9119ff330ed0b762)
---
準備上傳，安裝 Git LFS 用於管理大檔案的上傳：
brew install git-lfs
新增遠端倉庫：
git remote add origin git@hf.co:gpustack/Llama-3.2-3B-Instruct-GGUF
新增檔案，並透過 git ls-files 確認提交的檔案， git lfs ls-files 確認所有 .gguf 檔案被 Git LFS 管理上傳：
git add .
git ls-files
git lfs ls-files
上傳超過 5GB 大小的檔案到 HuggingFace 需開啟大檔案上傳，在命令列登入 HuggingFace，輸入上面下載模型章節建立的 Token：
huggingface-cli login
為當前目錄開啟大檔案上傳：
huggingface-cli lfs-enable-largefiles .
將模型上傳到 HuggingFace 倉庫：
git commit -m "feat: first commit" --signoff
git push origin main -f
上傳完成後，在 HuggingFace 確認模型檔案成功上傳。
上傳模型到 ModelScope
在 ModelScope 右上角點選頭像，選擇 建立模型 建立同名的模型倉庫，格式為 原始模型名-GGUF，並填寫 License、模型型別、AI 框架、是否公開模型等其他配置：
上傳本地倉庫的 README.md 檔案並建立：
新增遠端倉庫，需要使用本文最開始獲得的 ModelScope Git 訪問令牌提供上傳模型時的認證：
git remote add modelscope https://oauth2:xxxxxxxxxxxxxxxxxxxx@www.modelscope.cn/gpustack/Llama-3.2-3B-Instruct-GGUF.git
獲取遠端倉庫已存在的檔案：
git fetch modelscope master
由於 ModelScope 使用 master 分支而非 main 分支，需要切換到 master 分支並透過 cherry-pick 將main 下的檔案移到 master 分支，先檢視並記下當前的 Commit ID：
git log
切換到 master 分支，並透過 main 分支的 Commit ID 將main 分支下的檔案移到 master 分支：
git checkout FETCH_HEAD -b master
git cherry-pick -n 833fb20e5b07231e66c677180f95e27376eb25c6
修改衝突檔案，解決衝突（可以用原始模型的 .gitattributes 合併 *.gguf filter=lfs diff=lfs merge=lfs -text，參考 quantize.sh 指令碼相關邏輯 ）：
vim .gitattributes
新增檔案，並透過 git ls-files 確認提交的檔案， git lfs ls-files 確認所有 .gguf 檔案被 Git LFS 管理上傳：
git add .
git ls-files
git lfs ls-files
將模型上傳到 ModelScope 倉庫：
git commit -m "feat: first commit" --signoff
git push modelscope master -f
上傳完成後，在 ModelScope 確認模型檔案成功上傳。
總結
以上為使用 llama.cpp 製作並量化 GGUF 模型，並將模型上傳到 HuggingFace 和 ModelScope 模型倉庫的操作教程。
llama.cpp 的靈活性和高效性使得其成為資源有限場景下模型推理的理想選擇，應用十分廣泛，GGUF 是 llama.cpp 執行模型所需的模型檔案格式，希望以上教程能對如何管理 GGUF 模型檔案有所幫助。
如果覺得寫得不錯，歡迎點贊、轉發、關注。