Ubuntu 大模型HF转GGUF全流程实践指南

本文基于 Ubuntu 26.04 系统、纯CPU无CUDA硬件环境，完整演示基于 llama.cpp 实现 HF 原始模型转换 GGUF 格式与CPU量化的落地实操流程。以 Qwen2-0.5B-Instruct 中文对话模型为案例，循序渐进讲解Swap分区配置、系统依赖安装、llama.cpp源码编译、Python虚拟环境部署、原生HF模型下载、HF模型转GGUF格式封装、Q4_K_M等级量化的完整步骤。

1、首先HF模型加载、格式转换、权重量化均会产生高额内存占用，可提前配置大容量磁盘Swap虚拟内存，本次配置8G缓存。

root@localhost:~/# sudo fallocate -l 8G /swapfile
root@localhost:~/# sudo chmod 600 /swapfile
root@localhost:~/# sudo mkswap /swapfile
root@localhost:~/# sudo swapon /swapfile
root@localhost:~/# echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

2、安装编译工具、运行依赖、虚拟环境工具，为llama.cpp编译、模型转换提供基础环境。

root@localhost:~/# sudo apt update
root@localhost:~/# sudo apt install -y git build-essential cmake python3 python3-pip python3-full python3-venv tmux

3、在官方仓库中拉取llama.cpp源程序，并执行make命令完成编译，编译通过后会在根目录下生成所需要的转换脚本。

root@localhost:~/# git clone https://github.com/ggerganov/llama.cpp.git
root@localhost:~/# cd llama.cpp

root@localhost:~/# mkdir build
root@localhost:~/# cd build
root@localhost:~/# cmake ..
root@localhost:~/# make -j2

[100%] Building CXX object app/CMakeFiles/llama-app.dir/llama.cpp.o
[100%] Building CXX object app/CMakeFiles/llama-app.dir/download.cpp.o
[100%] Building CXX object app/CMakeFiles/llama-app.dir/__/license.cpp.o
[100%] Linking CXX executable ../bin/llama
[100%] Built target llama-app
[100%] Building CXX object tools/cli/CMakeFiles/llama-cli.dir/main.cpp.o
[100%] Linking CXX executable ../../bin/llama-cli
[100%] Built target llama-cli
[100%] Linking CXX executable ../bin/test-chat
[100%] Built target test-chat

root@localhost:~/# cd ..
root@localhost:~/# ls -lh convert*
-rwxr-xr-x 1 root root 13K Aug 27 16:19 convert_hf_to_gguf.py
-rwxr-xr-x 1 root root 28K Aug 27 16:19 convert_hf_to_gguf_update.py
-rwxr-xr-x 1 root root 19K Aug 27 16:19 convert_llama_ggml_to_gguf.py
-rwxr-xr-x 1 root root 23K Aug 27 16:19 convert_lora_to_gguf.py

4、模型转换脚本依赖Python生态，使用独立虚拟环境，避免污染系统全局Python，同时适配低配内存，关闭缓存写入。

root@localhost:~/# python3 -m venv ~/myvenv
root@localhost:~/# source ~/myvenv/bin/activate

(myvenv) root@localhost:~/llama.cpp# export TMPDIR=$HOME/tmp
(myvenv) root@localhost:~/llama.cpp# mkdir -p "$TMPDIR"
(myvenv) root@localhost:~/llama.cpp# pip install --upgrade pip
(myvenv) root@localhost:~/llama.cpp# pip install --no-cache-dir torch transformers sentencepiece protobuf safetensors huggingface_hub modelscope
(myvenv) root@localhost:~/llama.cpp# pip list

Package                Version
---------------------- ---------
annotated-doc          0.0.5
anyio                  4.14.2
certifi                2026.7.22
charset-normalizer     3.5.1
click                  8.4.2
cuda-bindings          13.3.1
cuda-pathfinder        1.7.0
cuda-toolkit           13.0.3.0
filelock               3.32.4
fsspec                 2026.7.0
h11                    0.16.0
hf-xet                 1.6.0
httpcore               1.0.9
httpx                  0.28.1
huggingface_hub        1.28.0
idna                   3.19
Jinja2                 3.1.6
markdown-it-py         4.2.0
MarkupSafe             3.0.3
mdurl                  0.1.2
modelscope             1.39.1
modelscope-hub         0.2.0
mpmath                 1.3.0
networkx               3.6.1
numpy                  2.5.2
nvidia-cublas          13.1.1.3
nvidia-cuda-cupti      13.0.85
nvidia-cuda-nvrtc      13.0.88
nvidia-cuda-runtime    13.0.96
nvidia-cudnn-cu13      9.20.0.48
nvidia-cufft           12.0.0.61
nvidia-cufile          1.15.1.6
nvidia-curand          10.4.0.35
nvidia-cusolver        12.0.4.66
nvidia-cusparse        12.6.3.3
nvidia-cusparselt-cu13 0.8.1
nvidia-nccl-cu13       2.29.7
nvidia-nvjitlink       13.3.33
nvidia-nvshmem-cu13    3.4.5
nvidia-nvtx            13.0.85
packaging              26.3
pip                    26.2.1
protobuf               7.36.0
Pygments               2.21.0
PyYAML                 6.0.3
regex                  2026.7.19
requests               2.34.2
rich                   15.0.0
safetensors            0.8.0
sentencepiece          0.2.2
setuptools             84.0.0
shellingham            1.5.4
sympy                  1.14.0
tokenizers             0.22.2
torch                  2.13.0
tqdm                   4.70.0
transformers           5.15.1
triton                 3.7.1
typer                  0.27.1
typing_extensions      4.16.0
urllib3                2.7.0

5、直接在魔搭社区拉取Qwen2-0.5B-Instruct源程序，文件中包含 config.json、model.safetensors、tokenizer.json、tokenizer_config.json 如果缺少任意一个，代表下载不完整，重新执行下载命令。

(myvenv) root@localhost:~/llama.cpp# modelscope download --model Qwen/Qwen2-0.5B-Instruct --local_dir ./Qwen2-0.5B-Instruct
(myvenv) root@localhost:~/llama.cpp# (myvenv) root@wintcp:~/llama.cpp/Qwen2-0.5B-Instruct# ls -lhA
total 954M
-rw-r--r-- 1 root root 1.5K Aug 27 16:58 .gitattributes
-rw-r--r-- 1 root root  12K Aug 27 16:58 LICENSE
-rw-r--r-- 1 root root 3.5K Aug 27 16:58 README.md
-rw-r--r-- 1 root root  659 Aug 27 16:58 config.json
-rw-r--r-- 1 root root   48 Aug 27 16:58 configuration.json
-rw-r--r-- 1 root root  242 Aug 27 16:58 generation_config.json
-rw-r--r-- 1 root root 1.6M Aug 27 16:58 merges.txt
-rw-r--r-- 1 root root 943M Aug 27 16:59 model.safetensors
-rw-r--r-- 1 root root 6.8M Aug 27 16:58 tokenizer.json
-rw-r--r-- 1 root root 1.3K Aug 27 16:58 tokenizer_config.json
-rw-r--r-- 1 root root 2.7M Aug 27 16:58 vocab.json

6、执行HF转GGUF文件，此处很多新手混淆格式转换与权重量化两者的区别，此处重点说明：

• HF转GGUF（convert_hf_to_gguf.py）：仅做文件格式翻译，不压缩、不损失精度。将HuggingFace的safetensors权重封装为llama.cpp专属的GGUF容器格式，输出的 f16.gguf 为FP16全精度模型，体积大、内存占用高，仅作为中间过渡文件。
• GGUF量化（llama-quantize）：真正的权重压缩，将FP16高精度权重压缩为4bit/5bit低精度，大幅缩小模型体积、降低内存占用。

简单总结就是GGUF是文件容器格式，不是量化格式，GGUF可存放全精度（f16）和量化精度（Q4_K_M）权重。

转换完成后生成 Qwen2-0.5B-Instruct-f16.gguf 全精度模型

(myvenv) root@localhost:~/llama.cpp# mkdir -p ./models
(myvenv) root@localhost:~/llama.cpp# python convert_hf_to_gguf.py ./Qwen2-0.5B-Instruct \
  --outtype f16 \
  --outfile ./models/Qwen2-0.5B-Instruct-f16.gguf \
  --no-lazy

通过llama-quantize工具将Qwen2-0.5B-Instruct-f16.gguf文件进行量化，此处选用Q4_K_M等级，对全精度GGUF进行4bit量化，并最终生成可用模型。

(myvenv) root@localhost:~/llama.cpp# ./build/bin/llama-quantize
  ./models/Qwen2-0.5B-Instruct-f16.gguf \
  ./models/Qwen2-0.5B-Instruct-Q4_K_M.gguf \
  Q4_K_M