场景对比：同样是本地部署多模态模型，用 Ollama 拉取图像问答模型看似两步搞定，但当并发请求超过 5 个，延迟就会飙到无法忍受。而把它交给 vLLM——一个专为大模型推理加速的引擎——同样的 Gemma-4 31B 模型，吞吐量能翻数倍，延迟压到百毫秒级。这篇文章带你从零搭建一个生产可用的 Gemma-4 多模态推理服务，哪怕你不写生产代码，也能看清技术选型的关键差异。
1. 环境准备：你需要一台怎样的机器？
Gemma-4-31B 是 Google 最新的图像理解大模型（image-text-to-text），有 31B 参数。推理时使用 bfloat16 精度，显存占用约 62 GB，所以起步配置是：
- GPU：至少 1 块 NVIDIA A100 80GB（或 H100 80GB）
- 显存不足？别急，后文会给出更小的 E4B（4B 参数）版本替代方案
软件依赖很简单：
- Ubuntu 20.04+（推荐）或 Windows WSL2
- Python 3.10 – 3.12
- NVIDIA 驱动版本 ≥ 525.60.13，CUDA 12.1 工具包
你可以用 nvidia-smi 确认驱动和 CUDA 版本：
nvidia-smi
# 关注右上角的 CUDA Version，需 ≥ 12.1
2. 安装 vLLM 0.21.0
先用 conda 或 venv 创建干净的环境，再装 vLLM。注意要指定版本，确保多模态能力稳定。
# 创建并激活环境
python -m venv vllm_env
source vllm_env/bin/activate
# 安装 vLLM（会连带安装必要的 transformers、torch）
pip install vllm==0.21.0
# 验证安装
python -c "import vllm; print(vllm.__version__)"
# 应输出 0.21.0
如果安装时出现 FlashAttention 相关报错，可以先用 pip install flash-attn --no-build-isolation 手动安装，这是加速图像特征的注意力库。
3. 配置启动参数：一句话看懂关键开关
vLLM 的启动命令看似复杂，其实核心就三个事：装什么模型、给多大显存、开多长上下文。我们一项项拆。
模型选择：Gemma-4 完全兼容 vLLM 多模态推理，直接传入 HuggingFace 路径即可。官方模型是 google/gemma-4-31B-it，首次运行会自动下载权重（约 62 GB）。
显存利用：参数 --gpu-memory-utilization 0.95 告诉 vLLM“放心吃掉 95% 的显存”，剩下的留给系统开销。对 80 GB 显存来说，大约有 76 GB 用于缓存 KV 值，极大提升批处理效率。
上下文长度：多模态任务既要塞图像 token 又要塞文本，所以 --max-model-len 不能太低。推荐 8192 起步，既能满足高清图加长篇问答，也不会撑爆显存。
还有两个提速利器：
--dtype bfloat16：保持精度，比 float32 省一半显存--enforce-eager：关掉动态图编译，减少启动时间（调试期推荐开启）
把这些拼起来，启动命令就成型了——
4. 启动多模态服务
用 one-liner 拉起兼容 OpenAI API 的 HTTP 服务：
python -m vllm.entrypoints.openai.api_server \
--model google/gemma-4-31B-it \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 8192 \
--gpu-memory-utilization 0.95 \
--dtype bfloat16 \
--enforce-eager
# 看到 “Application startup complete.” 即启动成功
这时终端会打印模型加载日志，然后是 Uvicorn 的启动信息。整个过程在 A100 上大约 60–90 秒（取决于网络下载速度）。
5. 验证：让模型“看图说话”
启动后，服务提供 /v1/chat/completions 端点，和 ChatGPT 的调用方式一致。只是多了一个 image_url 字段。
我们用 curl 发一个请求，图片用公网 URL（亦可本地 base64）：
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-4-31B-it",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么？"},
{"type": "image_url", "image_url": {"url": "https://images.unsplash.com/photo-1518791841217-8f162f1e1131?w=600"}}
]
}
],
"max_tokens": 200
}'
# 返回 JSON 中包含 "一只猫趴在沙发上" 等描述（图片为猫）
如果你手头有本地图片，可以先用 Python 转成 base64，然后嵌入请求体：
import base64, requests
with open("cat.jpg", "rb") as f:
img_b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"http://localhost:8000/v1/chat/completions",
json={
"model": "google/gemma-4-31B-it",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图片"},
{"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"}}
]
}]
}
)
print(resp.json()["choices"][0]["message"]["content"])
返回一段描述，说明服务跑通。
6. 调优：从“能跑”到“跑得快”
默认配置已经可以处理日常测试，但生产环境还需几项调整。
并发与批处理：vLLM 内部会自动合并多条请求，一次前向计算处理一组，这叫连续批处理（Continuous Batching）。如果你有 10 个并发用户，可以适当增加 --max-num-seqs（默认 256），让引擎一次性调度更多序列。当然，别超过显存水位。
前缀缓存：--enable-prefix-caching 可以复用多轮对话中重复的系统提示词，降低首 token 延迟。多模态场景下，如果大量请求用同一张图，缓存也能生效。
低显存备选：万一显存冒烟，先试着把 --max-model-len 降到 4096，再把 --gpu-memory-utilization 设为 0.85。若还不行，就请出 Google 的轻量版 google/gemma-4-E4B-it，这是个 4B 参数的“any-to-any”模型，支持图像、文本互转，在 RTX 4090 24 GB 上就能跑，命令只需改模型名：
python -m vllm.entrypoints.openai.api_server \
--model google/gemma-4-E4B-it \
--host 0.0.0.0 --port 8000 \
--max-model-len 4096 \
--gpu-memory-utilization 0.9 \
--dtype float16
代价是回答质量和图像细节理解会稍有下降，适合对延迟敏感、精度不极端的场景。
常见报错急救
1. CUDA Out of Memory
日志出现 torch.cuda.OutOfMemoryError: CUDA out of memory。原因通常是 --max-model-len 或 --gpu-memory-utilization 设置过高。解法：先按上文降低这两个值；如果仍然 OOM，换用 4B 模型。绝对不要用 --swap-space 把显存溢到内存，那会让推理速度退化成幻灯片。
2. 多模态模型加载失败
若报错 ValueError: The model xxx is a multi-modal model, but this feature is not supported by the current vLLM installation.，说明 vLLM 没有激活多模态扩展。重新安装支持多模态的依赖：
pip uninstall vllm -y
pip install vllm==0.21.0 --no-cache-dir
pip install flash-attn --no-build-isolation
之后重启服务即可。
最小可行配置
如果你只想快速跑通一个多模态 API，复制下面这条命令（前提：已安装 vLLM，CUDA 就绪，有一块 80 GB GPU）：
python -m vllm.entrypoints.openai.api_server --model google/gemma-4-31B-it --host 0.0.0.0 --port 8000 --max-model-len 8192 --gpu-memory-utilization 0.95 --dtype bfloat16 --enforce-eager
这条命令不会占用太多额外磁盘，模型会在第一次启动时自动缓存至 ~/.cache/huggingface。从搭环境到发出第一个请求，顺利的话 10 分钟就能完成。至此，一个具备生产级性能的多模态推理服务就立起来了，你可以对接任何支持 OpenAI 格式的上层应用，或直接用它构建自己的看图问答产品。