Gemma4 部署教程¶

1 引言¶

Gemma4 是 Gemma 系列语言模型，包含密集型和混合专家（MoE）变体，适用于通用文本生成、推理和指令遵循场景。

本文档描述了在 Atlas A2、Atlas A3 和 Ascend 950 产品上对 Gemma4 进行的主要验证步骤，包括支持特性、前提条件、安装、单节点在线部署、功能验证、离线推理、精度与性能评估、性能调优以及常见问题解答。

本文档基于最新的 vLLM Ascend 主分支编写。在此版本中，Gemma4 在 Atlas A2、Atlas A3 和 Ascend 950 产品上受支持。

2 支持特性¶

请参考支持的模型获取模型支持矩阵，包括 BF16、分块预填充、自动前缀缓存、张量并行、专家并行和 ACLGraph 支持。

请参考特性指南获取特性配置详情。

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

3 前提条件¶

3.1 模型权重¶

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

模型类型	描述	推荐硬件
Gemma4 密集型模型	密集型 Gemma4 权重。	单个 Atlas A2、Atlas A3 或 Ascend 950 节点。根据模型大小调整可见 NPU 数量。
Gemma4 MoE 模型	混合专家 Gemma4 权重。	单个 Atlas A2、Atlas A3 或 Ascend 950 节点。根据模型大小和部署计划使用张量并行或专家并行。

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

3.2 验证多节点通信（可选）¶

如果需要多节点部署，请按照验证多节点通信环境验证多节点通信环境。

4 安装¶

4.1 镜像可用性¶

如果您需要预构建镜像，请联系华为工程师获取适用于您目标硬件的镜像和软件栈。

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

npu-smi info

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

4.2 源码安装¶

从主分支安装 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 缓存充足时增加。
--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 多卡部署¶

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

6 功能验证¶

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

6.1 补全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 聊天补全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 使用语言模型评估工具¶

以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基准测试¶

详情请参考vLLM基准测试。

9 性能调优¶

9.1 推荐配置¶

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

场景	部署模式	NPU总数	模型类型	关键考虑因素
功能验证	单节点在线服务	4	稠密或MoE	首先使用eager模式验证模型加载和基础生成。
生成服务	单节点在线服务	4	稠密或MoE	使用带有`FULL_DECODE_ONLY`的ACLGraph以减少解码调度开销。
长上下文	单节点在线服务	4	稠密或MoE	仅在KV缓存充足时增加`--max-model-len`；若发生OOM则降低并发数。
MoE服务	单节点在线服务	4	MoE	根据模型大小和部署计划使用张量并行或专家并行。

9.2 调优指南¶

通用调优方法请参考公开性能调优文档。

详细功能描述请参考功能指南。

推荐调优顺序：

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

9.3 模型特定优化¶

优化项	启用方式	收益	备注
全解码ACLGraph	`--compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}'`	减少解码调度开销。	在生成解码token时推荐使用。
分段ACLGraph	`--compilation-config '{"cudagraph_mode": "PIECEWISE"}'`	启用分段图执行。	在需要分段图执行时支持。
张量并行	`--tensor-parallel-size`	将模型计算拆分到多个NPU上。	根据模型大小和可用设备调整。
专家并行	`--enable-expert-parallel`	为MoE变体分配专家。	仅对使用EP的MoE部署计划启用。

10 常见问题¶

常见环境、安装和通用参数问题请参考常见问题。本节仅涵盖Gemma4的模型特定问题。

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

现象： 用户在初始部署时需要在eager模式和ACLGraph模式之间进行选择。

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

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

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

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

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

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

问题3：如何部署Gemma4 MoE变体？¶

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

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

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