Published on

llama.cpp + Hy3 部署指南

Authors

环境信息

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

1. 安装 ROCm 驱动

安装 amdgpu-install 工具

sudo apt update
wget https://repo.radeon.com/amdgpu-install/7.2.3/ubuntu/noble/amdgpu-install_7.2.3.70203-1_all.deb -O /tmp/amdgpu-install.deb
sudo dpkg -i /tmp/amdgpu-install.deb

安装 ROCm

sudo apt update
sudo apt install -y rocm
sudo usermod -aG render,video $USER

安装完成后需重新登录或重启，使 render 和 video 用户组权限生效。

2. 安装 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/b10079/llama-b10079-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-b10079/* ~/.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

3. 运行 Hy3 模型

必要说明

  • hy_v3 架构在 llama.cpp PR #25395 合入，b10079 已包含
  • 模型文件需为 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}'

4. 参数详解

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 线程数（默认: 物理核心数）
-b N最大 batch size
-ub NPrompt 处理的 micro-batch size（需 ≤ -b，结合显存/内存带宽调优）
-lv N日志级别（0=error, 1=warn, 2=info, 3=verbose）

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

单卡 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 量化版本

6. 注意事项

  • 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 架构支持）

7. RPC 多机集群部署

当单机显存不足以容纳模型时，可通过 llama.cpp 内置的 RPC（Remote Procedure Call）协议将推理任务分布到多台机器上。模型按层拆分，不同层在不同机器的 GPU 上计算，每步推理通过网络传输中间结果。

架构说明

┌─────────────────────┐         ┌─────────────────────┐
│      Master 节点     │         │     Worker 节点      │
│   (有模型文件的机器)   │  ─────► │   (提供 GPU 算力)    │
│                     │  RPC    │                     │
│  llama-server       │  :50052 │  ggml-rpc-server    │
│  + 本地 GPU 计算     │         │  + GPU 计算          │
└─────────────────────┘         └─────────────────────┘
  • Master：运行 llama-server，加载模型文件，同时承担部分层的计算
  • Worker：运行 ggml-rpc-server，接收 Master 分配的层进行计算
  • 所有 Worker 和 Master 之间通过 RPC 协议通信

Worker 节点配置（每台 Worker 机器都要运行）

~/llama.cpp/vulkan/b10079/ggml-rpc-server --host 0.0.0.0 --port 50052

Worker 节点只需运行 ggml-rpc-server，不需要模型文件。确保防火墙放行 50052 端口。

Master 节点配置（有模型文件的机器）

~/llama.cpp/vulkan/b10079/llama-server \
  -m ~/model-gguf/Qwen3.6-27B-UD-Q4_K_XL.gguf \
  --rpc localhost:50052,192.168.1.100:50052 \
  --host 0.0.0.0 --port 8080 \
  -ngl 99
  • --rpc 参数格式为 IP1:PORT1,IP2:PORT2,...，列出所有 Worker 节点地址
  • localhost:50052 表示 Master 本机也作为 Worker 参与计算
  • 192.168.1.100:50052 替换为实际 Worker 机器的 IP 地址

完整示例：两台机器部署 Qwen3.6-27B

假设：

  • Master 机器 IP：192.168.1.50
  • Worker 机器 IP：192.168.1.100
  • 两台机器都有 Vulkan GPU

Worker 机器上执行：

~/llama.cpp/vulkan/b10079/ggml-rpc-server --host 0.0.0.0 --port 50052

Master 机器上执行：

~/llama.cpp/vulkan/b10079/llama-server \
  -m ~/model-gguf/Qwen3.6-27B-UD-Q4_K_XL.gguf \
  --rpc localhost:50052,192.168.1.100:50052 \
  --host 0.0.0.0 --port 8080 \
  -ngl 99

UMA 集成显卡的重要说明

如果你的 GPU 是集成显卡（如 AMD Radeon 8060S UMA），需要注意：

  • 集成显卡共享系统内存，每个 RPC Worker 用的都是各自机器的系统内存，不会真正"合并显存"
  • 模型按层拆分后，一部分层在 A 机器 GPU 上算，另一部分在 B 机器 GPU 上算，每步推理都要跨网络传输中间结果
  • 网络延迟会显著影响推理速度，尤其是层数多、中间张量大的模型

建议：以 18GB 的 27B 模型为例，单机单卡其实就能跑（UMA 共享系统内存，一般有 32-64GB 可用）。建议先单机试试速度，如果满足需求就不需要加 RPC。

RPC 性能优化建议

建议说明
使用有线网络Wi-Fi 延迟不稳定，会严重拖慢推理速度
万兆网络10GbE 网卡 + 交换机可显著减少传输瓶颈
减少跨机器层数尽量把更多层分配到显存更大的机器上
先测单机很多模型单机就能跑，RPC 不一定值得网络开销

附录：Vulkan + ROCm 双版本共存方案

如果需要同时安装 Vulkan 和 ROCm 两个后端版本，可以通过分目录安装 + 切换脚本实现。

目录结构

~/llama.cpp/
├── use-llama              # 切换脚本
├── vulkan/
│   └── b10079/            # Vulkan 版
└── rocm/
    └── b10079/            # ROCm 版

获取最新版本号

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'])"

当前最新版本为 b10079，下文命令已使用此版本号。

安装 Vulkan 版

mkdir -p ~/llama.cpp/vulkan/b10079 ~/llama.cpp/rocm/b10079
wget -O /tmp/llama-vulkan.tar.gz \
  https://github.com/ggml-org/llama.cpp/releases/download/b10079/llama-b10079-bin-ubuntu-vulkan-x64.tar.gz
tar xzf /tmp/llama-vulkan.tar.gz --strip-components=1 -C ~/llama.cpp/vulkan/b10079/

安装 ROCm 版

wget -O /tmp/llama-rocm.tar.gz \
  https://github.com/ggml-org/llama.cpp/releases/download/b10079/llama-b10079-bin-ubuntu-rocm-7.2-x64.tar.gz
tar xzf /tmp/llama-rocm.tar.gz --strip-components=1 -C ~/llama.cpp/rocm/b10079/

切换脚本

创建 ~/llama.cpp/use-llama：

#!/bin/bash
LLAMA_HOME="$HOME/llama.cpp"

case "$1" in
  vulkan)
    export LLAMA_BACKEND="vulkan"
    export LLAMA_PATH="$LLAMA_HOME/vulkan/b10079"
    ;;
  rocm)
    export LLAMA_BACKEND="rocm"
    export LLAMA_PATH="$LLAMA_HOME/rocm/b10079"
    ;;
  "")
    if [ -n "$LLAMA_BACKEND" ]; then
      echo "当前版本: $LLAMA_BACKEND ($LLAMA_PATH)"
    else
      echo "当前版本: 未激活"
      echo "用法: source use-llama vulkan|rocm"
    fi
    return 0 2>/dev/null || exit 0
    ;;
  *)
    echo "用法: source use-llama vulkan|rocm"
    return 1 2>/dev/null || exit 1
    ;;
esac

export PATH="$LLAMA_PATH:$PATH"
export LD_LIBRARY_PATH="$LLAMA_PATH:$LD_LIBRARY_PATH"
echo "llama.cpp ($LLAMA_BACKEND) 已激活"

chmod +x ~/llama.cpp/use-llama

使用方式

source ~/llama.cpp/use-llama vulkan   # 启用 Vulkan 版
source ~/llama.cpp/use-llama rocm     # 启用 ROCm 版
source ~/llama.cpp/use-llama          # 查看当前版本

注意：必须用 source（或 .）执行，才能修改当前 shell 的环境变量。

Discuss on Twitter • View on GitHub