Gemma4¶

1 简介¶

Gemma4 是 Gemma 系列语言模型，包含密集（Dense）和混合专家（Mixture-of-Experts，MoE）两种变体，适用于通用文本生成、推理和指令跟随等场景。

本文档介绍 Gemma4 在 Atlas A2、Atlas A3 和 950PR&950DT 产品上的主要验证步骤，包括支持特性、前提条件、安装、单节点在线部署、功能验证、离线推理、精度与性能评估、性能调优和常见问题。

本文档基于最新的 vLLM Ascend main 分支编写。在此版本中，Gemma4 支持在 Atlas A2、Atlas A3 和 950PR&950DT 产品上运行。

2 支持特性¶

请参阅支持特性列表，获取模型支持矩阵，包括 BF16、chunked prefill（分块预填充）、自动前缀缓存、张量并行、专家并行和 ACLGraph 支持。

请参阅特性指南，了解特性配置详情。

Gemma4 在 Atlas A2、Atlas A3 和 950PR&950DT 产品上同时支持 eager 执行和 ACLGraph 执行。对于图执行，FULL_DECODE_ONLY 可减少解码阶段的调度开销，同时也支持 PIECEWISE。

3 前提条件¶

3.1 模型权重¶

将 Gemma4 模型权重下载到本地或共享目录，例如 /root/.cache/。在以下示例中，请将 /root/.cache/path/to/gemma4 替换为您的实际模型路径。

以下示例假定为单节点且有可见 NPU。命令以 4 个可见 NPU 为例。请根据模型大小和可用设备调整 ASCEND_RT_VISIBLE_DEVICES 和 --tensor-parallel-size。

4 安装¶

4.1 镜像获取¶

如需预构建镜像，请联系华为工程师获取与目标硬件匹配的镜像和软件栈。

环境准备就绪后，验证 NPU 设备是否可见：

npu-smi info

预期结果：npu-smi info 列出预期的 Ascend 设备。

4.2 源码安装¶

从 main 分支安装 vLLM Ascend：

git clone https://github.com/vllm-project/vllm-ascend.git
cd vllm-ascend
pip install -e .

要验证源码安装，请运行以下命令：

python -c "import vllm_ascend; print(vllm_ascend.__version__)"

预期结果：命令成功打印已安装的 vLLM Ascend 版本，且无错误信息。

5 在线服务部署¶

5.1 单节点在线部署¶

单节点部署将 Prefill 和 Decode 均运行在同一节点上，适用于功能验证和单节点服务。以下示例展示 eager 和 ACLGraph 的启动命令。命令以 4 个可见 NPU 为例。使用不同设备数量时，请调整 ASCEND_RT_VISIBLE_DEVICES 和 --tensor-parallel-size。

说明：本教程中 /root/.cache/path/to/gemma4 为占位符，请替换为您的实际 Gemma4 模型路径。

Eager 模式¶

使用 eager 模式作为功能验证的基线配置。

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export MODEL_PATH=/root/.cache/path/to/gemma4

vllm serve ${MODEL_PATH} \
  --served-model-name gemma4 \
  --trust-remote-code \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --enforce-eager

ACLGraph 模式¶

当需要图执行时，使用 ACLGraph 模式。FULL_DECODE_ONLY 可减少解码阶段的调度开销。

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export MODEL_PATH=/root/.cache/path/to/gemma4

vllm serve ${MODEL_PATH} \
  --served-model-name gemma4 \
  --trust-remote-code \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}'

常见问题提示：如果服务启动失败、HBM 不足或请求未按预期调度，请先参阅公共常见问题，再查看第 10 节中模型相关的常见问题。

关键参数¶

• --tensor-parallel-size：设置张量并行大小。请根据模型大小和可用 NPU 设备进行调整。
• --enable-expert-parallel：当部署方案使用 EP 时，为 MoE 变体启用专家并行。
• --max-model-len：设置单个请求的最大输入加输出长度。仅在 KV cache 充足时增大该值。
• --enforce-eager：启用 eager 执行以进行基线验证。
• --compilation-config：配置图执行。FULL_DECODE_ONLY 可减少解码阶段的调度开销，同时也支持 PIECEWISE。
• --trust-remote-code：允许 vLLM 在模型仓库需要时加载模型特定代码。

服务验证¶

服务启动后，发送请求以验证模型的基本功能。

curl http://127.0.0.1:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4",
    "prompt": "Explain why graph execution improves decode performance.",
    "max_tokens": 128,
    "temperature": 0
  }'

预期结果：HTTP 状态码为 200，JSON 响应中包含带有生成文本的 choices 字段。

5.2 多卡部署¶

本教程提供 Gemma4 在 Atlas A2、Atlas A3 和 950PR&950DT 产品上的单节点多卡部署示例。对于不同的模型大小或设备数量，请根据可用 NPU 调整 ASCEND_RT_VISIBLE_DEVICES 和 --tensor-parallel-size。

6 功能验证¶

服务启动后，可通过 OpenAI 兼容 API 调用 Gemma4。

6.1 Completions API¶

curl http://127.0.0.1:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4",
    "prompt": "Explain why graph execution improves decode performance.",
    "max_tokens": 128,
    "temperature": 0
  }'

6.2 Chat Completions API¶

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4",
    "messages": [
      {"role": "user", "content": "Explain why graph execution improves decode performance."}
    ],
    "max_tokens": 128,
    "temperature": 0
  }'

预期结果：请求返回 HTTP 200，JSON 响应中包含 choices 字段，内含模型生成的文本。

6.3 离线推理¶

from vllm import LLM, SamplingParams

llm = LLM(
    model="/root/.cache/path/to/gemma4",
    trust_remote_code=True,
    tensor_parallel_size=4,
    compilation_config={"cudagraph_mode": "FULL_DECODE_ONLY"},
)

sampling_params = SamplingParams(temperature=0, max_tokens=128)
outputs = llm.generate(
    ["Explain why graph execution improves decode performance."],
    sampling_params,
)

for output in outputs:
    print(output.outputs[0].text)

7 精度评估¶

注意：max_tokens、temperature 和停止符等后处理参数，应与模型权重的 generation_config.json 中定义的参数保持一致。

7.1 使用 AISBench¶

详细信息请参阅使用 AISBench。

7.2 使用 Language Model Evaluation Harness¶

以 GPQA-Diamond 数据集为例，以在线模式对所选 Gemma4 稠密或 MoE 模型运行精度评估。安装和使用详情请参阅使用 lm_eval。

lm_eval \
  --model local-completions \
  --model_args model=gemma4,base_url=http://127.0.0.1:8000/v1/completions,tokenized_requests=False,trust_remote_code=True \
  --tasks gpqa_diamond \
  --output_path ./

8 性能评估¶

8.1 使用 AISBench¶

详细信息请参阅使用 AISBench 进行性能评估。

8.2 使用 vLLM Benchmark¶

详细信息请参阅 vLLM benchmark。

9 性能调优¶

9.1 推荐配置¶

以下配置仅供参考。最优配置取决于硬件资源、模型规模、最大输入/输出长度、请求并发度、前缀缓存命中率，以及所选的 Gemma4 权重是稠密模型还是 MoE 模型。请根据实际工作负载调整第 9.2 节中的参数。

9.2 调优指南¶

通用调优方法请参阅公共性能调优文档。

详细功能描述请参阅特性矩阵。

推荐的调优顺序：

1. 使用 eager 模式验证模型加载和生成正确性。
2. 为生成服务启用 ACLGraph 并设置 FULL_DECODE_ONLY，并与 eager 基线进行对比。
3. 根据所需上下文长度选择 --max-model-len。长上下文会增加 KV 缓存占用，因此若发生 OOM，请减小 --max-num-seqs。
4. 调整 --max-num-batched-tokens。较大的值可以提升 prefill 效率，但会消耗更多激活内存。
5. 根据服务并发度调整 --max-num-seqs。超过该值的请求将在队列中等待。
6. 当需要更多 KV 缓存时调整 --gpu-memory-utilization，同时为运行时内存波动预留足够的 HBM 余量。
7. 对于 MoE 变体，根据模型规模和部署方案选择张量并行或专家并行，并在相同请求负载下对比吞吐量和时延。

9.3 模型专属优化¶

10 常见问题¶

有关常见的环境、安装和通用参数问题，请参阅公共 FAQ。本节仅涵盖 Gemma4 的模型专属问题。

Q1：应优先使用哪种执行模式？¶

现象： 用户在初始部署时需要在使用 eager 模式还是 ACLGraph 模式之间做出选择。

原因： eager 模式更易于作为基线使用，而 ACLGraph 模式旨在减少服务期间的图调度开销。

解决方案： 首先使用 eager 模式验证模型加载和基本生成。确认基线后，使用 ACLGraph 模式配合 FULL_DECODE_ONLY 进行生成服务。

Q2：如何配置模型路径？¶

现象： 由于找不到模型路径或加载了错误的模型，服务无法启动。

原因： 示例使用 /root/.cache/path/to/gemma4 作为占位符。

解决方案： 将 MODEL_PATH 以及所有基准测试或离线推理模型路径替换为实际的本地 Gemma4 模型目录。

Q3：如何部署 Gemma4 MoE 变体？¶

现象： 用户需要决定 MoE 变体是使用张量并行还是专家并行。

原因： MoE 模型可以根据模型大小、设备数量和服务负载采用不同的并行策略。

解决方案： 从用于基线的相同张量并行配置开始。如果部署方案使用专家并行，请添加 --enable-expert-parallel，并在相同负载下比较吞吐量、延迟和内存使用。