场景：将标准 HuggingFace 格式 Qwen3 模型，直接转换为 GGUF 单文件，全程只用 convert_hf_to_gguf.py，不用编译 llama.cpp、不需要GPU，适合 Windows 本地离线转换。

一、前置环境探查

先校验模型文件与本地运行环境，避免转换中途报错。

1. 模型目录校验（标准HF格式）
   目录内必须包含：config.json、model.safetensors、tokenizer.json，属于标准HuggingFace模型归档。
   读取 config.json 核对模型架构信息：

• 模型类：Qwen3ForCausalLM
• 层数：28层
• 隐藏维度 hidden_size：1024
• 精度：bf16
• 权重共享：tie_word_embeddings=true

2. 机器环境检查

• Python：3.11（推荐版本）
• 磁盘：目标盘预留足够空闲空间
• CUDA：转换脚本本身不依赖GPU，CPU torch 即可完成权重读取

二、拉取转换工具仓库

核心转换脚本来自 llama.cpp 仓库，只需要浅克隆，不用完整历史：

git clone --depth 1 [https://github.com/ggml-org/llama.cpp.git](https://github.com/ggml-org/llama.cpp.git)

关键脚本：llama.cpp/convert_hf_to_gguf.py，整个转换逻辑都由这个Python脚本实现。

三、安装Python依赖（CPU版Torch）

无需 CUDA 版本 torch，CPU版本足够读取 safetensors 权重文件

# 安装CPU版torch
python -m pip install torch --index-url [https://download.pytorch.org/whl/cpu](https://download.pytorch.org/whl/cpu)
# 其余依赖
python -m pip install numpy sentencepiece gguf transformers safetensors

四、执行 HF → GGUF 转换命令

python llama.cpp/convert_hf_to_gguf.py \
    ./models/export-model-1 \
    --outfile ./models/export-model-1/model-bf16.gguf \
    --outtype bf16

参数说明

• 第一个参数：HF模型文件夹路径
• --outfile：输出GGUF单文件路径
• --outtype bf16：不做量化，保留原始BF16精度

量化替换方案：如需压缩模型，可将 bf16 改为 q4_k_m / q5_k_m / q8_0 等量化类型。
脚本会自动读取模型目录内的 config.json、tokenizer.json、chat_template.jinja，一并打包进GGUF文件。

五、GGUF 结果校验

转换完成后，使用 gguf Python包读取文件头做完整性校验，重点核对几项：

1. general.architecture = qwen3
2. general.file_type = 32 (MOSTLY_BF16)
3. Tensor总数量、张量shape，与原HF config完全匹配
4. bos / eos / pad token id 和原模型配置保持一致

六、核心要点总结

1. 无需编译 llama.cpp：本流程是纯Python脚本转换，不需要cmake编译后端，Windows上手门槛低；
2. 不需要GPU：torch仅用于加载 safetensors 权重文件，CPU即可跑；
3. 流式读写：大模型转换不会一次性把全部权重塞进内存，内存压力小；示例1.2GB模型，转换耗时约6秒；
4. GGUF是自包含单文件：权重、分词器、对话模板、特殊token全部打包在一个.gguf内，拷贝即可在llama.cpp、ollama等工具直接加载使用。

常见踩坑提示

• Python版本不要过高/过低，3.11兼容性最优；
• 磁盘要预留至少2倍模型大小空闲（原模型+输出GGUF）；
• 若模型有多个分片safetensors，脚本可自动识别合并，无需手动处理分片；
• 转换仅做格式封装与类型转换，不会改变模型推理能力，量化才会带来精度损失。