很高兴看到各实验室开始发布自己的GGUF版本🔥 https://huggingface.co/AngelSlim/Hy4-preview-GGUF…

AngelSlim/Hy4-preview-GGUF · Hugging Face

来源：https://huggingface.co/AngelSlim/Hy4-preview-GGUF
三个版本的 Hy4-Preview GGUF 构建：https://huggingface.co/tencent/Hy4-preview

语言： 英文 (https://huggingface.co/AngelSlim/Hy4-preview-GGUF#english) · 中文 (https://huggingface.co/AngelSlim/Hy4-preview-GGUF#%E4%B8%AD%E6%96%87)

两个文件均无法在原版 llama.cpp 上运行。
hyv4 架构尚未合入上游。需应用 hy4-preview-patch/ 目录中的补丁。

英文 (English)

1. 文件说明

Hy4-preview-Q4_K_M.gguf — 常规 Q4_K_M 量化。多数张量为 Q4_K；ffn_down_exps 的 37 层根据 llama.cpp 自身逻辑被量化为 Q6_K。除非内存受限，否则请使用此版本。

Hy4-preview-UD-IQ1_M.gguf — 采用 UD-IQ1_M 策略的混合精度量化，约 2.44 bpw，相同模型体积减半。路由专家的 gate/up 投影层分别使用 1.75 bpw (IQ1_M) 和 2.0625 bpw (IQ2_XXS)。

Hy4-preview-STQ1_0.gguf — 采用 MIX-STQ1_0 策略的混合精度量化，约 2.38 bpw，相同模型体积减半。路由专家的 gate/up 投影层在 29 层使用 1.3125 bpw (STQ1_0)，其余 48 层使用 2.0625 bpw (IQ2_XXS)。详见第 3 节。

2. 如何运行

构建打过补丁的 llama.cpp：

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
git checkout 0cea36222

git apply hy4-preview-patch/0001-hyv4-architecture.patch
git apply hy4-preview-patch/0002-stq1_0-quant-and-cuda.patch   # 若仅使用 Q4_K_M 则可跳过

export PATH=/usr/local/cuda-13.0/bin:$PATH CUDACXX=/usr/local/cuda-13.0/bin/nvcc
cmake -B build-cuda -DGGML_CUDA=ON -DLLAMA_CURL=OFF -DGGML_NATIVE=OFF \
      -DCMAKE_BUILD_TYPE=Release -DCMAKE_CUDA_ARCHITECTURES=90 \
      -DLLAMA_BUILD_UI=OFF -DLLAMA_USE_PREBUILT_UI=OFF
cmake --build build-cuda --target llama-cli llama-bench llama-quantize -j 48

根据你的 GPU 设置 -DCMAKE_CUDA_ARCHITECTURES（90 = H20/H100）。离线构建必须同时设置 -DLLAMA_BUILD_UI=OFF 和 -DLLAMA_USE_PREBUILT_UI=OFF；仅设置前者仍会下载预编译资源。

然后：

# 单条 prompt
build-cuda/bin/llama-cli -m Hy4-preview-Q4_K_M.gguf -ngl 99 -c 8192 \
    --temp 0 -n 512 --no-warmup --jinja -st -f prompt.txt

# 吞吐测试
build-cuda/bin/llama-bench -m Hy4-preview-STQ1_0.gguf -ngl 99 -p 512 -n 128 -r 3

• 聊天必须使用 --jinja。 HY4 的聊天模板不匹配 llama.cpp 任何内置模板族。
• GGUF 文件必须放在本地磁盘。 llama.cpp 以 mmap 方式加载权重；通过 NFS 访问时随机页错误率约 12 MB/s，会使 1 分钟的加载延长至数小时。
• 单条 prompt 使用 -st -f prompt.txt。 此构建忽略 -no-cnv，遇 EOF 会持续打印 >。
• 全量驻留显存需求：约 435 GiB (Q4_K_M) 或约 214 GiB (STQ1_0)。若显存不足，请降低 -ngl。

在 8×H20 上实测性能：

读取这些文件的 Python 工具必须使用打过补丁的 gguf-py，且必须使用绝对路径：sys.path.insert(0, '/path/to/llama.cpp/gguf-py')。

3. STQ1_0 与混合精度策略

格式说明。 STQ1_0 来自 llama.cpp PR #22836。权重为三值 {-d, 0, +d}，且每四个通道强制一个为零（3:4 稀疏）。每 4 个权重存储为一个 4-bit 编码加一个 1-bit 表索引位，索引一个 32 项的码本；每 256 个权重共用一个 fp16 缩放因子。即每 256 个权重占 2 + 32 + 8 = 42 字节 = 1.3125 bpw。

我们的编码器。 上游的量化器针对已落在三值网格上的 QAT 输入：它忽略 imatrix，设 d = amax，并将零置于 argmin |x|。这对训练后量化（PTQ）效果不佳。我们保持格式逐字节一致，仅修改两个决策：

1. 加权最小二乘缩放：d = sum(w*sel*x) / sum(w*sel²)，取代 d = amax。
2. imatrix 感知的零值位置：将使 w[j]*(x[j]² - (|x[j]| - d)²) 最小的通道置零，即基于增量代价而非单纯最小幅度。

两者交替迭代 3 轮。在 1200 行真实专家权重上实测：仅最小二乘缩放就带来 -89.7% 的加权 SSD 改善，imatrix 项在残差上再优化 -4.1%。主要收益来自缩放因子——amax 会将 d 固定为 256 个权重中单个最大离群值。

比特分配。 三个路由专家族占全部参数的 97.7%，因此配方在其他张量上不惜成本：

4. 构建运行时

从 bf16 重新量化

配方文件已随附。STQ1_0 强制需要 imatrix——其编码器使用它进行缩放因子求解和零值位置选择。

build-cuda/bin/llama-quantize --dry-run --imatrix imatrix.gguf \
    --tensor-type-file Hy4-preview-STQ1_0.tensortypes --leave-output-tensor \
    HY4.bf16.gguf out.gguf IQ1_M          # 构建 Q4_K_M 版本：基础 ftype 使用 Q4_K_M

中文

1. 文件说明

Hy4-preview-Q4_K_M.gguf — 常规 Q4_K_M。多数张量为 Q4_K，ffn_down_exps 的 37 层根据 llama.cpp 自身逻辑被量化为 Q6_K。没有显存压力就用这个。

Hy4-preview-UD-IQ1_M.gguf — 采用 UD-IQ1_M 策略的混合精度，约 2.44 bpw，相同模型体积减半。

Hy4-preview-STQ1_0.gguf — 采用 MIX-STQ1_0 策略的混合精度，约 2.38 bpw，相同模型体积减半。路由专家的 gate/up 在 29 层使用 1.3125 bpw (STQ1_0)，其余 48 层使用 2.0625 bpw (IQ2_XXS)。见第 3 节。

2. 如何使用

构建打过补丁的 llama.cpp：

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
git checkout 0cea36222

git apply hy4-preview-patch/0001-hyv4-architecture.patch
git apply hy4-preview-patch/0002-stq1_0-quant-and-cuda.patch   # 只用 Q4_K_M 可跳过

export PATH=/usr/local/cuda-13.0/bin:$PATH CUDACXX=/usr/local/cuda-13.0/bin/nvcc
cmake -B build-cuda -DGGML_CUDA=ON -DLLAMA_CURL=OFF -DGGML_NATIVE=OFF \
      -DCMAKE_BUILD_TYPE=Release -DCMAKE_CUDA_ARCHITECTURES=90 \
      -DLLAMA_BUILD_UI=OFF -DLLAMA_USE_PREBUILT_UI=OFF
cmake --build build-cuda --target llama-cli llama-bench llama-quantize -j 48

根据自己的 GPU 设置 -DCMAKE_CUDA_ARCHITECTURES（90 = H20/H100）。离线构建同时需要 -DLLAMA_BUILD_UI=OFF 和 -DLLAMA_USE_PREBUILT_UI=OFF，只给前者仍会去下载预构建资源。

# 单条 prompt
build-cuda/bin/llama-cli -m Hy4-preview-Q4_K_M.gguf -ngl 99 -c 8192 \
    --temp 0 -n 512 --no-warmup --jinja -st -f prompt.txt

# 测速
build-cuda/bin/llama-bench -m Hy4-preview-STQ1_0.gguf -ngl 99 -p 512 -n 128 -r 3

• 聊天必须加 --jinja。 HY4 的聊天模板不匹配 llama.cpp 任何内置模板族。
• GGUF 必须放本地盘。 llama.cpp 用 mmap，NFS 随机页错误约 12 MB/s，本来 1 分钟的加载会变成几小时。
• 单条 prompt 用 -st -f prompt.txt。 此构建忽略 -no-cnv，遇 EOF 会一直打印 >。
• 全量驻留显存需求：约 435 GiB (Q4_K_M) 或约 214 GiB (STQ1_0)。不够就降低 -ngl。

在 8×H20 上实测（已确认 GPU 空闲、权重全驻显存）：

读这些文件的 Python 工具必须用打过补丁的 gguf-py，且用绝对路径：sys.path.insert(0, '/path/to/llama.cpp/gguf-py')。

3. STQ1_0 与混合精度策略

格式。 STQ1_0 来自 llama.cpp PR #22836。权重为三值 {-d, 0, +d}，且每四个通道强制一个为零（3:4 稀疏）。每 4 个权重存成 4-bit 编码加 1-bit 选表位，索引一张 32 项码本；每 256 个权重共用一个 fp16 缩放因子。即每 256 个权重占 2 + 32 + 8 = 42 字节 = 1.3125 bpw。

我们的编码器。 上游的量化器面向已落在三值网格上的 QAT 输入：直接忽略 imatrix，取 d = amax，并把零放在 argmin |x|。这对训练后量化 (PTQ) 很弱。我们保持格式逐字节一致，只改两个决策：

1. 加权最小二乘缩放：d = sum(w*sel*x) / sum(w*sel²)，取代 d = amax。
2. imatrix 感知的零值位置：零掉使 w[j]*(x[j]² - (|x[j]| - d)²) 最小的通道，即比较增量代价，而非单纯的最小幅度。

两者交替 3 轮。在 1200 行真实专家权重上实测：仅最小二乘缩放就带来 -89.7% 加权 SSD 改善，imatrix 项在残差上再补 -4.1%。主要收益来自缩放因子——amax 会把 d 钉在 256 个权重里的单个最大离群值上。

比特分配。 三个路由专家族占全部参数的 97.7%，所以配方在其余张量上舍得花：

从 bf16 重新量化

配方文件已随附。STQ1_0 强制需要 imatrix——它的编码器要用 imatrix 做缩放因子求解与零值位置选择。

build-cuda/bin/llama-quantize --dry-run --imatrix imatrix.gguf \
    --tensor-type-file Hy4-preview-STQ1_0.tensortypes --leave-output-tensor \
    HY4.bf16.gguf out.gguf IQ1_M          # Q4_K_M 版本：基础 ftype 用 Q4_K_M

文件列表

hy4-preview-patch/
  0001-hyv4-architecture.patch        18 文件, +1632/-3    两个 GGUF 版本都需要此补丁
  0002-stq1_0-quant-and-cuda.patch    25 文件, +683/-4     仅 STQ1_0 版本需要
  Hy4-preview-STQ1_0.tensortypes      STQ1_0 配方
  Hy4-preview-Q4_K_M.tensortypes      Q4_K_M 配方

腾讯混元 (@TencentHunyuan):
我们将 Hy4-preview 从 1.5TB 压缩到约 200GiB GGUF，它仍然表现良好！

遇见 MIX-STQ1_0。
技巧不仅在于降低比特数，更在于决定何处降低：校准数据为每一层选择比特宽度，有些低至 1.31-bit STQ1_0，有些则保持在 2.06-bit IQ2_XXS。同样的预算，更低的…