NVIDIA Nemotron-3-Nano-30B-A3B 用户指南¶

本指南介绍如何使用 vLLM 运行 Nemotron-3-Nano-30B-A3B。有 FP8 和 BF16 版本。

部署步骤¶

我们建议使用 vLLM 0.12.0 版本以获得完整支持。不过，vLLM 0.11.2 也支持该模型。

拉取 Docker 镜像¶

拉取 vLLM v0.12.0 版本的 Docker 镜像。

pull_image.sh

# On x86_64 systems:
docker pull --platform linux/amd64 vllm/vllm-openai:v0.12.0
# On aarch64 systems:
# docker pull --platform linux/aarch64 vllm/vllm-openai:v0.12.0

docker tag vllm/vllm-openai:v0.12.0 vllm/vllm-openai:deploy

运行 Docker 容器¶

使用 Docker 镜像 vllm/vllm-openai:deploy 运行 Docker 容器。

run_container.sh

docker run -e HF_TOKEN="$HF_TOKEN" -e HF_HOME="$HF_HOME" --ipc=host --gpus all --entrypoint "/bin/bash" --rm -it vllm/vllm-openai:deploy

注意：如果需要，您可以使用 -v <local_path>:<path> 标志挂载其他目录和路径，例如挂载已下载的权重路径。

添加 -e HF_TOKEN="$HF_TOKEN" -e HF_HOME="$HF_HOME" 标志是为了使用您的 HuggingFace 令牌下载模型，并将下载的模型缓存到 $HF_HOME 中。有关这些环境变量的更多信息，请参阅 HuggingFace 文档；有关生成 HuggingFace 访问令牌的步骤，请参阅 HuggingFace 快速入门指南。

启动 vLLM 服务器¶

下面是一个使用 Nemotron-3-Nano-30B-A3B-BF16/FP8 模型启动 vLLM 服务器的命令示例。

launch_server.sh

# Set up a few environment variables for better performance for Blackwell architecture.
# They will be removed when the performance optimizations have been verified and enabled by default.

# Supported dtypes for this model are: FP8, BF16
DTYPE="FP8"

if [ "$DTYPE" = "FP8" ]; then
    # On FP8 only - set KV cache dtype to FP8
    KV_CACHE_DTYPE="fp8"

    # Enable use of FlashInfer FP8 MoE
    export VLLM_USE_FLASHINFER_MOE_FP8=1
    export VLLM_FLASHINFER_MOE_BACKEND=throughput
else
    KV_CACHE_DTYPE="auto"
fi

# Launch the vLLM server
vllm serve nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-$DTYPE \
  --trust-remote-code \
  --async-scheduling \
  --kv-cache-dtype $KV_CACHE_DTYPE \
  --tensor-parallel-size 1 &

服务器设置完成后，客户端现在可以向服务器发送提示请求并接收结果。

配置与参数¶

您可以使用这些标志来指定服务器运行的 IP 地址和端口

host：服务器的 IP 地址。默认情况下，它使用 127.0.0.1。
port：服务器监听的端口。默认情况下，它使用端口 8000。

以下是我们不建议更改或调整的配置标志

kv-cache-dtype：KV 缓存数据类型。使用 FP8 模型时，我们建议将其设置为 "fp8"，否则设置为 "auto"。
async-scheduling：启用异步调度以减少解码步骤之间的主机开销。我们建议始终添加此标志以获得最佳性能。

以下是一些您可以根据您的服务要求修改的可调参数

mamba-ssm-cache-dtype：Mamba SSM 缓存数据类型。为获得最佳模型精度，请设置为 float32。在使用 main 分支的 vLLM 或 0.12.0 及更新版本时，设置为 float16 可以提高性能，同时与 float32 相比，精度仅略有下降。在 vLLM 的 0.12.0 版本（含）之前的版本中，此模型的默认值为 bfloat16；在 vLLM 的更新版本或 main 分支中，默认值将是模型 HF config.json 文件中 mamba_ssm_cache_dtype 字段指定的值，如果不存在，则使用 float16。
tensor-parallel-size：张量并行大小。增加此值将增加用于推理的 GPU 数量。
max-num-seqs：每个批次的最大序列数。
默认情况下，在具有大内存大小的 GPU 上，此值设置为 1024 等大数字。
如果实际并发较小，将其设置为与最大并发匹配的较小数字可能会提高性能并改善每个用户的延迟。
max-model-len：每个请求的总令牌数（包括输入令牌和输出令牌）的最大值。
默认情况下，此值设置为模型支持的最大序列长度。
如果实际输入+输出序列长度短于默认值，将其设置为较小值可能会提高性能。
例如，如果最大输入序列长度为 1024 令牌，最大输出序列长度为 1024，则可以将其设置为 2048 以获得更好的性能。

有关如何调整这些可调参数以满足您的部署要求，请参阅“平衡吞吐量和延迟”部分。

### 性能基准测试

要进行性能基准测试，您可以使用 vllm bench serve 命令。

run_performance.sh

# Set DTYPE env var to match the benchmarked checkpoint (FP8 or BF16)
vllm bench serve \
  --host 0.0.0.0 \
  --port 8000 \
  --model nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-$DTYPE \
  --trust-remote-code \
  --dataset-name random \
  --random-input-len 1024 \
  --random-output-len 1024 \
  --num-warmups 20 \
  --ignore-eos \
  --max-concurrency 1024 \
  --num-prompts 2048 \
  --save-result --result-filename vllm_benchmark_serving_results.json

标志的解释

--dataset-name：用于基准测试的数据集。我们这里使用 random 数据集。
--random-input-len：指定平均输入序列长度。
--random-output-len：指定平均输出序列长度。
--num-warmups：指定预热请求的数量。这有助于确保基准测试反映实际的稳定状态性能，忽略初始开销。
--ignore-eos：在生成 eos（句子结束）标记时禁用提前返回。
--max-concurrency：最大并发请求数。我们建议将其与用于启动服务器的 --max-num-seqs 标志匹配。
--num-prompts：用于性能基准测试的提示总数。我们建议将其设置为 --max-concurrency 的至少五倍，以测量稳定状态性能。
--save-result --result-filename：性能基准测试结果的输出位置。

解读性能基准测试输出¶

在 H200 上使用 FP8 模型通过 vllm bench serve 命令生成的示例文本

============ Serving Benchmark Result ============
Successful requests:                     2048
Failed requests:                         0
Maximum request concurrency:             1024
Benchmark duration (s):                  132.49
Total input tokens:                      2097155
Total generated tokens:                  2097152
Request throughput (req/s):              15.46
Output token throughput (tok/s):         15828.30
Peak output token throughput (tok/s):    21157.00
Peak concurrent requests:                1088.00
Total Token throughput (tok/s):          31656.63
---------------Time to First Token----------------
Mean TTFT (ms):                          4490.58
Median TTFT (ms):                        1534.84
P99 TTFT (ms):                           15465.31
-----Time per Output Token (excl. 1st token)------
Mean TPOT (ms):                          59.45
Median TPOT (ms):                        61.04
P99 TPOT (ms):                           63.01
---------------Inter-token Latency----------------
Mean ITL (ms):                           59.45
Median ITL (ms):                         52.75
P99 ITL (ms):                            131.46
==================================================

关键指标的解释

Median Time to First Token (TTFT)：从发送请求到生成第一个输出令牌的典型时间。
Median Time Per Output Token (TPOT)：生成第一个令牌后生成每个令牌所需的典型时间。
Median Inter-Token Latency (ITL)：一个输出令牌（或输出令牌）完成响应与下一个令牌完成响应之间的典型时间延迟。
Output token throughput：系统生成输出（已生成）令牌的速率。
Total Token Throughput：系统处理输入（提示）令牌和输出（已生成）令牌的总速率。

平衡吞吐量和延迟¶

在 LLM 推理中，“吞吐量”可以定义为每秒生成的令牌数（上面的 Output token throughput 指标）或每秒处理的令牌数（上面的 Total Token Throughput 指标）。这两个吞吐量指标高度相关。在比较不同的并行配置时，我们通常将吞吐量除以使用的 GPU 数量以获得“每 GPU 吞吐量”。每 GPU 吞吐量越高，服务相同数量的传入请求所需的 GPU 越少。

另一方面，“延迟”可以定义为从发送请求到生成第一个输出令牌的延迟（TTFT 指标），在生成第一个令牌后两个生成令牌之间的延迟（TPOT 指标），或者从发送请求到生成最终令牌的端到端延迟（E2EL 指标）。当输入（提示）序列长度远长于输出（生成）序列长度时，TTFT 对 E2EL 的影响更大，而在相反的情况下，TPOT 对 E2EL 的影响更大。

为了实现更高的吞吐量，来自多个请求的令牌必须批量处理，但这会增加延迟。因此，必须根据部署要求在吞吐量和延迟之间进行平衡。

Nemotron Nano 3 的两个主要可调配置是 --tensor-parallel-size (TP) 和 --max-num-seqs (BS)。它们如何影响吞吐量和延迟总结如下：

在相同的 BS 下，较高的 TP 通常会导致较低的延迟，但吞吐量也较低。
在相同的 TP 大小下，较高的 BS 通常会导致较高的吞吐量，但延迟较差，但最大 BS 受加载权重后可用 GPU 内存（用于 kv-cache）的限制。
因此，增加 TP（在相同 BS 下会降低吞吐量）可能允许运行更高的 BS（会增加吞吐量），净吞吐量增益/损失取决于模型和配置。

请注意，上述陈述假设客户端的并发设置（例如性能基准测试命令中的 --max-concurrency 标志）与服务器端的 --max-num-seqs (BS) 设置匹配。