运行更流畅的 Gemma 4 31B IT NVFP4，具备更好的智能体推理与工具调用能力，易于部署 • 256k 上下文 • MTP • 原生图像和视频支持
智能体工作流评估正在进行中，即将发布。获取地址：https://github.com/MiaAI-Lab/Gemma-4-31B-IT-NVFP4-Recipe…

MiaAI-Lab/Gemma-4-31B-IT-NVFP4-Recipe

来源：https://github.com/MiaAI-Lab/Gemma-4-31B-IT-NVFP4-Recipe

Gemma 4 31B IT — NVFP4 服务

通过 vLLM 以 4 位 NVFP4 量化形式运行 Google Gemma 4 31B IT，提供 OpenAI 兼容端点、多 Token 预测投机解码、工具调用以及思考/推理支持。自动从 Hugging Face 下载并缓存两个模型——只需设置你的 token 即可运行。

模型

草稿模型运行 4 个轻量级解码器层，采用仅 Q 注意力机制，并与目标模型共享 KV 缓存。每步可生成最多 4 个草稿 Token 用于投机解码——在不牺牲输出质量的前提下加速生成。

快速开始

前提条件

• Docker 并安装 NVIDIA Container Toolkit（已完成 nvidia-ctk）
• NVIDIA GPU（已在 DGX Spark——GB10 GPU + 128 GB 统一内存上测试）
• Hugging Face Token，且具有访问以下两个受限模型的权限：
  • https://huggingface.co/nvidia/Gemma-4-31B-IT-NVFP4
  • https://huggingface.co/google/gemma-4-31B-it-assistant

启动服务

HF_TOKEN=hf_your_token_here ./start.sh

首次运行时脚本会下载两个模型（缓存至 ~/.cache/huggingface），随后启动 vLLM 容器，并等待其就绪。

使用 API

curl http://localhost:8888/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nvidia/Gemma-4-31B-IT-NVFP4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

停止服务

./stop.sh

特性

🧠 思考/推理

默认启用。模型会在最终回复前以 thought 块输出推理过程：

<|turn|>model
<|channel|>thought
The user is asking about...
Here's the answer...

可按请求禁用：在 API 调用中传递 chat_template_kwargs: {"enable_thinking": false}。

🛠️ 工具调用

通过 gemma4 解析器原生支持工具调用。所有配置已预置——只需在请求中传入 tools：

curl http://localhost:8888/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nvidia/Gemma-4-31B-IT-NVFP4",
    "messages": [{"role": "user", "content": "What'\''s the weather in Paris?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": ["location"]
        }
      }
    }]
  }'

🖼️ 多模态（图像 + 视频）

模型通过共享视觉编码器支持图像和视频。音频已定义 Token ID，但 NVFP4 量化权重不包含音频编码器（audio_config: null）。

图像示例：

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
        {"type": "text", "text": "What's in this image?"}
      ]
    }
  ]
}

视频示例：

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}},
        {"type": "text", "text": "Summarize this video"}
      ]
    }
  ]
}

限制：每个提示最多可包含 4 张图像 或 1 个视频（如果支持则为 1 个音频）。

⚡ MTP 投机解码

多 Token 预测使用轻量级助手模型每步生成 4 个草稿 Token。在以下场景中效果最佳：

• 批量 工作负载
• 长上下文 生成
• 系统提示密集型 应用（前缀缓存同样生效）

推荐客户端设置

根据 Google 对 Gemma 4 的建议：

可在每个请求中传递，或在客户端设置为默认值。

并发与性能

在 NVIDIA DGX Spark（GB10 GPU，128 GB 统一内存）上测试。

限制

0.70 显存利用率下的 KV 缓存

实际吞吐量

调优以获得更高并发度

--gpu-memory-utilization 设为 0.70 留有余量。可以通过提高该值来增加并发度——更多的 KV 缓存块可以容纳，从而支持更多并发序列，但会占用更少的空闲 GPU 内存：

# 在 start.sh 中，为了更高并发度：
--gpu-memory-utilization 0.95 --max-num-seqs 4 --max-num-batched-tokens 16384

使用 nvidia-smi 监控显存，确保不会 OOM。

配置

环境变量

关键 vLLM 标志

每个请求的覆盖

客户端可以在每个请求中覆盖模板 kwargs：

{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": false
  }
}

文件

.
├── start.sh                 # 启动 vLLM 容器（自动下载模型）
├── stop.sh                  # 优雅停止容器
├── chat_template.jinja      # Gemma 4 规范聊天模板（390 行）
├── README.md                # 本文件
├── .gitignore               # 忽略运行时工件
├── .vllm.log                # 容器日志（被 git 忽略）
├── .vllm.pid                # 容器 PID（被 git 忽略）
└── .cache/                  # Triton 缓存（被 git 忽略）

Python 客户端示例

OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8888/v1",
    api_key="not-needed",
)

response = client.chat.completions.create(
    model="nvidia/Gemma-4-31B-IT-NVFP4",
    messages=[{"role": "user", "content": "Write a quick sort in Python"}],
    temperature=0.2,
)

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

带工具调用

tools = [
    {
        "type": "function",
        "function": {
            "name": "run_code",
            "description": "Execute Python code and return stdout",
            "parameters": {
                "type": "object",
                "properties": {
                    "code": {"type": "string"}
                },
                "required": ["code"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="nvidia/Gemma-4-31B-IT-NVFP4",
    messages=[{"role": "user", "content": "Calculate 42 * 37"}],
    tools=tools,
)

排错指南

许可证

模型权重受 Gemma 许可证管理 (https://www.kaggle.com/models/google/gemma-4/license)。本仓库的脚本和配置采用 MIT 许可证。

参考

• Gemma 4 技术报告 (https://goo.gle/Gemma4Report)
• NVIDIA ModelOpt NVFP4 (https://github.com/NVIDIA/TensorRT-Model-Optimizer)
• vLLM 文档 (https://docs.vllm.ai/en/latest/)
• Hugging Face: nvidia/Gemma-4-31B-IT-NVFP4 (https://huggingface.co/nvidia/Gemma-4-31B-IT-NVFP4)