最新谷歌Gemma-4-31B-it开源模型实战深度测评：从vLLM启动到OpenCode接入的全链路教程

部署环境配置如下：一台搭载了 NVIDIA A100 80G GPU 的 Ubuntu 服务器。开始操作前，服务器上已预先完成 NVIDIA 驱动、Docker 以及 NVIDIA Container Toolkit 的安装与配置；在模型运行层面，我们选用了 Gemma 4 专用的 vLLM 镜像，目标模型为 google/gemma-4-31B-it，本地模型文件也已准备就绪。

本次部署任务聚焦五个核心目标：

1. 在服务器上成功加载并运行 google/gemma-4-31B-it 模型；
2. 借助 vLLM 对外提供一个兼容 OpenAI 接口规范的服务；
3. 将模型进程绑定至第二块 GPU 上运行；
4. 确保局域网内的其他终端能够通过 HTTP 接口顺利调用；
5. 为后续集成 OpenCode 工具链铺平道路。

目标明确之后，我们开始逐步推进落地。

一、模型下载

在正式动手之前，需要说明的是 Google Gemma-4 系列模型的构成。根据 Google 官方文档，Gemma 4 目前提供四种不同规模的模型版本：

• Gemma 4 E2B
• Gemma 4 E4B
• Gemma 4 26B-A4B
• Gemma 4 31B

其中，E2B 和 E4B 属于轻量级模型，适用于端侧或资源受限的部署场景；26B-A4B 是一款混合专家（MoE）架构模型，总参数量庞大，但推理时仅激活部分参数；31B 则是大规模密集型模型，综合能力更强，更适合作为服务器端的核心推理引擎。

从多模态能力来看，Gemma 4 系列原生支持文本与图像输入；E2B 和 E4B 额外支持音频输入，而 31B 以及 26B-A4B 主要面向文本和图像处理场景。Google 官方模型卡片提供了更详细的参数说明：31B 模型拥有约 307 亿参数，属于 Dense 模型，支持文本与图像，但不包含音频编码器。

我们本次实际部署的模型是 google/gemma-4-31B-it。后缀 it 代表 instruction-tuned 版本，也就是经过指令微调的版本，特别适合对话、问答、代码生成以及工具调用等交互式任务，而非单纯的预训练版本。

1.1 模型来源与下载

模型直接从 Hugging Face 的官方仓库获取：google/gemma-4-31B-it。在网络通畅的环境中，可以利用 Hugging Face CLI 或 Python 工具将整个模型目录拉取至本地。模型页面同时提供了模型卡片、文件清单以及版本信息，可作为部署前校验文件完整性的依据。

1.2 确认模型路径

首先确认本地模型目录存在且为完整的模型根目录。本次使用的实际目录是：

/home/ubuntu/Test/Workspace/Models/google/gemma-4-31B-it

执行 ls -lah /home/ubuntu/Test/Workspace/Models/google/gemma-4-31B-it | head 后，可以看到目录中包含以下关键文件：

• config.json
• tokenizer.json 或相关的 tokenizer 文件
• generation_config.json
• model.safetensors.index.json
• 若干 *.safetensors 文件

这里需要特别提醒：挂载到容器内的必须是模型根目录本身，而不是它的父目录，更不能是 Hugging Face 缓存目录的上层。否则 vLLM 很可能在启动时直接报错，提示“模型目录无效”。

二、准备 Gemma 4 专用镜像

本次部署没有沿用之前用于运行 Qwen 或 GLM 的旧镜像，而是切换为 Gemma 4 专用的 vLLM 镜像。原因在于：即便对旧环境进行升级，依然容易在 Gemma 4 上暴露各种兼容性问题，例如 gemma4 架构识别失败、Transformers 版本不匹配、回退至 Transformers backend 后权重映射错误，以及 tool calling 与 reasoning 参数支持不完整。因此，最稳妥的方案就是直接使用 Gemma 4 对应的 vLLM 专用运行环境。

2.1 镜像获取途径

vLLM 官方在 Gemma 4 的部署文档中已标明对应的镜像标签：vllm/vllm-openai:gemma4 与 vllm/vllm-openai:gemma4-cu130。如果服务器可以直接访问 Docker Hub，直接拉取即可；若网络受限，也可在其他机器上下载后导出为 tar 包，再上传至目标服务器。

2.2 已有镜像包时的导入方法

假设镜像包已上传至服务器，例如 ~/vllm-openai-gemma4-x86_64-cu129.tar，接下来执行：

docker load -i ~/vllm-openai-gemma4-x86_64-cu129.tar

然后运行 docker images | grep vllm-openai 进行确认。导入成功后，会看到类似 vllm/vllm-openai gemma4-x86_64-cu129 的输出信息。至此，服务器端运行 Gemma 4 所需的镜像环境便准备就绪，可以进入下一步的容器创建与服务启动环节。

三、创建部署容器

为便于排查问题，我没有采用一条 docker run 命令直接启动服务，而是选择更稳妥的方式：先创建容器，再手动启动服务。具体流程分两步：先启动容器，随后进入容器内手动执行 vllm serve。这种做法的优势在于：容器状态与服务状态分离，方便反复调整启动参数，也利于排查显存不足、上下文过大、tool calling 参数缺失等问题。

3.1 删除旧容器

先清理可能残留的旧容器：

docker stop gemma4_31b_gpu1 2>/dev/null || true

docker rm gemma4_31b_gpu1 2>/dev/null || true

3.2 创建新容器

由于这台 A100 集群配备了两张 GPU，第一张卡已用于其他任务，为保证稳定性，我们将模型绑定在第二张 GPU 上：

docker run -itd --name gemma4_31b_gpu1 --entrypoint /bin/bash --ipc=host --network host --shm-size 16G --gpus '"device=1"' -v /home/ubuntu/Test/Workspace/Models/google/gemma-4-31B-it:/models/gemma-4-31B-it vllm/vllm-openai:gemma4-x86_64-cu129

这里几个关键参数需要着重说明：

• --entrypoint /bin/bash 强制覆盖镜像默认入口，避免镜像自动执行预设命令。
• --gpus '"device=1"' 表示容器仅映射宿主机的第二张 GPU。容器内部看到的 cuda:0，实际上是宿主机的第二张卡。
• --network host 使服务直接使用宿主机网络，便于后续局域网内访问 8000 端口。
• --ipc=host 与 --shm-size 16G 用于防止大模型初始化时因共享内存不足而引发异常。

3.3 检查容器状态

执行 docker ps -a | grep gemma4_31b_gpu1，状态正常即表示容器已启动：

0dc54912df12 vllm/vllm-openai:gemma4-x86_64-cu129 "/bin/bash" 22 seconds ago Up 21 seconds gemma4_31b_gpu1

四、进入容器并启动 vLLM 服务

4.1 进入容器

docker exec -it gemma4_31b_gpu1 /bin/bash

进入后，命令行提示符通常会切换为容器内部的样式。

4.2 启动基础服务

如果只是想先验证模型能否正常运行，可以使用基础版的启动参数：

vllm serve /models/gemma-4-31B-it --served-model-name gemma-4-31b-it --tensor-parallel-size 1 --max-model-len 8192 --gpu-memory-utilization 0.90 --host 0.0.0.0 --port 8000

不过，如果目标是后续接入 OpenCode，建议直接一步到位开启 tool calling 与 reasoning 支持：--tool-call-parser gemma4 和 --reasoning-parser gemma4。Gemma 4 的工具调用和推理模式都需要显式指定相应的 parser。

4.3 启动适配 OpenCode 的版本

vllm serve /models/gemma-4-31B-it --served-model-name gemma-4-31b-it --tensor-parallel-size 1 --max-model-len 32288 --gpu-memory-utilization 0.90 --enable-auto-tool-choice --tool-call-parser gemma4 --reasoning-parser gemma4 --host 0.0.0.0 --port 8000

解释几个关键参数：

• --served-model-name gemma-4-31b-it 指定 API 层对外暴露的模型名称，后续 curl 请求与 OpenCode 配置均需使用此名称。
• --tensor-parallel-size 1 本次部署目标是单卡运行，因此固定为 1。
• --max-model-len 32288 这是最终成功运行的最大上下文长度。前期使用 8192 可以启动服务，但在 OpenCode 等长上下文场景下可能不足。
• --gpu-memory-utilization 0.90 控制 vLLM 可占用的显存比例。值越高，KV cache 空间越大，但显存压力也相应增加。
• --enable-auto-tool-choice OpenCode build / agent 模式的关键参数，不开启会导致后续报错。

看到服务启动成功的界面，说明 vLLM 已正常运行。不过，在此过程中也遇到了一些问题，值得记录。

4.4 启动失败的常见原因与处理

这一步最常见的问题有两类。

问题一：第二张 GPU 上存在残留进程

如果之前的模型或旧服务未被彻底关闭，vLLM 会在启动阶段直接报显存不足。此时应在宿主机执行 nvidia-smi -i 1，检查第二张 GPU 上是否仍有旧进程占用资源。

问题二：上下文过大导致单卡无法启动

如果直接使用大上下文失败，可以先退回更保守的参数，例如：

vllm serve /models/gemma-4-31B-it --served-model-name gemma-4-31b-it --tensor-parallel-size 1 --max-model-len 12288 --gpu-memory-utilization 0.85 --enable-auto-tool-choice --tool-call-parser gemma4 --reasoning-parser gemma4 --host 0.0.0.0 --port 8000

建议的做法是从能稳定启动的配置开始，再逐步增加上下文长度，而不是一开始就将参数拉到极限。当然，如果硬件资源充裕，直接使用大 token 配置也可能不会出现问题。

五、验证服务是否成功启动

服务启动后，先不要急于接入 OpenCode，而应通过基础的 HTTP 请求验证服务状态。

5.1 查看模型列表

在服务器上另开一个终端，执行：

curl http://127.0.0.1:8000/v1/models

成功的话会返回一个 JSON，其中包含 id":"gemma-4-31b-it" 这样的字段。这表明服务已启动，OpenAI-Compatible API 可正常使用。

5.2 测试聊天接口（服务器本机）

上述命令之后，可以简单测试一下对话能力：

curl http://127.0.0.1:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "gemma-4-31b-it","messages": [{"role": "user", "content": "你好，请做一个简短自我介绍。"}],"max_tokens": 128,"temperature": 0.7}'

5.3 测试聊天接口（局域网其他机器）

假设服务器的局域网地址是 xxx.168.15.121，确保你的电脑与服务器处于同一局域网内，然后在你的电脑上执行：

curl http://xxx.168.15.121:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "gemma-4-31b-it","messages": [{"role": "user", "content": "你好，请做一个简短自我介绍。"}],"max_tokens": 128,"temperature": 0.7}'

这里有一个容易混淆的点：在服务器本机测试时，地址使用 127.0.0.1；在局域网其他机器测试时，地址必须替换为服务器的实际 IP，两者不能混用。

5.4 确认模型运行在第二张 GPU

回到宿主机执行 nvidia-smi -i 1，可以看到 vLLM/python 进程以及显存占用情况。如果当前没有请求，GPU 利用率为 0%。发送一个请求后，GPU 利用率会上升，说明模型确实在第二张 GPU 上运行。

六、配置 OpenCode 接入局域网服务

vLLM 服务本身运行正常后，下一步就是将 OpenCode 接入进来。OpenCode 的安装方法较为简单，网上有大量教程，此处不再赘述。

OpenCode 的配置文件默认路径为 ~/.config/opencode/opencode.json。在运行 OpenCode 的机器上执行：

mkdir -p ~/.config/opencode

cat > ~/.config/opencode/opencode.json <<'EOF'

{"$schema": "https://opencode.ai/config.json","provider": {"vllm": {"npm": "@ai-sdk/openai-compatible","name": "Gemma 4 31B IT LAN vLLM","options": {"baseURL": "http://192.168.15.121:8000/v1","apiKey": "EMPTY"},"models": {"gemma-4-31b-it": {"name": "Gemma 4 31B IT","limit": {"context": 32288,"output": 1024}}}}},"model": "vllm/gemma-4-31b-it"}

EOF

这里最关键的两点：

1. baseURL 必须填写服务器的局域网 IP，而不是 127.0.0.1。
2. context 参数需要与服务端的 --max-model-len 保持一致。如果后续修改了服务端的上下文长度，这里也要同步更新。

配置完成后，在终端输入 opencode 即可启动使用。

七、Google Gemma-4-31B-it 性能测试

当模型能够稳定启动，并通过 /v1/chat/completions 正常返回结果后，接下来需要关注的不再是“能不能用”，而是“实际性能如何”。本节从两个维度进行了测试：基础回答能力与单卡部署下的生成速度。

7.1 回答能力测试

回答能力测试选用了两类典型的提示词：一类偏重代码生成，另一类偏重逻辑推理。选择这两类任务是因为它们在实际应用中较为常见，且结果优劣易于判断。

（1）代码生成测试

模型能够直接生成可运行 Python 版本的快速排序实现，并进一步说明其在平均情况、最优情况与最坏情况下的时间复杂度。这表明模型具备稳定的基础代码生成能力，能够胜任常见的编程辅助任务。

（2）逻辑推理测试

针对一个更偏逻辑过程的问题进行测试。从实际输出来看，模型能够分步骤给出完整的运输方案，并补充说明“羊既会被狼吃，又会吃菜，因此必须始终处于被隔离或陪同状态”这一核心约束。这说明模型在结构化推理任务上同样表现良好。

7.2 文本生成速度测试

回答质量固然重要，但部署完成后还需要评估一个实际指标：生成速度是否可接受。本次采用最贴近真实使用场景的方式：直接通过 curl 访问 /v1/chat/completions 接口，并在命令前加上 time 命令，统计一次较长输出请求的整体耗时。

从实际测试结果来看，本次请求返回的统计信息如下：prompt_tokens = 38，completion_tokens = 1500，total_tokens = 1538。同时，终端 time 给出的总耗时约为 64.90 s。由此可以计算出粗略的速度估算：每秒生成 token 数 ≈ 1500 / 64.90 ≈ 23.1 token/s。

这个数值并非严格的理论峰值，而是基于一次真实请求测得的端到端结果，因此更贴近实际使用体验。对于当前这套单卡 A100 80G + Gemma-4-31B-it + OpenAI-Compatible API 服务化部署的场景来说，这个速度已足以满足日常测试、局域网调用以及一般交互式使用需求。

结语

回顾整个 google/gemma-4-31B-it 的部署过程，最花时间的并非敲击命令本身，而是持续解决那些看似细小的问题。正是这些细节，决定了一个模型是仅仅能够启动，还是真正能够投入实用。

还有一点印象颇深。Gemma-4-31B-it 并非那种特别话多的模型。面对一个简单问题，它不会展开成长篇大论，而是经常把答案收得更紧、回得更短，但关键信息一点不落。某种意义上，这正是指令微调最有价值的地方：不是让模型更能说，而是让模型更懂任务、更会克制、更知道如何围绕目标作答。

来源：互联网