Published on

llama.cpp + Hy3 部署指南

Authors

环境信息

项目值
系统Linux x86_64
显卡AMD RX 395 (Vulkan)
显存96 GB
模型Hy3-IQ1_M-mtp.gguf (86 GB)
llama.cpp 版本b10075

1. 安装 llama.cpp（Vulkan 版）

下载最新 release

curl -sL https://api.github.com/repos/ggml-org/llama.cpp/releases/latest | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['tag_name'])"

Ubuntu Vulkan x64 版本下载：

wget -O /tmp/llama-vulkan.tar.gz \
  https://github.com/ggml-org/llama.cpp/releases/download/b10075/llama-b10075-bin-ubuntu-vulkan-x64.tar.gz

安装到用户目录

mkdir -p ~/.local/lib/llama ~/.local/bin
tar xzf /tmp/llama-vulkan.tar.gz -C /tmp/llama
cp /tmp/llama/llama-b10075/* ~/.local/lib/llama/
chmod +x ~/.local/lib/llama/llama* ~/.local/lib/llama/ggml*
for f in ~/.local/lib/llama/llama* ~/.local/lib/llama/ggml*; do
  [ -x "$f" ] && ln -sf "$f" ~/.local/bin/
done

设置环境变量

export LD_LIBRARY_PATH="$HOME/.local/lib/llama:$LD_LIBRARY_PATH"
export PATH="$HOME/.local/bin:$PATH"

验证安装：

llama-cli --version

2. 运行 Hy3 模型

必要说明

  • hy_v3 架构在 llama.cpp PR #25395 合入，b10075 已包含
  • 模型文件需为 MTP 版本（含 MTP 头），文件名 Hy3-IQ1_M-mtp.gguf
  • 86 GB 模型在 96 GB 显存上运行，剩余约 10 GB 给 KV 缓存

基础运行（无 MTP）

llama-server \
  -m ~/model-gguf/Hy3-IQ1_M-mtp.gguf \
  -ngl 99 \
  -c 65536 \
  -ctk q8_0 -ctv q8_0 \
  -fa on \
  --host 0.0.0.0 --port 8080

推荐运行（MTP + KV 量化，单卡 96G 最佳配置）

export LD_LIBRARY_PATH="$HOME/.local/lib/llama:$LD_LIBRARY_PATH" && \
export PATH="$HOME/.local/bin:$PATH" && \
llama-server \
  -m ~/model-gguf/Hy3-IQ1_M-mtp.gguf \
  --alias "hy3" \
  --api-key "sk-testing" \
  -ngl 99 -c 80000 \
  -ctk q8_0 -ctv q8_0 \
  -ctkd q8_0 -ctvd q8_0 \
  -fa on \
  --host 0.0.0.0 --port 8080 \
  --spec-type draft-mtp \
  --spec-draft-n-max 2

AMD RX 395 对 iq4_nl KV 量化格式支持不佳，改用 q8_0 后速度可达约 20 token/s，是目前实测最快的配置。

API 调用测试

curl -s http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-testing" \
  -d '{"messages":[{"role":"user","content":"你好"}],"max_tokens":100}'

3. 参数详解

GPU 相关

参数说明本配置
-ngl N将 N 层 offload 到 GPU（-1 或 99 = 全部）99
-fa onFlash Attention，节省显存、加速长上下文on

上下文与 KV 缓存

参数说明本配置
-c N上下文窗口大小（token 数）80000 (80K)
-ctk TYPEK 缓存量化格式q8_0
-ctv TYPEV 缓存量化格式q8_0

KV 缓存量化格式（按显存用量从小到大）：

格式每元素位宽说明
iq4_nl~4 bit非线性 4-bit，质量最佳
q4_0~4 bit标准 4-bit 块量化
q4_1~4.5 bit4-bit + fp16 scale 和 min
q5_0~5 bit5-bit 块量化
q5_1~5.5 bit5-bit + fp16 scale 和 min
q8_0~8 bit8-bit 块量化，无损近似
f1616 bit半精度，默认
f3232 bit全精度

MTP 投机解码（Multi-Token Prediction）

参数说明本配置
--spec-type draft-mtp使用 MTP 头作为草稿模型draft-mtp
--spec-draft-n-max N最多预测 N 个未来 token2
-ctkd TYPE草稿模型 K 缓存量化q8_0
-ctvd TYPE草稿模型 V 缓存量化q8_0

MTP 效果：接受率约 38%，平均每次生成 2.14 个 token，可提速 ~20-40%。

其他性能参数

参数说明
-t NCPU 线程数（默认: 物理核心数）
-ub N最大 batch size，影响 prompt 处理速度
-lv N日志级别（0=error, 1=warn, 2=info, 3=verbose）

4. 显存预算与上下文上限

单卡 96 GB 显存计算

模型权重: ~86 GB 运行时开销: ~1-2 GB 可用给 KV 缓存: ~8-9 GB

上下文q8_0 KV 大小显存余量结论
32K~5.6 GB~3 GB很稳
64K~11.2 GB~0 GB紧张
80K~14 GB-实测可用，约 20 token/s

每 token KV 缓存大小 ≈ 层数 × KV 头数 × 头维度 × 2 × 位宽系数 Hy3: 80层 × 8 KV头 × 128维度 × 2 × 1 byte (q8_0) ≈ 160 KB/token

超 80K 上下文的方案

  1. --no-kv-offload：KV 缓存放系统内存，模型仍在 GPU。

    • 可行但慢 3-5 倍（PCIe 传输开销）
    • 系统内存需足够：200K × 160 KB ≈ 32 GB

  2. 多卡：2 张卡可轻松跑 IQ1_M + MTP + 默认上下文

  3. 换更小量化：没有比 IQ1_M 更小的 Hy3 量化版本

5. 注意事项

  • AMD RX 395 兼容性：iq4_nl KV 量化格式在 AMD 395 上支持不佳，建议改用 q8_0
  • Warning special_eos_id is not in special_eog_ids：GGUF 元数据问题，不影响使用
  • 首次请求较慢（模型预热 + 编译缓存），后续请求提速
  • MTP token 接受率和生成长度相关，短文本接受率可能偏低
  • 模型文件不兼容过旧的 llama.cpp 版本（需 hy_v3 架构支持）
Discuss on Twitter • View on GitHub