环境变量¶

本文档列出了支持的诊断和性能分析以及性能调优选项。

诊断和性能分析参数¶

参数名称	描述	默认值
`VLLM_PROFILER_ENABLED`	启用高级性能分析器。您可以在 perfetto.habana.ai 上查看生成的 JSON 跟踪。	`false`
`VLLM_HPU_LOG_STEP_GRAPH_COMPILATION`	仅在发生编译时，记录每个 vLLM 引擎步骤的图编译。我们建议将其与 `PT_HPU_METRICS_GC_DETAILS=1` 一起使用。	`false`
`VLLM_HPU_LOG_STEP_GRAPH_COMPILATION_ALL`	记录每个 vLLM 引擎步骤的图编译，即使没有发生编译。	`false`
`VLLM_HPU_LOG_STEP_CPU_FALLBACKS`	仅在发生回退时，记录每个 vLLM 引擎步骤的 CPU 回退。	`false`
`VLLM_HPU_LOG_STEP_CPU_FALLBACKS_ALL`	记录每个 vLLM 引擎步骤的 CPU 回退，即使没有发生回退。	`false`
`VLLM_T_COMPILE_FULLGRAPH`	如果在编译过程中发生任何图中断，则强制 PyTorch 编译函数引发错误。这有助于轻松检测现有的图中断，这些中断通常会降低性能。	`false`
`VLLM_T_COMPILE_DYNAMIC_SHAPES`	强制 PyTorch 编译禁用动态选项的图，仅在需要时使用动态形状。	`false`
`VLLM_FULL_WARMUP`	强制 PyTorch 假设预热阶段完全涵盖所有可能的张量大小，从而防止进一步的编译。如果在预热后发生编译，PyTorch 将崩溃（并显示此消息：`Recompilation triggered with skip_guard_eval_unsafe stance. This usually means that you have not warmed up your model with enough inputs such that you can guarantee no more recompilations.`），并且必须禁用。	`false`

性能调优参数¶

参数名称	描述	默认值
`VLLM_GRAPH_RESERVED_MEM`	专用于 HPUGraph 捕获的内存百分比。	`0.1`
`VLLM_EXPONENTIAL_BUCKETING`	启用指数分桶间距，而非线性分桶间距。	`true`
`VLLM_BUCKETING_FROM_FILE`	启用从文件读取分桶配置	`None`

开发者模式参数¶

要进入开发者模式，请使用 VLLM_DEVELOPER_MODE

参数名称	描述	默认值
`VLLM_SKIP_WARMUP`	跳过预热阶段。	`false`

附加参数¶

参数名称	描述	默认值
`VLLM_HANDLE_TOPK_DUPLICATES`	处理 top-k 之外的重复项。	`false`
`VLLM_CONFIG_HIDDEN_LAYERS`	设置每个 HPUGraph 要运行的隐藏层数量，用于在隐藏层之间分割模型，当 TP 为 1 时。它通过减少某些模型中跨 token 的延迟限制来提高吞吐量。	`1`

影响 vLLM 执行的 HPU PyTorch 桥接环境变量

参数名称	描述	默认值
`PT_HPU_LAZY_MODE`	设置 Gaudi 的后端，其中 `0` 表示 PyTorch Eager，`1` 表示 PyTorch Lazy。	`0`
`PT_HPU_ENABLE_LAZY_COLLECTIVES`	对于使用 HPU Graphs 的张量并行推理，必须将其设置为 `true`。	`true`
`PT_HPUGRAPH_DISABLE_TENSOR_CACHE`	对于 LLaVA、Qwen 和 RoBERTa 模型，必须将其设置为 `false`。	`false`
`VLLM_PROMPT_USE_FLEX_ATTENTION`	仅为 Llama 模型启用，允许使用 `torch.nn.attention.flex_attention` 而不是 FusedSDPA。需要 `VLLM_PROMPT_USE_FUSEDSDPA=0`。	`false`
`RUNTIME_SCALE_PATCHING`	启用运行时比例缩放补丁功能，该功能仅适用于 FP8 执行，对于 BF16 被忽略。	`true` (Torch 编译模式)，`false` (Lazy 模式)

线性分桶策略的附加性能调优参数¶

VLLM_{phase}_{dim}_BUCKET_{param} 是一组环境变量，用于配置线性分桶机制的范围，其中：

{phase} 是 PROMPT 或 DECODE
{dim} 是 BS、SEQ 或 BLOCK
{param} 是 MIN、STEP 或 MAX

下表列出了可用变量及其默认值

阶段	变量名	默认值
Prompt	批大小最小值 (`VLLM_PROMPT_BS_BUCKET_MIN`)	`1`
Prompt	批大小步长 (`VLLM_PROMPT_BS_BUCKET_STEP`)	`1`
Prompt	批大小最大值 (`VLLM_PROMPT_BS_BUCKET_MAX`)	`max_num_prefill_seqs`
Prompt	查询长度最小值 (`VLLM_PROMPT_SEQ_BUCKET_MIN`)	`块大小`
Prompt	查询长度步长 (`VLLM_PROMPT_SEQ_BUCKET_STEP`)	`块大小`
Prompt	查询长度最大值 (`VLLM_PROMPT_SEQ_BUCKET_MAX`)	`max_num_batched_tokens`
Prompt	序列上下文最小值 (`VLLM_PROMPT_CTX_BUCKET_MIN`)	`0`
Prompt	序列上下文步长 (`VLLM_PROMPT_CTX_BUCKET_STEP`)	`1`
Prompt	序列上下文最大值 (`VLLM_PROMPT_CTX_BUCKET_MAX`)	`(max_model_len - block_size) // block_size`
Decode	批大小最小值 (`VLLM_DECODE_BS_BUCKET_MIN`)	`1`
Decode	批大小步长 (`VLLM_DECODE_BS_BUCKET_STEP`)	`32`
Decode	批大小最大值 (`VLLM_DECODE_BS_BUCKET_MAX`)	`max_num_seqs`
Decode	块大小最小值 (`VLLM_DECODE_BLOCK_BUCKET_MIN`)	`1`
Decode	块大小步长 (`VLLM_DECODE_BLOCK_BUCKET_STEP`)	`块大小`
Decode	块大小最大值 (`VLLM_DECODE_BLOCK_BUCKET_MAX`)	`max_model_len * max_num_seqs // block_size` 默认或 `max_blocks` 如果 `VLLM_CONTIGUOUS_PA = True`

当部署的工作负载不使用模型的全部上下文时，我们建议您根据服务 vLLM 服务器后将生成的预期输入和输出 token 长度，提前限制最大值。例如，假设您想部署具有 131072 (我们的 max_model_len) 的 text generation 模型 Qwen2.5-1.5B，并且您的工作负载模式将不会使用全部上下文长度（您期望的最大输入 token 大小为 1K，并预测生成最多 2K token 作为输出）。在这种情况下，为整个上下文长度准备 vLLM 服务器是不必要的，您可以提前限制这些值。这可以减少启动时间和预热时间。此情况的推荐设置是：

--max_model_len: 3072，这是输入和输出序列的总和 (1+2)*1024。
VLLM_PROMPT_SEQ_BUCKET_MAX: 1024，这是您期望处理的最大输入 token 大小。

注意

如果模型配置指定了较高的 max_model_len，请根据实际需求将其设置为 input_tokens 和 output_tokens 的总和，并向上舍入为 block_size 的倍数。