hy4ggufllama.cppollama本地部署显存混元

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

2026年11月10日by EXAIV Team

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

hy4 是混元家族里最适合自己部署的一个：4B 稠密模型，官方给齐 FP8 / GPTQ-Int4 / AWQ-Int4 三种量化，社区 GGUF 转换的作者也有五六个以上。真正把事情变复杂的不是模型本身，而是三个你需要自己做决定的地方：选哪个量化档位、显存放多少、跑哪个框架。本文按「决策 → 测算 → 部署 → 排查」的顺序走一遍，命令可以直接复制。

30 秒版本

第一次部署 hy4 的推荐组合：社区 GGUF 的 Q4_K_M + llama.cpp（llama-server 起 OpenAI 兼容端点）。显存按「权重 2.5GB + KV cache 0.5GB + 运行时 0.5GB」估算，6GB 卡足够。Mac 用户换成 mlx-community 的 4bit 转换更省事。

第一步：选量化档位

档位	权重大小（实测 bartowski 仓库文件体积）	质量	适合
IQ4_XS	2.37 GB	接近 Q4	显存紧张的等价 Q4 路线
Q3_K_M	2.17 GB	可感知损失	4GB 卡勉强可跑
Q4_K_M	2.61 GB	几乎无损	默认选择，绝大多数场景够用
Q5_K_M	3.03 GB	接近原始	显存够就选它
Q6_K	3.47 GB	几乎等同原精度	长文本生成的保守选择
Q8_0	4.49 GB	基本等同原精度	做精度对照基准用
FP16（原始权重）	约 8.4 GB	原始	需要 FP16 推理栈时

原始权重体积来自模型卡参数：Hunyuan-4B-Instruct 是 42.2 亿参数，BF16 存储约 8.4GB。

选档位的实际顺序

先用 Q4_K_M 跑通，确认命令、上下文和服务化都没问题；如果你做的是结构化抽取、代码生成这类对精度敏感的任务，再换 Q5_K_M 对比输出差异；只有在需要建立「我的量化损失了多少」的基线时才上 Q8_0 或 FP16。上来就 FP16 往往只是浪费显存。

社区 hy4 GGUF 的作者与仓库：

作者	仓库特点
bartowski	档位最全、社区下载量最高，适合作为默认来源
mradermacher	提供标准量化与 i1 系列量化两套
gabriellarson	常规量化为主
DevQuasar	常规量化为主
Disya	Q8_0 为主，适合做高精度对照
Edge-Quant	单档位 Q4_K_M，极简选择

下载时注意区分文件名里的量化标记（Q4_K_M、Q5_K_M、Q8_0）和来源仓库，别把不同作者的同名文件当成同一个。

第二步：算显存，别只算权重

显存占用是三块相加：

总显存 ≈ 权重占用 + KV cache + 运行时开销

权重占用：hy4 是 42.2 亿参数，乘以每参数字节数。Q4_K_M 约 0.65 字节/参数，Q8_0 约 1.06 字节/参数，FP16 是 2 字节/参数。

KV cache：随上下文长度线性增长。hy4 的官方配置是 36 层、8 个 KV 头、头维度 128，BF16 下每个 token 约占 144KB：

KV cache ≈ 2 × 层数 × KV 头数 × 头维度 × 上下文长度 × 字节数
       ≈ 2 × 36 × 8 × 128 × 上下文长度 × 2 字节
       ≈ 144KB × 上下文长度

对照实际：4K 上下文约 0.56GB，32K 上下文约 4.6GB。hy4 的官方最大位置长度是 262144（256K），但把窗口开满意味着 KV cache 要吃掉十几 GB，真正能用多少上下文要按显存倒推，而不是照抄标称值。

hy4 是稠密 4B 模型，KV cache 相对温和；这也是它比同体量 MoE 更适合长上下文场景的原因之一——MoE 的权重虽然只激活一部分，但总权重仍要占显存。

运行时开销：CUDA 上下文、计算缓冲区、量化元数据，经验值 0.3–1GB。

一张速查表

Q4_K_M（2.61GB）+ 4K 上下文：约 2.6 + 0.6 + 0.5 ≈ 3.7GB，4GB 卡紧张但可行；Q4_K_M + 32K 上下文：约 2.6 + 4.6 + 0.5 ≈ 7.7GB，8GB 卡以上才稳；Q5_K_M + 8K 上下文：约 3.0 + 1.1 + 0.5 ≈ 4.6GB，6GB 卡可行；Q8_0（4.49GB）已经吃掉大半张卡。数字是估算区间，实际以 nvidia-smi 首次加载后的读数为准。

第三步：用 llama.cpp 跑起来

bash

# 1. 下载社区 GGUF（以 bartowski 仓库为例，文件名按仓库实际列表调整）
huggingface-cli download bartowski/tencent_Hunyuan-4B-Instruct-GGUF \
  Q4_K_M.gguf --local-dir ./hunyuan4b

# 2. 直接命令行对话，验证权重能不能加载
./llama-cli -m ./hunyuan4b/Q4_K_M.gguf -p "用三句话解释什么是 MoE" -n 256

# 3. 起 OpenAI 兼容服务
./llama-server -m ./hunyuan4b/Q4_K_M.gguf \
  --host 127.0.0.1 --port 8080 \
  --ctx-size 32768 \
  --jinja

服务起来之后，现有客户端只需要改两个参数：

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8080/v1",
    api_key="not-needed",
)
resp = client.chat.completions.create(
    model="local-model",
    messages=[{"role": "user", "content": "你好，介绍一下你自己"}],
)
print(resp.choices[0].message.content)

模型名可以随便填，但别真填成 API ID

llama-server 对模型名不做强校验，本地服务填 local-model 即可。如果你的客户端会拿模型名去请求远端目录，注意区分本地端点与云端端点。

第四步：用 Ollama 跑（生态兼容性最好）

Ollama 的价值在于它自带一整套模型管理和 API 生态，Open WebUI、Dify、Cursor 等工具默认就认它。

bash

# 1. 创建模型（Modelfile 里用本地 GGUF 路径）
cat > Modelfile <<'EOF'
FROM ./hunyuan4b/Q4_K_M.gguf
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""
PARAMETER num_ctx 8192
PARAMETER temperature 0.7
EOF

ollama create hy4-local -f Modelfile

# 2. 验证
ollama run hy4-local "写一个 Python 函数解析 ISO 8601 时间"

# 3. 查看与删除
ollama list
ollama show hy4-local
ollama rm hy4-local

TEMPLATE 一定要按模型卡来

聊天模板对不上是最隐蔽的坑：模型能加载、能出字，但回答质量很差，看起来像模型本身不行。模板要从对应模型卡的 Usage 段落抄，不同代际的混元模板不一定相同，抄错就重抄。

第五步：Mac 与端侧的另外两条路

平台	路线	说明
Apple Silicon	`mlx-community/Hunyuan-4B-Instruct-4bit`	通过 mlx-lm 直接加载，统一内存下量化收益直接
端侧 / 嵌入式	`taobao-mnn/Hunyuan-4B-Instruct-MNN`	阿里 MNN 推理引擎，面向移动与嵌入式设备
老 CPU	社区 GGUF 的 Q4/Q5	llama.cpp 的 CPU 后端，4B 是现实上限

bash

# MLX 快速验证
pip install mlx-lm
python -m mlx_lm.generate --model mlx-community/Hunyuan-4B-Instruct-4bit \
  --prompt "用一句话解释向量数据库" --max-tokens 128

速度预期怎么估才靠谱

不要信别人的 token/s 数字。CPU、内存带宽、上下文长度、后端实现都会改变结果。正确做法是在自己的机器上测：固定提示词、固定生成长度，跑三轮取中位数，并同时记录显存峰值。把这组数字记下来，后续换量化档位时才有可比基线。

排查表：按报错找原因

现象	最可能的原因	处理
加载时报架构不支持	llama.cpp 版本太旧	升级引擎到最新版重新编译
加载成功但输出乱码	聊天模板不对	按模型卡改 TEMPLATE / `--jinja`
显存不足被kill	只算了权重，漏了 KV cache	降上下文长度或换更低量化档
每 token 极慢	显存不足导致部分层卸载到内存	换更小量化或更小的模型
首 token 很慢，之后正常	首次加载权重进显存	正常现象，预热即可
工具调用格式不生效	模板缺少工具调用段	按模型卡补 tool 段或换模板
输出重复、不断句	采样参数极端	调 temperature / top_p、确认有 EOS token

FAQ

hy4 有官方 GGUF 吗？

没有。官方给的是 FP8、GPTQ-Int4、AWQ-Int4 三份权重，hy4 的 GGUF 全部来自社区转换，bartowski、mradermacher、gabriellarson、DevQuasar、Disya 等都有。相比之下 A13B 有官方 GGUF。

第一次部署 hy4 应该选哪个量化？

Q4_K_M。它在 4B 级别上几乎无损，显存量级友好，是绝大多数场景的默认答案。等流程跑通、确认质量够用，再考虑升到 Q5_K_M。

怎么知道自己需要多少显存？

用三件套公式估算：权重占用（参数量乘每参数字节数）加 KV cache（随上下文长度线性增长）加 0.3 到 1GB 的运行时开销。估完之后一定要在实际机器上量一次 nvidia-smi 的峰值。

llama.cpp 和 Ollama 怎么选？

要极致性能和可调参数用 llama.cpp；要生态兼容（Open WebUI、Dify、Cursor 这类工具开箱即用）用 Ollama。两者都能暴露 OpenAI 兼容端点，模型文件可以共用。

跑出来效果很差，是模型不行吗？

多数情况是聊天模板不对。混元不同代际的模板不完全一样，模板错了模型照样能出字但质量崩坏。先按模型卡校模板，再去怀疑量化档位。

Mac 上跑 hy4 用哪个方案？

用 mlx-community 的 Hunyuan-4B-Instruct-4bit 转换，配合 mlx-lm 直接加载。Apple Silicon 的统一内存让 4-bit 的收益最直接，不需要额外的显存/内存划分。

混元能通过 API 调用吗？

EXAIV 当前云端目录未接入混元，以模型目录实时列表为准。混元需要自部署，部署完成后在你的网络内部暴露 OpenAI 兼容端点即可。

数据来源

量化档位与仓库清单会随社区更新变化，本文以采样时状态为准；显存数字为经验估算，实际以你机器上的实测为准。

国产模型一个 Key 调用

EXAIV 已接入 Qwen / DeepSeek / Kimi / GLM 等国产开源模型，OpenAI 兼容端点，注册即用

查看充值套餐

← 返回博客

hy4ggufllama.cppollama本地部署显存混元

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

2026年11月10日by EXAIV Team

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

30 秒版本

第一步：选量化档位

档位	权重大小（实测 bartowski 仓库文件体积）	质量	适合
IQ4_XS	2.37 GB	接近 Q4	显存紧张的等价 Q4 路线
Q3_K_M	2.17 GB	可感知损失	4GB 卡勉强可跑
Q4_K_M	2.61 GB	几乎无损	默认选择，绝大多数场景够用
Q5_K_M	3.03 GB	接近原始	显存够就选它
Q6_K	3.47 GB	几乎等同原精度	长文本生成的保守选择
Q8_0	4.49 GB	基本等同原精度	做精度对照基准用
FP16（原始权重）	约 8.4 GB	原始	需要 FP16 推理栈时

原始权重体积来自模型卡参数：Hunyuan-4B-Instruct 是 42.2 亿参数，BF16 存储约 8.4GB。

选档位的实际顺序

社区 hy4 GGUF 的作者与仓库：

作者	仓库特点
bartowski	档位最全、社区下载量最高，适合作为默认来源
mradermacher	提供标准量化与 i1 系列量化两套
gabriellarson	常规量化为主
DevQuasar	常规量化为主
Disya	Q8_0 为主，适合做高精度对照
Edge-Quant	单档位 Q4_K_M，极简选择

下载时注意区分文件名里的量化标记（Q4_K_M、Q5_K_M、Q8_0）和来源仓库，别把不同作者的同名文件当成同一个。

第二步：算显存，别只算权重

显存占用是三块相加：

总显存 ≈ 权重占用 + KV cache + 运行时开销

权重占用：hy4 是 42.2 亿参数，乘以每参数字节数。Q4_K_M 约 0.65 字节/参数，Q8_0 约 1.06 字节/参数，FP16 是 2 字节/参数。

KV cache：随上下文长度线性增长。hy4 的官方配置是 36 层、8 个 KV 头、头维度 128，BF16 下每个 token 约占 144KB：

KV cache ≈ 2 × 层数 × KV 头数 × 头维度 × 上下文长度 × 字节数
       ≈ 2 × 36 × 8 × 128 × 上下文长度 × 2 字节
       ≈ 144KB × 上下文长度

hy4 是稠密 4B 模型，KV cache 相对温和；这也是它比同体量 MoE 更适合长上下文场景的原因之一——MoE 的权重虽然只激活一部分，但总权重仍要占显存。

运行时开销：CUDA 上下文、计算缓冲区、量化元数据，经验值 0.3–1GB。

一张速查表

第三步：用 llama.cpp 跑起来

bash

# 1. 下载社区 GGUF（以 bartowski 仓库为例，文件名按仓库实际列表调整）
huggingface-cli download bartowski/tencent_Hunyuan-4B-Instruct-GGUF \
  Q4_K_M.gguf --local-dir ./hunyuan4b

# 2. 直接命令行对话，验证权重能不能加载
./llama-cli -m ./hunyuan4b/Q4_K_M.gguf -p "用三句话解释什么是 MoE" -n 256

# 3. 起 OpenAI 兼容服务
./llama-server -m ./hunyuan4b/Q4_K_M.gguf \
  --host 127.0.0.1 --port 8080 \
  --ctx-size 32768 \
  --jinja

服务起来之后，现有客户端只需要改两个参数：

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8080/v1",
    api_key="not-needed",
)
resp = client.chat.completions.create(
    model="local-model",
    messages=[{"role": "user", "content": "你好，介绍一下你自己"}],
)
print(resp.choices[0].message.content)

模型名可以随便填，但别真填成 API ID

llama-server 对模型名不做强校验，本地服务填 local-model 即可。如果你的客户端会拿模型名去请求远端目录，注意区分本地端点与云端端点。

第四步：用 Ollama 跑（生态兼容性最好）

Ollama 的价值在于它自带一整套模型管理和 API 生态，Open WebUI、Dify、Cursor 等工具默认就认它。

bash

# 1. 创建模型（Modelfile 里用本地 GGUF 路径）
cat > Modelfile <<'EOF'
FROM ./hunyuan4b/Q4_K_M.gguf
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""
PARAMETER num_ctx 8192
PARAMETER temperature 0.7
EOF

ollama create hy4-local -f Modelfile

# 2. 验证
ollama run hy4-local "写一个 Python 函数解析 ISO 8601 时间"

# 3. 查看与删除
ollama list
ollama show hy4-local
ollama rm hy4-local

TEMPLATE 一定要按模型卡来

第五步：Mac 与端侧的另外两条路

平台	路线	说明
Apple Silicon	`mlx-community/Hunyuan-4B-Instruct-4bit`	通过 mlx-lm 直接加载，统一内存下量化收益直接
端侧 / 嵌入式	`taobao-mnn/Hunyuan-4B-Instruct-MNN`	阿里 MNN 推理引擎，面向移动与嵌入式设备
老 CPU	社区 GGUF 的 Q4/Q5	llama.cpp 的 CPU 后端，4B 是现实上限

bash

# MLX 快速验证
pip install mlx-lm
python -m mlx_lm.generate --model mlx-community/Hunyuan-4B-Instruct-4bit \
  --prompt "用一句话解释向量数据库" --max-tokens 128

速度预期怎么估才靠谱

排查表：按报错找原因

现象	最可能的原因	处理
加载时报架构不支持	llama.cpp 版本太旧	升级引擎到最新版重新编译
加载成功但输出乱码	聊天模板不对	按模型卡改 TEMPLATE / `--jinja`
显存不足被kill	只算了权重，漏了 KV cache	降上下文长度或换更低量化档
每 token 极慢	显存不足导致部分层卸载到内存	换更小量化或更小的模型
首 token 很慢，之后正常	首次加载权重进显存	正常现象，预热即可
工具调用格式不生效	模板缺少工具调用段	按模型卡补 tool 段或换模板
输出重复、不断句	采样参数极端	调 temperature / top_p、确认有 EOS token

FAQ

hy4 有官方 GGUF 吗？

第一次部署 hy4 应该选哪个量化？

Q4_K_M。它在 4B 级别上几乎无损，显存量级友好，是绝大多数场景的默认答案。等流程跑通、确认质量够用，再考虑升到 Q5_K_M。

怎么知道自己需要多少显存？

llama.cpp 和 Ollama 怎么选？

要极致性能和可调参数用 llama.cpp；要生态兼容（Open WebUI、Dify、Cursor 这类工具开箱即用）用 Ollama。两者都能暴露 OpenAI 兼容端点，模型文件可以共用。

跑出来效果很差，是模型不行吗？

多数情况是聊天模板不对。混元不同代际的模板不完全一样，模板错了模型照样能出字但质量崩坏。先按模型卡校模板，再去怀疑量化档位。

Mac 上跑 hy4 用哪个方案？

用 mlx-community 的 Hunyuan-4B-Instruct-4bit 转换，配合 mlx-lm 直接加载。Apple Silicon 的统一内存让 4-bit 的收益最直接，不需要额外的显存/内存划分。

混元能通过 API 调用吗？

EXAIV 当前云端目录未接入混元，以模型目录实时列表为准。混元需要自部署，部署完成后在你的网络内部暴露 OpenAI 兼容端点即可。

数据来源

量化档位与仓库清单会随社区更新变化，本文以采样时状态为准；显存数字为经验估算，实际以你机器上的实测为准。

国产模型一个 Key 调用

EXAIV 已接入 Qwen / DeepSeek / Kimi / GLM 等国产开源模型，OpenAI 兼容端点，注册即用

查看充值套餐

← 返回博客

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

第一步：选量化档位

第二步：算显存，别只算权重

第三步：用 llama.cpp 跑起来

第四步：用 Ollama 跑（生态兼容性最好）

第五步：Mac 与端侧的另外两条路

排查表：按报错找原因

FAQ

相关阅读

数据来源

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

hy4 GGUF 本地部署实操：量化档位、显存测算与 llama.cpp / Ollama 命令

第一步：选量化档位

第二步：算显存，别只算权重

第三步：用 llama.cpp 跑起来

第四步：用 Ollama 跑（生态兼容性最好）

第五步：Mac 与端侧的另外两条路

排查表：按报错找原因

FAQ

相关阅读

数据来源