AngelSlim/Hy3-GGUF · Hugging Face

来源：https://huggingface.co/AngelSlim/Hy3-GGUF

AngelSlim

致力于打造更直观、更全面、更高效的 LLMs 压缩工具包。

📖文档 (https://angelslim.readthedocs.io/) | 🤗Hugging Face (https://huggingface.co/AngelSlim) | 🤖ModelScope (https://modelscope.cn/models/AngelSlim/Hy3-GGUF) | 💬微信 (https://huggingface.co/AngelSlim/docs/source/assets/angel_slim_wechat.png)

https://huggingface.co/AngelSlim/Hy3-GGUF#hy3-llamacpp-quantization

Hy3 llama.cpp 量化

在 llama.cpp 上量化并运行 Hy3 (hy_v3)，支持 MTP 自推测解码和思考/工具调用解析器。一个脚本即可修补并构建 llama.cpp；内置配方和聊天模板，可从校准集自行量化低比特 GGUF。

以下两部分：部署（构建与运行）和量化。

https://huggingface.co/AngelSlim/Hy3-GGUF#quick-start

快速入门

https://huggingface.co/AngelSlim/Hy3-GGUF#build

构建

bash setup_hyv3_llama.sh                     # clone 到 ./llama.cpp-hyv3，自动 CUDA/CPU
bash setup_hyv3_llama.sh /path/to/target      # 选择 clone 目录
CUDA=0 bash setup_hyv3_llama.sh               # 强制仅 CPU 构建

脚本会锁定已验证的 llama.cpp 基础提交，应用 patches/01（基础架构）然后是 patches/02（MTP + 解析器），然后构建。二进制文件位于 /build/bin/。

https://huggingface.co/AngelSlim/Hy3-GGUF#run

运行

# 普通服务（无推测解码）
./llama.cpp-hyv3/build/bin/llama-server -m /path/to/Hy3.gguf -ctk q8_0 -ctv q8_0 -fa on -c 65536

# 服务 + MTP 自推测解码（需要 MTP gguf，即转换时未加 --no-mtp）
./llama.cpp-hyv3/build/bin/llama-server -m /path/to/Hy3-mtp.gguf --spec-type draft-mtp --spec-draft-n-max 3 --spec-draft-n-min 1 -ctk q8_0 -ctv q8_0 -ctkd q8_0 -ctvd q8_0 -fa on -c 65536

https://huggingface.co/AngelSlim/Hy3-GGUF#recommended-setups

推荐配置

权重：IQ1_M 约 83 GiB，Q4_K_M 约 166 GiB（MTP 增加约 2 GiB 加上草稿 KV 缓存）。

1 张卡只适合 IQ1_M，且很紧张——需缩小上下文、量化 KV、关闭 MTP。
2 张卡运行 IQ1_M+MTP 绰绰有余（可去掉 -c/KV 标志），但 Q4_K_M+MTP 较紧，需保留 -c 65536 和 q8_0 KV（主模型+草稿）。
4 张卡可轻松运行 Q4_K_M+MTP。

https://huggingface.co/AngelSlim/Hy3-GGUF#troubleshooting

故障排除

• Error: no such instruction: vdpbf16ps（出现在 ggml-cpu 的 vec.cpp/sgemm.cpp 中）：CPU 有 AVX512-BF16 但系统汇编器（旧 binutils）无法编码。脚本会自动检测并添加 -DGGML_NATIVE=OFF；必要时可强制 GGML_NATIVE=0 bash setup_hyv3_llama.sh。与补丁无关；CUDA 推理不受影响。
• undefined reference to SSL_get1_peer_certificate：系统 OpenSSL 过旧。此处默认关闭 OpenSSL（-DLLAMA_OPENSSL=OFF）；仅影响服务器的 HTTPS 模型下载，不影响本地 GGUF 服务。如果拥有 OpenSSL 3.0+ 且需要，可设置 OPENSSL=1。

https://huggingface.co/AngelSlim/Hy3-GGUF#quantize-with-your-own-data

使用自己的数据进行量化

如果你有校准集，可以自行计算重要性矩阵并量化模型。所有步骤均使用标准 llama.cpp 工具；混合精度配方和 minja 兼容的聊天模板已集成在此文件夹中。

https://huggingface.co/AngelSlim/Hy3-GGUF#the-mixed-precision-recipes

混合精度配方

recipes/ 中的配方将比特分配给关键部分：

• 注意力（attn_q/k/v）和token 嵌入/输出头保持高精度（q8_0 / q4_K / q6_K）——体积小，低比特损害最大。
• 共享专家（ffn_*_shexp，每个 token 都激活）保持 q5_K–q6_K。
• 路由专家（ffn_*_exps）承担激进的低比特，并主导文件大小。在 IQ1_M 配方中，大多数层为 iq1_m，ffn_down 略高（iq3_xxs），敏感层逐层升级（iq2_xxs）。

*_mtp 变体添加了 MTP 块（blk..nextn.* 和层 * 专家）。仅当 gguf 仍包含 MTP 头时使用；对于使用 --no-mtp 转换的 gguf，请使用普通配方。（MTP 块的专家保留 K 量化而非 IQ*，因为极低比特 IQ 类型需要 imatrix，而 imatrix 只覆盖主干层。）

https://huggingface.co/AngelSlim/Hy3-GGUF#1-convert-hf-%E2%86%92-bf16-gguf

1. 转换 HF → BF16 GGUF

PYTHONPATH=./llama.cpp-hyv3/gguf-py python ./llama.cpp-hyv3/convert_hf_to_gguf.py /path/to/HYV3-hf --outfile Hy3-BF16.gguf --outtype bf16
# 添加 --no-mtp 可丢弃 MTP 头（后面使用非 mtp 配方）

https://huggingface.co/AngelSlim/Hy3-GGUF#2-compute-the-importance-matrix-imatrix

2. 计算重要性矩阵（imatrix）

校准文件是纯文本，包含已应用模型特殊 token 的样本（单个文件，通过 -f 传入）。imatrix 与目标量化类型无关——在 BF16 上计算一次，即可用于任何配方。

./llama.cpp-hyv3/build/bin/llama-imatrix -m Hy3-BF16.gguf -f calib.txt -o imatrix.gguf --output-format gguf --parse-special
# 单 GPU 无法容纳 BF16 → 添加 --cpu-moe（将专家保留在 CPU）或 -ngl 0

https://huggingface.co/AngelSlim/Hy3-GGUF#3-quantize-with-a-recipe

3. 使用配方进行量化

选择匹配目标和 gguf 是否包含 MTP 头的配方（上表）。--token-embedding-type 有所不同：Q4_K_M 时保持 q8_0（嵌入体积小，无需过度压缩），极端 IQ1_M 构建时降为 q4_K。以下示例适用于 MTP gguf——对于 --no-mtp gguf 请使用 non-mtp 配方。

# ~Q4_K_M 混合
./llama.cpp-hyv3/build/bin/llama-quantize --imatrix imatrix.gguf --tensor-type-file recipes/hyv3_q4km_mtp_recipe.txt --token-embedding-type q8_0 --output-tensor-type q6_K Hy3-BF16-mtp.gguf Hy3-Q4_K_M-mtp.gguf Q4_K_M

# ~IQ1_M 混合（极端）
./llama.cpp-hyv3/build/bin/llama-quantize --imatrix imatrix.gguf --tensor-type-file recipes/hyv3_iq1m_mtp_recipe.txt --token-embedding-type q4_K --output-tensor-type q6_K Hy3-BF16-mtp.gguf Hy3-IQ1_M-mtp.gguf IQ1_M

https://huggingface.co/AngelSlim/Hy3-GGUF#4-optional-embed-a-minja-compatible-chat-template

4. （可选）嵌入 minja 兼容的聊天模板

Hy3 内置的 chat_template 使用 Python str.format，llama.cpp 的 minja 引擎无法评估 → 聊天/--jinja 模式会崩溃。hyv3_opensource_chat_template.jinja 是一个静态版本（suffix 硬编码为 :opensource，展开 .format）。将其烘焙到 gguf 中，使 --jinja 无需在运行时指定 --chat-template-file：

PYTHONPATH=./llama.cpp-hyv3/gguf-py python -m gguf.scripts.gguf_new_metadata --chat-template "$(cat hyv3_opensource_chat_template.jinja)" --force Hy3-IQ1_M-mtp.gguf Hy3-IQ1_M-mtp-tmpl.gguf