如何在本地运行 Gemma 4 31B：Unsloth、Ollama、llama.cpp 和 HuggingFace

Google DeepMind 在 2026 年初发布了 Gemma 4，其中 31B 指令微调版本刚好踩在一个甜点上：参数量够大，能在推理基准测试中和专有模型掰手腕；又够小，在一块不错的消费级 GPU 上就能跑。它在 MMLU Pro 上拿了 85.2%，在 AIME 2026 上拿了 89.2%（不用工具），这个成绩已经能和参数量翻倍的模型放在一起聊了。

问题一直都在——"我到底怎么跑这玩意儿？" 一个 30.7B 参数的全精度模型大概需要 62GB 的 VRAM，没人会在单张显卡上放这么多。但选对量化方法、用对工具，你可以在 24GB 的 RTX 4090 上跑起来，甚至在 16GB 显卡上部分卸载到 CPU 也能用。如果你需要 GPU 实例但不想长期投入，我们推荐用 LightNode 作为你的 VPS 服务商。

这篇指南覆盖四种方法，其中 Unsloth 是大多数人的首选推荐。

目录

1. Gemma 4 模型家族概览
2. 硬件需求
3. 方法一：Unsloth Studio（推荐）
4. 方法二：Ollama
5. 方法三：llama.cpp
6. 方法四：HuggingFace Transformers
7. 理解 GGUF 量化格式
8. 性能优化技巧
9. 常见问题排查
10. 你该选哪种方法？

Gemma 4 模型家族概览

Gemma 4 有四个尺寸。选对很重要，因为它们之间的硬件需求跨度挺大。

变体	总参数	激活参数	上下文长度	模态	最佳用途
E2B	5.1B	2.3B（等效）	128K	文本、图像、音频	手机、树莓派
E4B	8B	4.5B（等效）	128K	文本、图像、音频	笔记本、纯 CPU
26B A4B (MoE)	25.2B	3.8B（激活）	256K	文本、图像	快速推理、省显存
31B（Dense）	30.7B	30.7B	256K	文本、图像	最高质量

26B A4B 是最聪明的那一个：总参数 25.2B，但推理时只有 3.8B 被激活，这得益于混合专家架构（128 个专家中激活 8 个，外加 1 个共享专家）。它的推理速度几乎和 4B 模型一样快，质量却接近完整的 31B。如果你的 GPU 有 12-16GB VRAM，26B A4B 的 Q4 量化版本可能是你的最佳选择。

31B Dense 就是本篇指南的重点。它是满血模型，每次前向传播所有参数全部参与。质量最高，硬件要求也最高。

四个变体都支持可配置的思考模式（链式推理）、原生系统提示、函数调用，以及 140 多种语言。

硬件需求

在选方法之前，先搞清楚你手上的硬件是什么水平。

Gemma 4 31B-it

量化	所需 VRAM	质量损失	典型硬件
FP16（全精度）	~62 GB	无	A100、多卡
Q8_0（8-bit）	~32 GB	可忽略	RTX 4090（24GB）+ CPU 卸载
Q5_K_M（5-bit）	~22 GB	极小	RTX 4090、RTX 3090
Q4_K_M（4-bit）	~18 GB	较小	RTX 4080、RTX 3090
Q3_K_M（3-bit）	~14 GB	明显	RTX 4070、部分卸载

Gemma 4 26B A4B (MoE)

量化	所需 VRAM	质量损失	典型硬件
Q5_K_M	~14 GB	极小	RTX 4070 Ti
Q4_K_M	~10 GB	较小	RTX 4070、RTX 3080
Q3_K_M	~8 GB	明显	RTX 4060 Ti 8GB

如果你只有 CPU，E4B 或 E2B 变体可以轻松跑起来。31B 在 CPU 上技术上可行，但速度感人（现代 CPU 上大概 1-3 tokens/秒）。

内存需求：在 VRAM 之外，还需要额外 8-16GB 系统内存给运行时开销。如果有层卸载到 CPU，需要更多。

方法一：Unsloth Studio（推荐）

Unsloth 是运行 Gemma 4 最简单的方式。它是一个 Web UI，把模型下载、量化选择和推理全部打包在一起。支持 Windows、Linux、macOS 和 WSL。

为什么选 Unsloth

• 一键搜索并从 HuggingFace 下载模型
• 自动为你挑选适合硬件的 GGUF 量化版本
• 内置聊天界面，支持图片、PDF 和文档
• 内置工具调用和网页搜索
• 代码执行沙箱
• 不用折腾命令行

安装

macOS、Linux、WSL：

curl -fsSL https://unsloth.ai/install.sh | sh

Windows（PowerShell）：

irm https://unsloth.ai/install.ps1 | iex

Docker：

docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

启动

unsloth studio -H 0.0.0.0 -p 8888

在浏览器打开 http://localhost:8888，就能看到 Unsloth Studio 的界面了。

运行 Gemma 4 31B

1. 搜索模型：在模型搜索栏输入 gemma-4-31B
2. 选择量化：Unsloth 托管了预量化的 GGUF 文件。24GB 显卡选 Q4_K_M 或 Q5_K_M；16GB 显卡选 Q3_K_M
3. 下载：点击下载。Q4_K_M 版本大约 18GB
4. 开始聊天：下载完成后，模型会自动加载到聊天界面

Unsloth 为 Gemma 4 31B-it 提供以下 GGUF 变体：

文件	大小	量化
gemma-4-31B-it-Q3_K_M.gguf	~14 GB	3-bit（均衡）
gemma-4-31B-it-Q4_K_M.gguf	~18 GB	4-bit（推荐）
gemma-4-31B-it-Q5_K_M.gguf	~22 GB	5-bit（高质量）
gemma-4-31B-it-Q6_K.gguf	~26 GB	6-bit（近乎无损）
gemma-4-31B-it-Q8_0.gguf	~32 GB	8-bit（几乎无损）

HuggingFace 仓库地址：unsloth/gemma-4-31B-it-GGUF。

使用聊天界面

Unsloth Studio 的聊天支持以下功能：

• 文本对话，带思考模式开关
• 图片上传：拖放图片进行视觉问答
• PDF/DOCX 上传：提取并讨论文档内容
• 代码执行：模型可以在沙箱中编写和测试代码
• 自定义系统提示：设定行为和人设

要开启 Gemma 4 的思考模式，在聊天设置里打开 "Thinking" 选项。这会激活链式推理，模型在给出最终答案之前会先一步步分析问题。

用 Unsloth 微调

如果你不只是想推理，还想做训练，Unsloth 也能搞定：

• LoRA 微调：训练适配器，VRAM 占用减少最高 70%
• GRPO 强化学习：目前最高效的 RL 库
• 数据配方（Data Recipes）：从 PDF、CSV、DOCX 文件自动创建训练数据集
• 多 GPU 支持：已上线，持续改进中

要对 Gemma 4 31B 做微调，你至少需要一张 24GB 的 GPU，使用 QLoRA（4-bit 量化训练）。

更新 Unsloth

再次运行同样的安装命令即可：

# macOS/Linux/WSL
curl -fsSL https://unsloth.ai/install.sh | sh

# Windows
irm https://unsloth.ai/install.ps1 | iex

方法二：Ollama

如果你更喜欢命令行，Ollama 是最快的上手方式。它自动处理模型下载、GPU 检测和模型服务。

安装

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# 从 https://ollama.com/download 下载

运行 Gemma 4

# 拉取并运行 31B 模型
ollama run gemma4:31b-it

# 或者用更小的 MoE 变体，更省显存
ollama run gemma4:26b-a4b-it

# 或者更小的 Dense 模型
ollama run gemma4:e4b-it
ollama run gemma4:e2b-it

Ollama 默认自动使用 Q4_K_M 量化。如果你想用别的量化级别：

# 指定量化的运行
ollama run gemma4:31b-it-q5_K_M

使用 API

Ollama 在 11434 端口暴露本地 API：

import requests

response = requests.post('http://localhost:11434/api/chat', json={
    "model": "gemma4:31b-it",
    "messages": [
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Write a Python function to merge two sorted lists."}
    ],
    "stream": False
})

print(response.json()['message']['content'])

Ollama 的优缺点

优点：零配置，自动 GPU 检测，简洁的命令行，自带 API 服务，模型管理简单。

缺点：量化选项比 llama.cpp 少，不是所有模型都支持内置图片功能（检查当前兼容性），对推理参数的控制较少。

方法三：llama.cpp

想要对量化、内存使用和推理参数有最大控制权，llama.cpp 是不二之选。Ollama 和 Unsloth 底层就是用它做 GGUF 推理的。

从源码编译

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# 支持 CUDA（NVIDIA）
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

# 支持 Metal（macOS Apple Silicon）
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j$(nproc)

# 纯 CPU
cmake -B build
cmake --build build --config Release -j$(nproc)

下载 GGUF 模型

从 Unsloth 的 HuggingFace 仓库下载量化模型：

# 安装 huggingface-cli
pip install huggingface-hub

# 下载 Q4_K_M（推荐 24GB 显卡使用）
huggingface-cli download unsloth/gemma-4-31B-it-GGUF \
  gemma-4-31B-it-Q4_K_M.gguf \
  --local-dir ./models

# 或者 Q5_K_M，质量更好
huggingface-cli download unsloth/gemma-4-31B-it-GGUF \
  gemma-4-31B-it-Q5_K_M.gguf \
  --local-dir ./models

运行模型

# 基础聊天
./build/bin/llama-cli \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 99 \
  -c 8192 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -p "You are a helpful assistant.\nUser: Explain quantum computing in simple terms.\nAssistant:"

关键参数说明：

• -ngl 99：把所有层卸载到 GPU。如果 VRAM 不够就减小这个数字（比如 -ngl 40 大约卸载三分之二的层）
• -c 8192：上下文长度（token 数）。处理长文档可以增加到 256K，但上下文越长越吃显存
• --temp 1.0：Google 推荐给 Gemma 4 用 temperature=1.0
• --top-p 0.95 和 --top-k 64：推荐的采样参数

启动服务器

./build/bin/llama-server \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 99 \
  -c 8192 \
  --host 0.0.0.0 \
  --port 8080 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64

然后在浏览器访问 http://localhost:8080，或者调用兼容 OpenAI 的 API：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="unused")

response = client.chat.completions.create(
    model="gemma-4-31b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Write a Rust function to reverse a linked list."}
    ]
)

print(response.choices[0].message.content)

GPU 卸载策略

如果你的 GPU 显存不够加载完整模型，可以把层在 GPU 和 CPU 之间分配：

# 16GB 显卡跑 Q4 模型（总大小约 18GB）
# 大约卸载 40 层到 GPU，其余用 CPU
./build/bin/llama-cli \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 40 \
  -c 4096

速度比全 GPU 卸载慢，但能装进小显存显卡。根据你的 CPU 和卸载层数，大概 5-15 tokens/秒。

方法四：HuggingFace Transformers

如果你在开发应用，需要编程级别的控制，HuggingFace Transformers 让你直接访问模型，支持全精度或自定义量化。

安装

pip install -U transformers torch accelerate

如果需要图片支持：

pip install -U transformers torch torchvision accelerate

全精度运行（需要 62GB+ VRAM）

from transformers import AutoProcessor, AutoModelForCausalLM

MODEL_ID = "google/gemma-4-31B-it"

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    dtype="auto",
    device_map="auto"
)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain the difference between TCP and UDP."},
]

text = processor.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=False
)

inputs = processor(text=text, return_tensors="pt").to(model.device)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=1024)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
result = processor.parse_response(response)
print(result)

4-bit 量化运行（18GB VRAM）

from transformers import AutoProcessor, AutoModelForCausalLM, BitsAndBytesConfig

MODEL_ID = "google/gemma-4-31B-it"

# 4-bit 量化配置
quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16
)

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    quantization_config=quantization_config,
    device_map="auto"
)

处理图片

31B 模型支持文本和图片输入：

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-31B-it"

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(
    MODEL_ID,
    dtype="auto",
    device_map="auto"
)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://example.com/photo.jpg"},
            {"type": "text", "text": "Describe what you see in this image."}
        ]
    }
]

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
).to(model.device)

input_len = inputs["input_ids"].shape[-1]
outputs = model.generate(**inputs, max_new_tokens=512)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
result = processor.parse_response(response)
print(result)

开启思考模式

Gemma 4 支持链式推理。设置 enable_thinking=True 即可启用：

text = processor.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=True  # 激活推理模式
)

开启思考模式后，模型会先输出内部推理过程，再给出最终答案。用 processor.parse_response(response) 可以把思考过程和最终答案分开。

理解 GGUF 量化格式

下载 GGUF 文件时你会看到很多后缀，这里说说它们实际代表什么。

格式	比特数	大小（31B）	适用场景
Q8_0	8-bit	~32 GB	最佳质量，需要 32GB+ VRAM
Q6_K	6-bit	~26 GB	近乎无损，24GB+ VRAM
Q5_K_M	5-bit	~22 GB	质量/体积的甜点
Q4_K_M	4-bit	~18 GB	最佳平衡，适配 24GB 显卡
Q3_K_M	3-bit	~14 GB	小显存显卡，有一定质量损失
Q2_K	2-bit	~10 GB	万不得已的选择，质量下降明显

我的建议：24GB 显卡选 Q4_K_M，能多出 4GB 空间就选 Q5_K_M。Q4_K_M 和 Q5_K_M 在基准测试上有差距，但日常使用基本感觉不出来。低于 Q3_K_M 就不太值得了，除非真的没有其他选择。

_K_M 后缀意思是"K-量化，中等"。还有 _K_S（小，压缩更多）和 _K_L（大，压缩更少）变体。_K_M 是默认推荐。

性能优化技巧

上下文长度管理

Gemma 4 31B 支持最长 256K token 的上下文，但上下文中的每个 token 都要吃显存。几个实用建议：

• 4K token：只要能装下模型的显卡都没问题
• 8K token：大多数对话的标准配置，依然很轻松
• 32K token：根据量化级别额外需要 4-6GB 显存
• 128K+ token：需要大量显存或积极卸载

从 -c 8192 开始，需要时再增加。

采样参数

Google 为 Gemma 4 推荐的设置：

temperature = 1.0
top_p = 0.95
top_k = 64

这和大多数模型不一样。别给 Gemma 4 用 temperature=0.7，它就是用 temperature=1.0 训练的，在这个设置下效果最好。

Flash Attention

如果你用 HuggingFace Transformers，开启 Flash Attention 可以加快推理、降低内存占用：

model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    attn_implementation="flash_attention_2",
    device_map="auto"
)

需要 pip install flash-attn，以及兼容的 GPU（大多数 NVIDIA RTX 系列都行）。

多 GPU 设置

如果你有多张显卡，Transformers 中的 device_map="auto" 会自动处理分配。llama.cpp 这样做：

./build/bin/llama-cli \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 99 \
  -ts 1,1 \  # 在 2 张 GPU 之间平均分配
  -c 8192

常见问题排查

显存不足（CUDA OOM）

最常见的问题。按绝望程度依次列出解决方案：

1. 用更低的量化：从 Q5 换到 Q4，或从 Q4 换到 Q3
2. 减少上下文长度：把 -c 从 8192 降到 4096 或 2048
3. 卸载到 CPU：减小 -ngl 来卸载部分层
4. 用 26B A4B MoE 变体：同等质量档次，显存只需一小部分
5. 用 E4B 变体：什么机器都能跑

CPU 推理太慢

如果你在用 CPU 跑，31B 模型大概 1-3 tokens/秒。可选方案：

• 换用 E4B 或 E2B 模型（CPU 上 10-20 tok/s）
• 用 GPU 云实例（LightNode 提供 GPU VPS 选项）
• 编译 llama.cpp 时启用你 CPU 的指令集（AVX2、AVX-512）

模型下载失败

Q4_K_M 文件大约 18GB。如果下载一直失败：

# 用 huggingface-cli 的断点续传功能
huggingface-cli download unsloth/gemma-4-31B-it-GGUF \
  gemma-4-31B-it-Q4_K_M.gguf \
  --local-dir ./models \
  --local-dir-use-symlinks False

或者用支持断点续传的下载工具。HuggingFace CDN 对大文件有时候不太稳定。

"Model not supported" 错误

确保你用的是最新版本的工具。Gemma 4 很新，旧版的 llama.cpp、Ollama 和 Transformers 都不支持：

# 更新 llama.cpp
cd llama.cpp && git pull && cmake --build build --config Release -j$(nproc)

# 更新 Ollama
ollama pull gemma4:31b-it  # 如果需要会自动更新

# 更新 Transformers
pip install -U transformers

你该选哪种方法？

场景	最佳方法
想要图形界面，不想碰终端	Unsloth Studio
想要最快上手，命令行没问题	Ollama
需要对推理有最大控制	llama.cpp
在开发应用	HuggingFace Transformers
显存有限（8-16GB）	Unsloth 或 Ollama，用 Q3/Q4
有 24GB+ VRAM	任何方法都行，用 Q4_K_M 或 Q5_K_M
需要图片理解能力	Unsloth Studio 或 HuggingFace Transformers
想做微调	Unsloth（内置 LoRA/GRPO 训练）

对于大多数刚入门的朋友，Unsloth Studio 是最省心的路。装好它，搜索 Gemma 4，选一个适合你显卡的量化版本，然后开始聊天。从安装到第一次对话，整个过程大概 15 分钟。

如果你终端玩得溜、只是想跑模型，Ollama 两个命令就搞定了。而如果你需要编程接口或者在模型之上构建应用，HuggingFace Transformers 配合 4-bit 量化给你完整的 Python API。

总结

在本地跑 Gemma 4 31B 已经变得相当实用了。一年前，同等质量水平的 30B 模型还是个研究项目。现在用 Unsloth 或 Ollama，15 分钟就能搞定，而且能跑在你现在就能买到的消费级硬件上。

这个模型本身在推理、编程和多模态任务上足以抗衡专有方案。256K 上下文、内置思考模式、图片理解和函数调用，让它在真正的实际工作中派上用场，而不只是拿来玩玩。

如果要在远程 GPU 上部署模型，LightNode 提供 GPU VPS 实例，按小时计费，需要的时候开一台，用完关掉就行。

Gemma 4 模型卡（HuggingFace） 里有完整的技术细节，Unsloth GGUF 仓库 里有所有量化版本可供下载。