如何5分钟在本地跑起gemma-4-31B-it-GGUF：从零开始的新手部署教程

想在自己的电脑上私有化部署 Google 最新开源多模态大模型吗？gemma-4-31B-it-GGUF 仓库由 Unsloth 提供，收录了Gemma 4 31B指令微调版的全部 GGUF 量化版本（Q2 到 Q8、BF16），开箱即用，支持文本与图像输入、最长 256K 上下文，Apache 2.0 协议可自由商用。本教程带你从零开始，5 分钟在本地跑起它。

一、这个仓库里有什么？

先花 1 分钟了解仓库结构，下载时心里有数：

如何选量化版本？

按显存对号入座即可 🎯：

💡 带UD前缀的是 Unsloth Dynamic 动态量化，按层重要性分配比特数，同体积下质量更好；-XL后缀为更大文件内的高精度变体。

二、部署前准备：安装 llama.cpp

Gemma 4 需要较新的 llama.cpp（MTP 功能于 2026-06-07 合并进主干）。以 NVIDIA 显卡为例，克隆源码并编译：

git clone https://github.com/ggml-org/llama.cpp cd llama.cpp # -DCMAKE_CUDA_ARCHITECTURES 按你的显卡填写：89(RTX 4090)、90(H100)、100(B200) cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES=90 cmake --build build --config Release -j --target llama-server

更多构建细节可参考 MTP/README.md。

三、5分钟快速启动 llama-server

本仓库是一个镜像仓库，可以直接克隆到本地，然后指向本地文件启动：

git clone https://gitcode.com/hf_mirrors/unsloth/gemma-4-31B-it-GGUF cd gemma-4-31B-it-GGUF ./path/to/llama-server \ -m gemma-4-31B-it-Q4_K_M.gguf \ --mmproj mmproj-BF16.gguf \ -ngl 999 -fa on

参数小白注释 📝：

• -m：主模型文件，换成你选定的量化版本即可
• --mmproj：视觉投影文件，加上它模型才能"看图"
• -ngl 999：把所有层卸载到 GPU
• -fa on：开启 Flash Attention，省显存提速

启动后浏览器打开http://localhost:8080，即可在 Web 界面与模型对话、上传图片。

⚠️ 注意：仓库内文件较大，若只是下载单个文件，建议用hf download之类的工具按需拉取，不必 clone 整个仓库。

四、进阶：用 MTP 推测解码再提速 40% 🚀

MTP/README.md 中给出了实测数据：在单卡 B200 上跑Q4_K_M，开启 MTP 后从70 tok/s 提升到 101 tok/s（草稿接受率 0.78）。

新版 llama.cpp 能自动发现仓库根目录的 mtp-gemma-4-31B-it.gguf，直接加两个参数即可：

./path/to/llama-server \ -m gemma-4-31B-it-Q4_K_M.gguf \ --spec-type draft-mtp --spec-draft-n-max 4 \ -ngl 999 -fa on

想要指定精度或多卡部署，可改用显式写法：--model-draft MTP/mtp-gemma-4-31B-it-Q8_0.gguf（详见 MTP/README.md）。

五、最佳采样参数（官方推荐）

按照 README.md 的 Best Practices，无论何种任务都建议使用统一采样配置：

其他小贴士：

• 多模态输入：图片/音频放在提示词前面，效果最佳
• 图像分辨率：支持 70~1120 的视觉 token 预算，OCR 读小字用高值，分类/看图说话用低值
• 多轮对话：历史消息中只保留最终回答，不要保留中间思考内容

六、常见问题

Q：内存/显存不够，模型卡住怎么办？换更低的量化版本（如UD-IQ2_XXS），或减少-ngl让部分层留在内存。

Q：加载 MTP 文件报错gemma4-assistant架构不认识？你的 llama.cpp 太旧了，请编译 2026-06-07 之后的版本。

Q：只想要文字能力，能省掉 mmproj 吗？可以，不传--mmproj参数即可，还能省一点显存。

至此，一台 24GB 显卡的机器上，Gemma 4 31B 已经可以流畅本地运行了。它支持 140+ 语言、256K 长上下文和图像理解，配合 MTP 加速，日常问答、文档解析、代码任务都值得一试。