模型加载与配置

1、--model

说明

要使用的模型名称或模型权重文件在本地的存放路径，如不选择本地路径默认会去huggingface拉取

默认值

facebook/opt-125m

参数选项

模型库加载：facebook/opt-125m
本地加载：/models/DeepSeek-R1/

使用场景

选择运行的模型是从本地加载还是从互联网的模型库加载

2、--task

说明

task 参数可以让模型更偏向于某一方面的任务执行，帮助模型理解希望它专注于某种类型的操作。通过指定不同的任务，模型会在执行时调整其处理方式，以适应特定类型的需求。

默认值

auto

参数选项

  • auto

    • 使用场景：当不确定要执行什么任务，可以让模型自动选择最合适的任务时。
    • 例子：只是想让模型理解并响应你的输入，模型会根据输入自动决定任务。

  • generate

    • 使用场景：需要生成文本内容，如创作文章、编写代码、生成故事等。
    • 例子：写一篇关于人工智能的文章，生成一个Python代码段，编写一个关于未来科技的短篇小说。

  • embedding

    • 使用场景：文本嵌入生成，用于信息检索、相似度搜索或聚类分析。
    • 例子：将一篇文章转换为向量表示，以便于之后在大数据中进行相似度搜索，或者在推荐系统中使用。

  • embed

    • 使用场景：将文本转换为可供机器学习模型进一步处理的嵌入表示。
    • 例子：将用户的评论转换为嵌入向量，用于训练情感分析模型。

  • classify

    • 使用场景：文本分类，常用于情感分析、垃圾邮件检测、产品推荐等。
    • 例子：分析一段评论，判断它是正面的还是负面的；将邮件分类为“垃圾邮件”或“非垃圾邮件”。

  • score

    • 使用场景：为文本内容打分，通常用于质量评分、评估任务等。
    • 例子：对某篇文章的质量进行评分，或者根据某些标准给一段文本评分（如流畅度、逻辑性等）。

  • reward

    • 使用场景：在强化学习或某些任务中给模型的输出打分或奖励。
    • 例子：评估一个模型生成的答案，并根据正确性、创造性等因素给予奖励。

  • transcription

    • 使用场景：将语音或音频文件转换为文本。
    • 例子：将会议录音转换为文字记录，或者将视频中的对白转写成文本。

使用场景

比如做一个情感分析任务，classify 任务就非常适合；如果你需要基于某些文本生成新的内容，generate 任务则是更好的选择。

3、--tokenizer

说明

指定要使用的分词器的名称或路径。

默认值

null

参数选项

本地就选路径：/models/DeepSeek-R1/
云端就选模型库的名称：unsloth/DeepSeek-R1-BF16 默认走huggingface

使用场景

分词器是处理文本的工具，将文本分割成更小的单位（称为 tokens），并将这些 tokens 转换为模型能够理解的数值形式。可自定义分词器或者用模型自带分词器。

4、--skip-tokenizer-init

说明

跳过分词器（tokenizer）和解码器（detokenizer）的初始化过程。

默认值

null

参数选项

null

使用场景

比如已经明确知道分词器已经被正确加载，或者希望手动管理分词器的初始化时，可用此参数

5、--revision

说明

用于指定模型权重的具体版本。可以是一个分支名（branch name）、标签名（tag name）或提交 ID（commit id）

默认值

默认拉取默认版本，类似docker 中pull的过程，不给tag 就pull tag为latest的image

参数选项

分支名(branch name)
标签名(tag name)
提交 ID(commit id)

使用场景

加载特定的分支、标签或提交版本。
回退到旧版本以解决问题。
进行多版本测试或对比实验。

6、--code-revision

说明

用于指定模型代码的版本，可以是一个分支名（branch name）、标签名（tag name）或提交 ID（commit id）

默认值

默认拉取默认版本，类似docker 中pull的过程，不给tag 就pull tag为latest的image

参数选项

分支名(branch name)
标签名(tag name)
提交 ID(commit id)

使用场景

加载特定的分支、标签或提交版本的模型代码。
回退到旧版本的模型代码以解决问题。
进行多版本测试或对比实验。

7、--tokenizer-revision

说明

用于指定分词器（tokenizer）的具体版本。可以是一个分支名（branch name）、标签名（tag name）或提交 ID（commit id）。

默认值

默认拉取默认版本，类似docker 中pull的过程，不给tag 就pull tag为latest的image

参数选项

分支名(branch name)
标签名(tag name)
提交 ID(commit id)

使用场景

加载特定的分支、标签或提交版本的分词器。
回退到旧版本的分词器以解决问题。
进行多版本测试或对比实验。

8、--tokenizer-mode

说明

用于指定分词器的工作模式。

默认值

auto

参数选项

auto自动选择分词器模式。

  • 系统会优先尝试使用快速分词器（fast tokenizer），如果快速分词器不可用，则回退到慢速分词器（slow tokenizer）通常auto是最佳实现。
  • 快速分词器通常基于 Rust 或其他高性能语言实现，性能更高。

优点:

  • 简单易用，无需手动配置。
  • 性能最优（在快速分词器可用的情况下）。

缺点:

  • 如果快速分词器不可用，会回退到慢速分词器，性能下降。

slow始终使用慢速分词器。

慢速分词器通常基于 Python 实现，性能较低，但支持更多的自定义功能,适用于需要对分词逻辑进行深度定制的场景。

优点:

  • 灵活性高，易于修改和调试。

缺点:

  • 性能较差，不适合大规模推理或生产环境。

mistral始终使用 mistral_common 分词器

专门为 Mistral 模型设计的分词器，针对 Mistral 模型的特点进行了优化,包括特定的词汇表、分词规则等方面的调整。

优点:

  • 针对特定模型优化，性能和兼容性更好。

缺点:

  • 仅适用于 Mistral 模型，通用性较低。

custom使用预注册的自定义分词器。

用户可以通过 --tokenizer 参数指定一个预注册的分词器名称或路径,适用于需要完全控制分词逻辑的场景,比如：处理领域特定语言或非标准文本。

优点:
完全可控，适合高度定制化的需求。

缺点:
需要额外开发或配置，增加了复杂性。

使用场景

  1. 默认选择
    如果没有特殊需求，可以直接使用 auto 模式，让系统选择最佳实现。
  2. 调试和开发
    在开发或调试阶段，可以使用 slow 模式来检查分词器的行为是否符合预期。
  3. 特定模型优化
    如果使用的是 Mistral 模型，建议使用 mistral 模式以获得最佳性能。
  4. 自定义需求
    如果需要特殊的分词规则（如处理领域特定语言或非标准文本），可以使用 custom 模式，并提供自定义分词器。

11、--download-dir

说明

指定模型权重的下载和加载目录。如果不指定此参数，默认会使用 Hugging Face 的默认缓存目录。

默认值

huggingface默认下载路径：/root/.cache/huggingface/modules/

参数选项

下载模型至/models/目录：

vllm server --download-dir="/models/"

使用场景

默认缓存目录所在的磁盘空间不足或想自定义下载模型的路径,可以使用此参数将模型权重下载到其他磁盘或分区。

12、--load-format

说明

用于指定模型权重的加载格式。有多种选项，每种选项对应不同的权重存储和加载方式。

默认值

如果未指定 --load-format，默认值为 auto,在 auto 模式下，系统会优先尝试加载 safetensors 格式的权重文件。如果 safetensors 不可用，则回退到 PyTorch 的 .bin 格式。

参数选项

auto

自动选择权重加载格式,系统会优先尝试加载 safetensors 格式的权重文件，如果 safetensors 格式不可用，则回退到 PyTorch 的 .bin 格式。

优点:

  • 简单易用，无需手动配置。
  • 性能较优（在 safetensors 可用的情况下）。

缺点:

  • 如果 safetensors 不可用，可能会回退到较慢的 .bin 格式。

pt

直接加载标准的 PyTorch 权重文件,加载 PyTorch 的 .bin 格式权重文件,

优点:
兼容性强，适用于大多数 PyTorch 模型。

缺点:
加载速度可能较慢，且安全性较低（容易受到恶意修改）。

safetensors

加载 safetensors 格式的权重文件,使用 safetensors 格式加载权重，该格式具有更高的安全性和更快的加载速度。

优点:

  • 更快的加载速度。
  • 更高的安全性（防止恶意修改）。

缺点:

  • 需要确保权重文件已转换为 safetensors 格式。

npcache

加载 PyTorch 格式的权重，并生成一个 NumPy 缓存以加速后续加载,在首次加载时，将权重文件转换为 NumPy 格式并缓存,后续加载时直接使用缓存文件，从而加快加载速度.需要频繁加载同一模型权重时使用。

优点:
显著提升重复加载的速度。

缺点:
首次加载时需要额外的时间生成缓存。

dummy

不加载实际的权重文件，而是随机初始化权重,测试模型推理性能或调试代码时使用。,主要用于性能分析（profiling）。

优点:
无需下载或加载真实的权重文件。

缺点:
无法用于实际推理任务。

tensorizer

使用 CoreWeave 的 Tensorizer 工具加载权重,Tensorizer 是一种优化工具，旨在加速模型权重的加载和推理,使用 CoreWeave 平台或需要高性能加载时使用。

优点:
加载速度极快，适合大规模部署。

缺点:
需要额外的工具支持。

sharded_state

加载分片存储的权重文件,权重文件被分割成多个小文件（分片），分别加载,适用于模型权重过大，无法一次性加载到内存时使用。

优点:
支持超大模型的加载。

缺点:
需要额外的分片管理。

gguf

加载 GGUF 格式的权重文件,GGUF 是一种专门为小型设备优化的权重格式,在资源受限的设备上运行模型时使用。

优点:
占用空间小，适合嵌入式设备。

缺点:
兼容性有限。

bitsandbytes

使用 bitsandbytes 进行量化加载,将权重文件量化为低精度格式（如 4-bit 或 8-bit），以减少内存占用,在 GPU 内存有限的情况下运行大模型时使用。

优点:
显著降低内存占用。

缺点:
可能会导致精度损失。

mistral

加载 Mistral 模型专用的权重格式,针对 Mistral 模型进行了优化,使用 Mistral 模型时推荐使用此格式。

优点:
针对特定模型优化，性能更好。

缺点:
仅适用于 Mistral 模型。

runai_streamer

使用 Run:ai Model Streamer 加载 safetensors 格式的权重,通过 Run:ai 的流式加载技术优化权重加载,使用 Run:ai 平台时推荐使用此格式.

优点:
加载速度更快，适合分布式环境。

缺点:
需要依赖 Run:ai 平台。

使用场景

  1. 默认选择
    直接使用 auto 模式，让系统选择最佳实现。
  2. 高性能加载
    需要快速加载权重，可以使用 safetensors 或 tensorizer。
  3. 资源受限环境
    在 GPU 内存有限的情况下运行模型，可以使用 bitsandbytes和gguf进行量化加载。
  4. 分布式环境
    在分布式环境中运行模型，可以使用 runai_streamer 或 sharded_state。
  5. 测试和调试
    需要测试模型性能或调试代码，可以使用 dummy。

13、--config-format

说明

用于指定模型配置文件的加载格式。

默认值

ConfigFormat.AUTO

参数选项

--config-format auto

自动选择配置文件的加载格式,系统会优先尝试加载 Hugging Face 格式的配置文件,如果 Hugging Face 格式的配置文件不可用，则尝试加载 Mistral 格式的配置文件,适用与不确定配置文件的格式，或者希望系统为你选择最佳实现，可以使用 auto。

优点:
简单易用，无需手动配置。

缺点:
如果配置文件格式不明确，可能会导致加载失败或加载错误的格式。

--config-format hf

加载 Hugging Face 格式的配置文件,直接加载标准的 Hugging Face 配置文件（通常是 config.json 文件）,配置文件明确为 Hugging Face 格式时使用。

优点:
兼容性强，适用于大多数 Hugging Face 模型。

缺点:
不适用于非 Hugging Face 格式的配置文件。

--config-format mistral

加载 Mistral 格式的配置文件,加载专门为 Mistral 模型设计的配置文件,使用 Mistral 模型时推荐使用此格式。

优点:
针对特定模型优化，性能更好。

缺点:
仅适用于 Mistral 模型，通用性较低。

使用场景

  1. 自动选择最佳实现（auto）
  2. 加载 Hugging Face 格式的配置文件（hf）。
  3. 加载 Mistral 格式的配置文件（mistral）。

14、--hf-overrides

说明

用于向 Hugging Face 模型的配置（config）中传递额外的自定义参数。
Hugging Face 的模型配置文件（如 config.json）包含了许多预定义的参数（如 hidden_size, num_attention_heads 等）,通过 --hf-overrides 参数，可以动态地修改或扩展这些配置，而无需直接修改原始的 config.json 文件。
参数值是一个 JSON 字符串，会被解析为一个字典（dictionary），并应用于模型的配置。
通过 --hf-overrides,可以覆盖模型配置中的某些参数。例如，可以修改 num_attention_heads 或 hidden_size，以适应特定任务的需求。

默认值

默认情况下不会覆盖或扩展模型的配置。

参数选项

# 覆盖模型配置中的 num_attention_heads 和 hidden_size
vllm serve \
--hf-overrides='{"num_attention_heads":16,"hidden_size":1024}'

num_attention_heads 被设置为 16。
hidden_size 被设置为 1024。

使用场景

  1. 动态调整模型配置。
  2. 启用实验性功能。
  3. 调试和验证。

15、--model-loader-extra-config

说明

用于向模型加载器传递额外的配置信息。通过合理设置该参数，可以优化模型加载行为，例如调整显存分配、启用量化支持或定制加载格式。适用于不同硬件资源和负载场景下的性能优化需求。

  1. 模型加载器的作用 ：

    1. 模型加载器负责将模型权重从存储介质（如磁盘或远程服务器）加载到内存或 GPU 显存中，并根据指定的格式（load_format）进行初始化。

  2. 自定义配置 ：

    1. --model-loader-extra-config 允许用户通过 JSON 格式的字符串传递额外的配置参数，这些参数会被解析为字典并传递给模型加载器。具体支持的配置项取决于所选的 load_format 和模型加载器的实现。

默认值

默认值：无（不传递额外配置）默认情况下，模型加载器会使用其默认配置加载模型。如果需要自定义加载行为，则可以通过该参数传递额外的配置。

参数选项

--model-loader-extra-config 是一个字符串类型的参数，必须是有效的 JSON 格式。常见的配置选项包括：

  • 显存优化 ：
    调整显存分配策略，例如设置分块加载（chunked loading）或显存预分配比例。

--model-loader-extra-config='{"chunk_size": 512}'

  • 加载格式 ：
    针对不同的 load_format（如 torch, safetensors, bitsandbytes 等），传递特定的加载选项。

--model-loader-extra-config='{"fast_load": true}'

  • 量化配置 ：
    如果启用了量化（quantization），可以通过该参数传递量化相关的配置，例如量化精度（8-bit 或 4-bit）。

--model-loader-extra-config='{"quantization": "4bit"}'

  • 其他高级功能 ：
    启用或禁用某些高级功能，例如懒加载（lazy loading）、缓存优化等
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --model-loader-extra-config '{"chunk_size": 512}' \
    --gpu-memory-utilization 0.8 \
    --port 8000

--model-loader-extra-config '{"chunk_size": 512}' :传递额外的配置信息，启用分块加载并将每个分块的大小设置为 512 MB。

使用场景

  1. 显存优化:在显存资源有限的情况下，可以通过传递额外的配置来优化显存分配。
  2. 量化支持:如果启用了量化（quantization），可以通过该参数传递量化相关的配置。例如，设置量化精度为 4-bit。
  3. 加载格式定制：针对不同的 load_format，可以通过该参数传递特定的加载选项。例如，针对 safetensors 格式启用快速加载模式。

16、--ignore-patterns

说明

用于指定在加载模型时需要忽略的文件或目录模式。通过合理设置该参数，可以避免重复加载、忽略临时文件或优化加载性能。适用于不同模型和硬件资源下的加载优化需求。

  1. 避免重复加载 ：

    1. 在加载大型语言模型时，某些文件或目录可能会被重复加载（例如 LLaMA 模型的检查点文件）。通过设置 --ignore-patterns，可以指定需要忽略的文件或目录模式，从而避免不必要的加载操作。

  2. 优化加载过程 ：

    1. 忽略不必要的文件或目录可以减少加载时间、显存占用和磁盘 I/O 开销，从而提高模型加载效率。

默认值

默认值：[] 在默认情况下，模型加载器不会忽略任何文件或目录。如果需要忽略某些模式，则可以通过该参数显式设置。

参数选项

  1. --ignore-patterns 是一个字符串类型的参数，支持以下格式：
  • 单个模式 ：
    直接指定一个模式，例如 "original/*/"。
  • 多个模式 ：
    使用逗号分隔多个模式，例如 "original/*/, checkpoints/*.bak"。
  1. 常见的模式包括：
  • 通配符 ：
    *：匹配任意字符（不包括路径分隔符 /）。

**：匹配任意路径（包括子目录）。

  • 具体路径 ：
    例如 "checkpoints/old_model/" 或 "logs/.txt"。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --ignore-patterns "original/**/*, *.tmp, *.bak" \
    --gpu-memory-utilization 0.8 \
    --port 8000

--ignore-patterns "original/**/, .tmp, *.bak" : 忽略 original/*/ 文件（避免重复加载 LLaMA 的检查点文件），并忽略所有 .tmp 和 .bak 文件。

使用场景

  1. 避免重复加载:在加载 LLaMA 等模型时，某些检查点文件可能会被重复加载。通过设置 --ignore-patterns="original/*/"，可以避免加载这些冗余文件。
  2. 忽略临时文件:如果模型目录中包含临时文件（如 .tmp 或 .bak 文件），可以通过设置忽略模式来跳过这些文件。
  3. 优化加载性能:在显存或磁盘资源有限的情况下，可以通过忽略不必要的文件或目录来减少加载时间和资源占用。

17、--qlora-adapter-name-or-path

说明

用于指定 QLoRA 适配器的名称或路径。通过加载 QLoRA 适配器，可以在显著减少显存占用的同时实现高效微调，适用于资源受限或特定领域任务优化的场景。
QLoRA 是一种高效的微调技术，结合了量化（quantization）和低秩适配（Low-Rank Adaptation, LoRA），能够在显著减少模型参数量的同时保持较高的性能。

  1. QLoRA 的作用 ：
  • QLoRA 通过在预训练模型的基础上添加少量的低秩矩阵（low-rank matrices）来实现高效微调，同时对这些矩阵进行量化以进一步降低显存占用。
    --qlora-adapter-name-or-path 指定了 QLoRA 适配器的位置，可以是一个本地路径或远程存储的名称。

默认值

默认值：无（需显式设置） 在默认情况下，vLLM 不会加载任何 QLoRA 适配器。如果需要使用 QLoRA 微调的模型，则必须显式设置该参数。

参数选项

--qlora-adapter-name-or-path 是一个字符串类型的参数，支持以下两种格式：

  • 本地路径 ：
    指定 QLoRA 适配器的本地存储路径，例如 /path/to/qlora_adapter。
  • 远程名称 ：
    指定 QLoRA 适配器的远程存储名称（如 Hugging Face Hub 上的模型 ID），例如 user/qlora-adapter-for-llama2。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --qlora-adapter-name-or-path user/qlora-adapter-for-llama2 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--qlora-adapter-name-or-path user/qlora-adapter-for-llama2:加载存储在 Hugging Face Hub 上的 QLoRA 适配器，其名称为 user/qlora-adapter-for-llama2。

使用场景

  1. 高效微调:在需要对大型语言模型进行微调的场景中（如特定领域的任务优化），可以通过加载 QLoRA 适配器实现高效微调，而无需重新训练整个模型。
  2. 资源受限场景:在显存或计算资源有限的情况下，QLoRA 适配器可以显著减少显存占用，从而支持更大的模型或更高的并发请求。
  3. 多任务适配:如果需要为不同的任务加载不同的 QLoRA 适配器，可以通过该参数动态切换适配器。

分布式执行相关

1、--distributed-executor-backend

说明

用于指定分布式模型推理的执行后端。

默认值

如果 pipeline_parallel_size × tensor_parallel_size 的乘积小于或等于本机可用 GPU 的数量，则使用 mp
如果上述乘积大于本机可用 GPU 的数量，并且安装了 Ray，则默认使用 ray；否则会报错
对于 TPU，仅支持 ray

参数选项

ray

使用 Ray 框架作为分布式执行后端,Ray 是一个分布式计算框架，支持跨主机的分布式任务调度

优点:
支持跨主机的分布式推理。
动态资源管理能力强。

缺点:
需要安装 Ray，增加了依赖。

mp

使用Python 的 multiprocessing 模块作为分布式执行后端,是一种基于单机多进程的实现方式，适合在单台机器上运行的任务

优点:
简单易用，无需额外依赖。

缺点:
不支持跨主机的分布式推理。

uni

使用单机模式运行推理任务,所有推理任务都在单个进程中完成，不涉及分布式计算。

优点:
简单直接，适合小规模任务。

缺点:
不适合大规模模型或高并发任务。

external_launcher

使用外部启动器管理分布式推理任务,外部启动器负责启动和管理分布式推理任务，通常与其他工具或框架集成(如 Kubernetes、Slurm)

优点:
灵活性强，适合复杂的集群环境。

缺点:
配置复杂，需要额外的工具支持。

使用场景

  1. 单机多 GPU
    任务只需要在单台机器上运行，并且 GPU 数量足够，可以直接使用 mp。
  2. 多机多 GPU
    任务需要跨多台机器运行（如超大规模模型推理），可以使用 ray。
  3. TPU 推理
    在 TPU 上运行推理任务，必须使用 ray。
  4. 小规模任务
    任务规模较小，或者不需要分布式推理，可以使用 uni。
  5. 复杂集群环境
    需要与特定的集群管理系统集成，可以使用 external_launcher。

2、--pipeline-parallel-size, -pp

说明

控制流水线并行的阶段数，将模型的不同层划分到多个设备上执行，以加速大规模模型的训练。

默认值

默认值为 1 ，表示不启用流水线并行，模型在单个设备上运行。

参数选项

1 - n

使用场景

适用于大规模模型、多设备环境或长序列模型的训练场景，尤其是当单个设备无法容纳整个模型时。

3、--tensor-parallel-size, -tp

说明

控制张量并行的副本数，将模型中的张量分割成多个部分，并分配到多个设备上进行计算，以加速大规模模型的训练。

默认值

默认值为 1 ，表示不启用张量并行，整个张量在单个设备上运行。

参数选项

1 - n

使用场景

适用于超大规模模型、高计算需求或长序列模型的训练场景，尤其是当单个设备无法容纳整个张量时。

4、--max-parallel-loading-workers

说明

用于控制模型加载时的并行工作线程数。主要目的是在使用 张量并行(Tensor Parallelism)和加载大模型时,避免因内存不足(RAM OOM,Out of Memory)而导致的问题

默认值

如果未指定 --max-parallel-loading-workers，系统通常会根据硬件配置和模型大小自动选择一个合理的值
在某些框架中，默认值可能是所有可用 GPU 的数量，但这可能会导致内存不足的问题。

参数选项

示例 1：限制并行加载的工作线程数

假设有一个 4-GPU 系统，并且需要加载一个大模型。为了避免主机内存不足，可以将并行加载的工作线程数限制为 2：

--max-parallel-loading-workers=2

模型的分片会被分成两批加载，第一批加载完成后，再加载第二批。

示例 2：动态调整

如果发现主机内存仍然不足，可以进一步降低并行加载的工作线程数。例如：

--max-parallel-loading-workers=1

模型的分片会按顺序逐一加载，最大限度地减少内存占用。

使用场景

  1. 大模型加载
    模型非常大（如超过 10B 参数），并且主机内存有限，可以通过此参数限制并行加载的工作线程数，避免内存不足。
  2. 张量并行
    使用张量并行时，模型权重会被分片到多个 GPU 上。如果同时加载所有分片，可能会导致主机内存占用过高。

通过设置 --max-parallel-loading-workers，可以将加载过程分成多个批次，逐步完成。

  1. 多 GPU 环境
    多 GPU 环境中，尤其是 GPU 数量较多时，主机内存可能成为瓶颈。通过限制并行加载的工作线程数，可以缓解这一问题。

5、--ray-workers-use-nsight

说明

用于指定是否使用 Nsight 工具对 Ray 工作线程(workers)进行性能分析(profiling).如果启用此参数,Ray 工作线程的运行将被 Nsight 监控和分析
Nsight 是 NVIDIA 提供的一套强大的性能分析工具,主要用于 GPU 应用程序的调试和优化,通过 --ray-workers-use-nsight 参数，可以将 Nsight 集成到 Ray 工作线程中，从而对分布式推理任务的性能进行深入分析。
此参数仅适用于 Ray 后端

默认值

默认不会启用 Nsight 性能分析。

参数选项

--ray-workers-use-nsight

使用场景

  1. 性能调优
    需要对 Ray 工作线程的 GPU 性能进行分析，可以启用此参数。

例如，在分布式推理任务中，如果发现某些 GPU 的利用率较低或存在性能瓶颈，可以通过 Nsight 进行详细分析。

  1. 调试 GPU 内核
    如果怀疑 Ray 工作线程中的 GPU 内核存在问题（如性能低下或内存泄漏），可以使用 Nsight 进行调试。
  2. 优化资源利用率
    在多机多 GPU 环境中，合理分配 GPU 资源是提高性能的关键。通过 Nsight 分析，可以更好地了解资源使用情况，并进行优化。

6、--disable-custom-all-reduce

说明

用于控制是否禁用自定义的 All-Reduce 操作。All-Reduce 是分布式深度学习中的一种通信原语，用于在多个设备（如 GPU）之间同步梯度或其他数据。

  • 启用该参数（设置为 True） ：禁用自定义的 All-Reduce 实现，转而使用框架默认的 All-Reduce 实现（例如 PyTorch 或 NCCL 提供的标准实现）。
  • 禁用该参数（设置为 False，默认行为） ：使用 vLLM 自定义优化的 All-Reduce 实现，可能针对特定硬件或场景进行了性能优化。

默认值

默认情况下该参数是 未启用 的，即使用 vLLM 自定义的 All-Reduce 实现。

参数选项

#True：禁用自定义 All-Reduce，使用框架默认实现。
vllm serve \
  --disable-custom-all-reduce
#False：启用自定义 All-Reduce，使用 vLLM 优化的实现。
vllm serve \
  /model/DeepSeek-R1

使用场景

  1. 调试和兼容性测试
    分布式训练中遇到与 All-Reduce 相关的问题（例如性能瓶颈、通信错误等），可以通过启用 --disable-custom-all-reduce 来切换到框架默认的 All-Reduce 实现，从而快速判断问题是否与 vLLM 的自定义实现有关。
  2. 硬件或环境限制
    在某些硬件或网络环境中，vLLM 的自定义 All-Reduce 可能无法充分发挥性能优势，甚至可能导致兼容性问题。此时可以禁用自定义实现，改用更通用的默认实现。
  3. 性能对比
    用户可以通过启用或禁用该参数，对比自定义 All-Reduce 和框架默认实现的性能差异，从而选择更适合当前任务的配置。
  4. 简化部署
    在某些情况下，用户可能希望减少对自定义实现的依赖，以降低部署复杂度。启用该参数可以避免引入额外的优化逻辑。

推理与生成设置

1、--max-model-len

说明

定义模型能够处理的最大上下文长度（token 数量），影响模型的计算复杂度和内存占用。

默认值

如果未指定，系统会根据模型配置文件自动推导出一个默认值（如 2048 或其他模型特定值）。
模型配置文件一般是模型库中config.json的max_position_embeddings的值来决定的

参数选项

null

使用场景

适用于长序列任务、资源受限环境或需要自定义上下文长度的任务场景。

2、--block-size

说明

用于指定 Token 块的大小(即连续 Token 的块大小).决定了模型在处理输入序列时如何将 Token 分组为块。参数支持4种选择分别是：8, 16, 32, 64, 128

  • 控制 Token 块的大小 ：

    • 输入序列通常会被分割成多个块（blocks），每个块包含固定数量的 Token。
    • 较小的块大小（如 8 或 16）适合短序列或低延迟任务。
    • 较大的块大小（如 64 或 128）适合长序列或高吞吐量任务。

  • 优化性能 ：

    • 不同的硬件平台对块大小的支持不同，合理选择块大小可以提高性能。
      例如，在 CUDA 设备上，块大小不能超过 32，否则可能会导致不兼容问题。

  • 设备特定的限制 ：

    • Neuron、CUDA 和 HPU 设备对块大小有不同的默认值和支持范围，需要根据目标设备进行调整。

  • 设备相关的行为 ：

    • Neuron 设备 ：
      在 Neuron 设备上，--block-size 参数会被忽略，并自动设置为 --max-model-len（模型的最大上下文长度）。
    • CUDA 设备 ：
      在 CUDA 设备上，仅支持块大小不超过 32 的值。如果指定更大的值（如 64 或 128），可能会导致错误或被限制为 32。
    • HPU 设备 ：
      在 HPU 设备上，默认的块大小为 128。

默认值

如果未指定 --block-size，系统会根据设备类型自动选择默认值：
Neuron 设备 ：设置为 --max-model-len。
CUDA 设备 ：最大值为 32。
HPU 设备 ：默认值为 128。

参数选项

vllm serve \
  --block-size=32 \
  --distributed-executor-backend=ray

--block-size=32 指定 Token 块的大小为 32
--distributed-executor-backend=ray 指定使用 Ray 作为分布式执行后端。

使用场景

  1. 短序列任务（较小的块大小）。
  2. 长序列任务（较大的块大小）。
  3. 硬件优化（根据设备特性选择合适的块大小）。

3、--enable-prefix-caching, --no-enable-prefix-caching

说明

一对互斥参数,用于控制是否启用 自动前缀缓存(Prefix Caching) 功能.Prefix Caching(前缀缓存)是一种优化技术,用于加速生成任务(如文本生成、对话生成等),通过缓存输入序列的公共前缀部分的计算结果(如 Key 和 Value 张量),避免重复计算,从而提高推理效率

  • --enable-prefix-caching:启用前缀缓存
  • --no-enable-prefix-caching:禁用前缀缓存

默认值

--enable-prefix-caching

参数选项

vllm serve \
--enable-prefix-caching
--no-enable-prefix-caching

使用场景

  1. 批量生成任务
    任务涉及批量生成（如同时生成多条文本），并且输入序列具有相同的前缀（如共享的上下文或提示），启用前缀缓存可以显著提高效率。
  2. 对话系统
    在对话生成任务中，多个用户的输入可能共享相同的上下文（如历史对话）。启用前缀缓存可以避免重复计算共享部分的 Key 和 Value 张量。
  3. 资源受限环境
    硬件资源有限（如内存不足），可以禁用前缀缓存以减少内存占用，尽管这可能会降低生成速度。
  4. 调试和实验
    在调试或实验阶段，可以通过启用或禁用前缀缓存来观察其对性能和资源使用的影响。

4、--disable-sliding-window

说明

用于禁用 滑动窗口（Sliding Window） 功能

  1. 控制滑动窗口的行为 ：

    • 滑动窗口（Sliding Window） 是一种技术，用于处理长序列时限制注意力机制的计算范围。
    • 在 Transformer 模型中，滑动窗口通过限制 Key 和 Value 的计算范围，减少内存占用和计算复杂度。
    • 启用 --disable-sliding-window 后，滑动窗口功能将被禁用，模型会使用完整的上下文长度进行计算。

  2. 优化性能与资源使用 ：

    • 禁用滑动窗口可能会导致更高的计算开销和内存占用，但可以保留完整的上下文信息。
    • 如果任务需要处理非常长的序列，并且硬件资源充足，可以禁用滑动窗口以获得更好的生成质量。

默认值

如果未明确指定，默认情况下滑动窗口功能是启用的。

参数选项

# 启用滑动窗口（默认行为）
vllm serve

# 禁用滑动窗口
vllm serve \
  --disable-sliding-window

使用场景

  1. 长序列任务
    任务涉及处理长序列（如长文档生成或复杂对话系统），并且希望保留完整的上下文信息，可以禁用滑动窗口。
  2. 资源受限环境
    硬件资源有限（如 GPU 内存不足），建议保留滑动窗口以减少内存占用和计算复杂度。
  3. 调试和实验
    在调试或实验阶段，可以通过启用或禁用滑动窗口来观察其对性能和生成质量的影响。

5、--num-lookahead-slots

说明

是一个实验性参数,主要用于 推测解码（Speculative Decoding） 的调度配置

  1. 控制推测解码的行为 ：
    推测解码通过提前预测模型可能的输出（即“前瞻”），减少实际需要计算的 Token 数量，从而加速生成过程。

--num-lookahead-slots 参数决定了在调度过程中预留的前瞻槽位数量，这些槽位用于存储推测的 Token。

  1. 优化性能 ：
    增加前瞻槽位的数量可能会提高推测解码的效率，但也会增加内存占用和调度复杂度。

设置为 0 时，表示不使用额外的前瞻槽位，推测解码的功能可能会受到限制。

  1. 过渡性配置 ：
    该参数是一个临时解决方案，未来会被更正式的推测解码配置取代。

在现阶段，它主要用于测试和验证推测解码的正确性。

默认值

默认值为 0，表示不启用额外的前瞻槽位。

参数选项

# 启用 4 个前瞻槽位
vllm serve \
  --num-lookahead-slots=4

使用场景

  1. 测试和验证推测解码的正确性。
  2. 研究推测解码的性能优化。

6、--max-num-batched-tokens

说明

用于设置每次迭代中可以处理的最大批量 Token 数量（Maximum Number of Batched Tokens）。

  1. 控制批处理规模 ：
    批处理（batching）是深度学习推理和训练中的关键技术，通过将多个输入序列组合在一起处理，可以提高计算效率。

--max-num-batched-tokens 参数限制了每个批次中 Token 的总数，从而间接控制了批处理的规模。

  1. 优化性能与资源使用 ：
    增加最大批量 Token 数量可以提高吞吐量，但可能会增加 GPU 内存占用。

减少最大批量 Token 数量可以降低内存需求，但可能会降低吞吐量。

  1. 防止内存溢出 ：
    在 GPU 内存有限的情况下，合理设置此参数可以避免因批量过大而导致的内存不足问题。
  2. 批量处理（Batching）机制
    在深度学习推理中，为了提高计算效率，通常会将多个用户的请求合并成一个批次（batch）进行处理。

--max-num-batched-tokens 的作用是限制 每个批次中所有请求的 Token 总数

假设 --max-num-batched-tokens=8192：
如果有 4 个用户的请求，分别包含 2048、2048、2048 和 2048 个 Token，则它们可以被合并为一个批次，因为总 Token 数为 8192。
如果第 5 个用户的请求包含 1024 个 Token，则该请求会被延迟到下一个批次，因为当前批次的 Token 总数已经达到了上限。

默认值

如果未明确指定，默认值通常由框架根据硬件资源和模型配置自动确定。

参数选项

# 设置最大批量 Token 数量为 4096
vllm serve \
  --max-num-batched-tokens=4096

使用场景

  1. 大规模批量推理。
  2. 资源受限环境。
  3. 调试和优化。

7、--max-num-seqs

说明

用于设置每次推理迭代中可以处理的最大序列数量（Maximum Number of Sequences）

  1. 控制批处理规模 ：
    批处理（batching）是深度学习推理和训练中的关键技术，通过将多个输入序列组合在一起处理，可以提高计算效率。

--max-num-seqs 参数限制了每个批次中可以包含的最大序列数量，从而间接控制了批处理的规模。

  1. 优化性能与资源使用 ：
    增加最大序列数量可以提高吞吐量，但可能会增加 GPU 内存占用。

减少最大序列数量可以降低内存需求，但可能会降低吞吐量。

  1. 防止内存溢出 ：
    在 GPU 内存有限的情况下，合理设置此参数可以避免因批量过大而导致的内存不足问题。

--max-num-seqs 是一个限制每次推理迭代中可以处理的最大序列数量的参数，类似于游乐园的过山车：

  • 过山车的载人上限 ：--max-num-seqs 决定了每次推理迭代中可以处理的最大请求数量（即最大序列数量）。
  • 批处理的过程 ：每次推理迭代相当于一次过山车启动，系统会将当前排队的请求（人）合并成一个批次进行处理。
  • 延迟至下一批处理 ：如果当前排队的请求数量超过了 --max-num-seqs 的限制，超出的请求会被延迟到下一次推理迭代。

与传统并发不同的是：

  • --max-num-seqs 并不是直接控制系统的并发能力，而是通过限制批处理规模间接影响并发,决定了每次推理能容纳多少请求。

默认值

如果未明确指定，默认值通常由框架根据硬件资源和模型配置自动确定。

参数选项

# 设置最大序列数量为 32
vllm serve \
  --max-num-seqs=32

--max-num-seqs=32 表示每次迭代中最多可以处理 32 个输入序列

使用场景

  1. 大规模批量推理。
  2. 资源受限环境。
  3. 调试和优化。

8、--max-logprobs

说明

用于设置在生成文本时返回的最大 log probabilities（对数概率）数量。

  • 控制返回的 log probabilities 数量 ：
    每次生成时，模型会根据输入序列和采样策略生成多个候选 token。

--max-logprobs 决定了最多返回多少个 token 的 log probabilities。

  • 优化资源使用 ：
    返回更多的 log probabilities 会增加计算开销和内存占用。

如果任务不需要详细的概率信息，可以通过减少此值来优化性能。

  • 支持下游任务 ：
    在某些任务中（如置信度分析、后处理优化），需要获取生成 token 的概率分布。

通过设置 --max-logprobs，可以灵活地满足这些需求。

默认值

默认值为 20，表示最多返回 20 个 token 的 log probabilities。

参数选项

# 设置最大 log probabilities 数量为 30
vllm serve \
--max-logprobs=30

使用场景

  1. 概率分析（如置信度分析、后处理优化）。
  2. 资源受限环境。
  3. 调试和验证。

9、--logits-processor-pattern

说明

用于指定一个正则表达式模式,以限制哪些 logits processors(logits 处理器)可以通过 logits_processors 参数传递给模型.
Logits Processor 是一种机制,用于在模型生成过程中动态调整 logits(未归一化的概率分布)
例如,可以通过 logits 处理器实现温度调节、top-k 采样、top-p 采样等.

默认值

默认值为 None,表示不允许任何 logits 处理器

参数选项

示例：允许所有 Hugging Face 官方处理器

--logits-processor-pattern="^transformers\..*"

匹配所有以 transformers. 开头的处理器名称。

使用场景

  1. 限制 logits 处理器的使用
    在某些场景中，可能希望限制用户只能使用特定的 logits 处理器，以避免潜在的安全风险或不兼容问题。

例如，可以只允许使用 Hugging Face 官方提供的 logits 处理器，而不允许自定义或第三方处理器。

  1. 支持灵活的命名规则
    通过正则表达式，可以灵活地定义允许的 logits 处理器的命名规则。

例如：

- 允许所有以 transformers. 开头的处理器。
- 允许特定的处理器名称（如 transformers.TemperatureLogitsProcessor）。
  1. 提高安全性
    在多用户环境中，限制 logits 处理器的使用可以防止恶意用户注入不安全的代码或逻辑。

10、--speculative-disable-mqa-scorer

说明

布尔型参数，用于控制推测解码中是否禁用 MQA Scorer。默认值为 False，即启用 MQA Scorer。在遇到兼容性问题、调试需求或资源受限场景时，可以通过设置为 True 禁用 MQA Scorer 并回退到 Batch Expansion 方法。合理使用该参数可以在性能和稳定性之间取得最佳平衡。
MQA Scorer 是一种高效的注意力机制实现方式，用于加速主模型对草稿模型生成的候选 token 序列的验证过程。

默认值

默认值：False 在默认情况下，vLLM 会在推测解码中启用 MQA Scorer 来加速验证过程。

参数选项

vllm serve \
    --model meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --speculative-disable-mqa-scorer True \
    --gpu-memory-utilization 0.8 \
    --port 8000

--speculative-disable-mqa-scorer True :禁用 MQA Scorer，回退到 Batch Expansion 方法进行验证。

使用场景

  1. 解决兼容性问题:在某些硬件或框架环境中，MQA Scorer 可能存在兼容性问题（如不支持特定的 GPU 架构或深度学习框架版本）。此时可以通过设置 --speculative-disable-mqa-scorer=True 禁用 MQA Scorer，确保服务正常运行。
  2. 调试与验证:如果怀疑 MQA Scorer 的实现存在问题（如输出质量异常或性能瓶颈），可以临时禁用 MQA Scorer，使用 Batch Expansion 方法进行对比测试，以确认问题来源。
  3. 资源受限场景:在某些资源受限的场景中（如低显存 GPU 或小规模部署），Batch Expansion 方法可能比 MQA Scorer 更适合，因为它对硬件的要求较低。
  4. 实验与调优:在模型部署初期，可以通过对比启用和禁用 MQA Scorer 的效果，找到最佳的推理配置。

11、--speculative-draft-tensor-parallel-size, -spec-draft-tp

说明

用于控制草稿模型在推测解码中的张量并行度。默认值为 1，即不启用张量并行。在多 GPU 环境中，可以通过增加该参数的值来充分利用硬件资源，从而加速草稿模型的推理过程。合理设置该参数可以在性能和资源利用率之间取得最佳平衡。
张量并行（Tensor Parallelism） 是一种分布式推理技术，通过将模型的权重和计算分布到多个 GPU 上，从而加速推理过程,该参数定义了草稿模型在推测解码中使用的张量并行副本数量。增加张量并行度可以更高效地利用多 GPU 环境，但需要确保硬件资源足够支持。

默认值

默认值：1 在默认情况下，草稿模型不会使用张量并行，而是运行在单个 GPU 上。

参数选项

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --speculative-draft-tensor-parallel-size 2 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--speculative-draft-tensor-parallel-size 2 :设置草稿模型的张量并行度为 2，即将其计算分布到 2 块 GPU 上。

使用场景

  1. 多 GPU 环境:拥有多个 GPU 的高性能计算环境中，可以通过增加张量并行度来充分利用硬件资源，从而加速草稿模型的推理过程。
  2. 大模型部署:如果草稿模型的规模较大（如数十亿参数），单个 GPU 可能无法容纳整个模型。此时可以通过张量并行将模型分布到多个 GPU 上。
  3. 性能优化:在需要进一步提升推理速度的场景中，可以通过调整张量并行度来优化草稿模型的计算效率。
  4. 实验与调优:在模型部署初期，可以通过对比不同张量并行度的效果，找到最佳的硬件资源配置。

12、--speculative-max-model-len

说明

用于定义草稿模型支持的最大序列长度。合理设置该参数可以在硬件资源有限的情况下优化性能，同时避免因输入序列过长而导致的问题。对于超长输入序列，可以通过跳过推测解码来保证服务的稳定性。

  1. 限制草稿模型的输入长度 ：

草稿模型通常是一个较小的模型，其设计可能无法处理过长的输入序列。通过设置该参数，可以限制草稿模型支持的最大序列长度。

  1. 跳过推测解码 ：

如果输入序列的长度超过了 --speculative-max-model-len 的值，则推测解码（Speculative Decoding）将被跳过，直接由主模型完成推理。

默认值

默认值：无（由草稿模型的最大上下文长度决定）

参数选项

--speculative-max-model-len 是一个整数类型的参数，理论上可以设置为任意正整数。实际使用中，常见的选项包括：

  • 小值（如 512、1024） ：适用于草稿模型规模较小、硬件资源有限的场景。
  • 中值（如 2048、4096） ：适用于草稿模型规模适中、硬件资源充足的场景。
  • 大值（如 8192+） ：适用于草稿模型规模较大、硬件资源非常充足的场景。

需要注意的是，设置的值不能超过草稿模型的最大上下文长度。

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --speculative-max-model-len 1024 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--speculative-max-model-len 1024 :设置草稿模型支持的最大序列长度为 1024 tokens。对于超过 1024 tokens 的输入序列，跳过推测解码,直接由主模型完成推理。

使用场景

  1. 限制草稿模型的输入长度:在草稿模型规模较小的情况下，可以通过设置该参数限制输入序列的长度，避免因超出草稿模型的能力范围而导致性能下降或错误。
  2. 跳过长序列的推测解码:对于超长输入序列（如超过 4096 tokens），推测解码可能会显著增加计算负担。此时可以通过设置该参数跳过推测解码，直接由主模型完成推理。
  3. 优化硬件资源利用率:在硬件资源有限的情况下，可以通过限制草稿模型的最大序列长度，减少显存占用和计算开销。
  4. 实验与调优:在模型部署初期，可以通过调整该参数进行性能测试，找到推理速度和输出质量的最佳平衡点。

13、--speculative-disable-by-batch-size

说明

用于动态控制推测解码的启用条件。合理设置该参数可以在高并发场景下防止性能下降，同时确保服务的稳定性。对于负载波动较大的场景，可以通过动态调整该参数来优化性能。

  1. 动态禁用推测解码 ：
    当新请求的队列长度（即当前排队等待处理的请求数量）超过该参数设置的值时，推测解码将被禁用。此时，所有新请求将直接由主模型完成推理，而不再使用草稿模型进行推测解码。
  2. 防止性能下降 ：
    推测解码虽然可以加速推理过程，但在高并发场景下可能会增加计算负担，导致整体性能下降。通过设置该参数，可以在高负载情况下动态禁用推测解码，从而避免性能瓶颈。

默认值

默认值：无（推测解码始终启用，除非显式设置该参数）

参数选项

--speculative-disable-by-batch-size 是一个整数类型的参数，理论上可以设置为任意正整数。实际使用中，常见的选项包括：

  • 小值（如 5、10） ：适用于对并发请求敏感、硬件资源有限的场景。
  • 中值（如 20、50） ：适用于平衡性能和并发能力的场景。
  • 大值（如 100+） ：适用于高并发、高性能硬件环境的场景。
    需要注意的是，设置的值应根据硬件性能和实际负载情况进行调整。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --speculative-disable-by-batch-size 15 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--speculative-disable-by-batch-size 15 :设置当请求队列长度超过 15 时，禁用推测解码。

使用场景

  1. 高并发场景:在高并发请求的情况下，推测解码可能会导致计算资源不足，从而降低整体性能。通过设置该参数，可以在请求队列长度超过一定阈值时禁用推测解码，确保服务稳定性。
  2. 资源受限场景:在硬件资源有限的情况下，可以通过设置较小的值来限制推测解码的启用范围，从而节省显存和计算资源。
  3. 动态性能优化:在负载波动较大的场景中，可以通过动态调整该参数来优化性能。例如，在低负载时启用推测解码以加速推理，在高负载时禁用推测解码以保证稳定性。
  4. 实验与调优:在模型部署初期，可以通过对比不同值的效果，找到最佳的并发请求阈值。

14、--spec-decoding-acceptance-method

说明

用于指定推测解码中草稿 token 的验证方法。默认值为 rejection_sampler，即使用固定的验证方法。如果需要更高的推理速度，可以选择 typical_acceptance_sampler 方法，并通过调整接受率来平衡性能和质量。合理设置该参数可以在不同场景下优化推理效率和输出质量。

  1. 草稿模型验证 ：
    在推测解码中，草稿模型生成的候选 token 序列需要由主模型进行验证，以决定是否接受这些 token。

  2. --spec-decoding-acceptance-method 提供了两种验证方法的选择：

    • rejection_sampler ：一种固定的验证方法，不允许调整草稿 token 的接受率。这种方法保证了较高的输出质量，但会降低推理速度。
    • typical_acceptance_sampler ：一种可配置的验证方法，允许通过调整接受率来平衡推理速度和输出质量。较高的接受率可以加速推理，但会降低输出质量。

默认值

默认值：rejection_sampler vLLM 使用 rejection_sampler 方法进行草稿 token 的验证。

参数选项

--spec-decoding-acceptance-method 是一个字符串类型的参数，支持以下两种选项：

  • rejection_sampler ：
    固定的验证方法，不允许调整草稿 token 的接受率。

特点：输出质量较高，但推理速度可能较慢。

  • typical_acceptance_sampler ：
    可配置的验证方法，允许通过调整接受率来平衡推理速度和输出质量。

特点：可以通过提高接受率加速推理，但可能会降低输出质量。

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --spec-decoding-acceptance-method typical_acceptance_sampler \
    --gpu-memory-utilization 0.8 \
    --port 8000

--spec-decoding-acceptance-method typical_acceptance_sampler :设置验证方法为 typical_acceptance_sampler，允许通过调整接受率来平衡推理速度和输出质量。

使用场景

  1. 高质量输出场景:在对输出质量要求较高的场景中（如内容创作、专业翻译等），可以选择 rejection_sampler 方法，确保草稿 token 的验证过程严格且高质量。
  2. 高性能推理场景:在需要快速生成文本的场景中（如在线聊天机器人、实时翻译等），可以选择 typical_acceptance_sampler 方法，并通过调整接受率来提高推理速度。
  3. 实验与调优:在模型部署初期，可以通过对比两种验证方法的效果，找到推理速度和输出质量的最佳平衡点。

15、--disable-logprobs-during-spec-decoding

说明

用于控制推测解码过程中是否返回 token 的对数概率。默认值为 True，即禁用对数概率的计算。通过合理设置该参数，可以在推理速度和功能需求之间取得最佳平衡，适用于不同场景下的性能优化需求。

  1. 对数概率的作用 ：

    1. 在语言模型推理中，token 的对数概率（log probabilities）通常用于计算生成文本的置信度、实现采样策略（如 Top-K 或 Top-P 采样），或者用于下游任务（如重排序或后处理）。

  2. 性能优化 ：

    1. 如果不需要对数概率，可以通过禁用其计算来减少推测解码过程中的延迟。禁用后，草稿模型和主模型在生成候选 token 和验证 token 时将跳过对数概率的计算。

默认值

默认值：True 在默认情况下，推测解码过程中不会返回 token 的对数概率。

参数选项

--disable-logprobs-during-spec-decoding 是一个布尔型参数，支持以下两种选项：

  • True ：禁用对数概率的计算和返回，从而减少推测解码的延迟。
  • False ：启用对数概率的计算和返回，按照 SamplingParams 中的设置返回对数概率。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --disable-logprobs-during-spec-decoding True \
    --gpu-memory-utilization 0.8 \
    --port 8000

--disable-logprobs-during-spec-decoding True :禁用对数概率的计算和返回，从而减少推测解码的延迟。

使用场景

  1. 高性能推理场景:在需要快速生成文本的场景中（如在线聊天机器人、实时翻译等），如果下游任务不需要对数概率，可以通过设置 --disable-logprobs-during-spec-decoding=True 禁用对数概率的计算，从而显著降低延迟。
  2. 需要对数概率的场景:在某些高级应用场景中（如重排序、置信度评估等），如果需要对数概率来进行进一步处理，可以通过设置 --disable-logprobs-during-spec-decoding=False 启用对数概率的计算。
  3. 实验与调优:在模型部署初期，可以通过对比启用和禁用对数概率的效果，找到推理速度和功能需求的最佳平衡点。

内存与资源管理

1、--swap-space

说明

定义每个 GPU 可以使用的 CPU 交换空间大小（GiB），用于在显存不足时扩展可用资源。

默认值

默认值为 4 ，每个 GPU 最多可以使用 4 GiB 的 CPU 内存作为交换空间。

参数选项

4 - n

使用场景

适用于显存不足、大模型推理/训练、多任务并行或低成本硬件等场景。

2、--cpu-offload-gb

说明

用于指定每个 GPU 可以将多少 GiB 的模型权重卸载（offload）到 CPU 内存中。

  1. 扩展 GPU 内存 ：
    假设你有一个 24 GB 的 GPU，并将 --cpu-offload-gb 设置为 10，那么虚拟上可以认为你的 GPU 内存增加到了 34 GB。

这使得你可以加载更大规模的模型（如 BF16 权重的 13B 模型，需要至少 26 GB 的 GPU 内存）。

  1. 优化资源利用率 ：
    在 GPU 内存有限的情况下，CPU 卸载可以充分利用 CPU 内存资源，避免因 GPU 内存不足而导致任务失败。
  2. 动态加载机制 ：
    每次模型前向传播时，系统会从 CPU 内存中动态加载所需的权重到 GPU 内存中。这种方式虽然增加了计算开销，但可以显著减少 GPU 内存需求。

默认值

如果未明确指定，默认值为 0，表示不启用 CPU 卸载功能。

参数选项

# 将 10 GiB 的模型权重卸载到 CPU 内存
vllm serve \
  --cpu-offload-gb=10

使用场景

  1. GPU 内存不足但 CPU 内存充足。
  2. 加载超大规模模型。
  3. 资源受限环境。

3、--gpu-memory-utilization

说明

控制当前 vLLM 实例可以使用的 GPU 显存比例，范围为 0 到 1。

默认值

默认值为 0.9 ，实例最多可以使用 90% 的 GPU 显存。

参数选项

0 - 1

使用场景

适用于多实例共享 GPU、显存资源管理或动态调整显存利用率的场景。

4、--num-gpu-blocks-override

说明

用于显式指定 GPU 的块数量(number of GPU blocks),并忽略 GPU 性能分析(profiling)的结果

  1. 覆盖性能分析结果 ：
    默认情况下，系统会通过性能分析确定 GPU 的块数量，以优化内存使用和计算效率。

使用 --num-gpu-blocks-override 参数可以忽略性能分析结果，并手动指定块数量。

  1. 支持测试场景 ：
    在测试抢占（preemption）或其他异常情况时，可以通过此参数模拟不同的块数量配置。
  2. 灵活性 ：
    此参数为开发者提供了更大的控制权，允许在特定场景下调整 GPU 块数量。

默认值

如果未明确指定，默认会根据 GPU 性能分析结果自动确定块数量。

参数选项

# 强制指定 GPU 的块数量为 100
vllm serve \
  --num-gpu-blocks-override=100

使用场景

  1. 测试抢占或其他异常情况。
  2. 调试和验证性能。
  3. 特殊硬件环境。

5、--kv-cache-dtype

说明

  1. 控制 KV Cache 的存储精度 ：

    • 在 Transformer 模型中，KV Cache 用于存储注意力机制中的 Key 和 Value 张量，以加速推理过程。
    • 通过 --kv-cache-dtype 参数，可以显式指定 KV Cache 的存储数据类型，从而在性能和内存占用之间进行权衡。

  2. 优化推理性能 ：

    • 使用低精度格式（如 FP8）可以显著减少内存占用，并加速计算，尤其是在支持 FP8 的硬件上（如 NVIDIA GPU 或 AMD GPU）。

  3. 支持混合精度 ：

    • 某些硬件平台（如 CUDA 11.8+ 和 ROCm）支持 FP8 格式，允许在保持较高推理速度的同时降低内存需求。

默认值

auto

参数选项

auto

自动选择 KV Cache 的数据类型,系统会根据模型的数据类型（--dtype 参数）自动选择合适的 KV Cache 数据类型,适用于不确定最佳的 KV Cache 数据类型时系统自动选择最佳实现
例如，如果模型使用 FP16，则 KV Cache 也会使用 FP16。

优点:
简单易用，无需手动配置。

缺点:
自动选择可能不总是符合特定需求（如需要更低精度时）。

fp8

使用 FP8 格式存储 KV Cache,FP8 是一种低精度格式,占用 8 位（1 字节），相比 FP16 和 FP32 显著减少了内存占用,默认情况下，fp8 等价于 fp8_e4m3,适用于硬件支持fp8时可使用

优点:
显著减少内存占用和计算时间。

缺点:
需要硬件支持（如 NVIDIA Ampere 架构或 AMD GPU）。

fp8_e5m2

使用 FP8_E5M2 格式存储 KV Cache,FP8_E5M2 是一种 FP8 变体，具有更大的数值范围(5位指数,2位尾数),适用于数值范围要求较高的场景

优点:
提供更大的数值范围。

缺点:
相比 fp8_e4m3，数值精度较低。

fp8_e4m3

使用 FP8_E4M3 格式存储 KV Cache,FP8_E4M3 是一种 FP8 变体,具有更高的数值精度(4位指数,3位尾数),适用于数值精度要求较高的场景

优点:
提供更高的数值精度。

缺点:
数值范围较小。

使用场景

  • 自动选择最佳实现(auto)
  • 高性能推理(fp8、fp8_e5m2、fp8_e4m3)
  • 平衡精度和范围(fp8_e5m2、fp8_e4m3)
  • 硬件兼容性(FP8 支持的硬件)

6、--kv-transfer-config

说明

用于配置分布式 KV 缓存传输的行为。通过合理设置该参数，可以在网络带宽、传输延迟和计算开销之间取得最佳平衡，适用于分布式推理场景下的性能优化需求。
KV 缓存是 Transformer 模型推理过程中的关键组件，用于存储键值对（Key-Value Pairs），从而加速自注意力机制的计算。

  • 分布式 KV 缓存的作用 ：
    在分布式推理场景中，KV 缓存可能需要在多个设备（如 GPU 或节点）之间传输。通过 --kv-transfer-config，可以自定义传输策略以优化性能或适配特定硬件环境。
  • JSON 格式 ：
    该参数接受一个 JSON 字符串，解析后会作为字典传递给分布式 KV 缓存传输的配置接口。

默认值

默认值：无（需显式设置） 在默认情况下，分布式 KV 缓存传输会使用其默认配置。如果需要自定义传输行为，则必须显式设置该参数。

参数选项

--kv-transfer-config 是一个字符串类型的参数，必须是有效的 JSON 格式。常见的配置选项包括：

  • transfer_mode ：
    指定传输模式。常见的模式包括：

"sync"：同步传输，确保数据在传输完成后才继续执行后续操作。
"async"：异步传输，允许数据在后台传输的同时继续执行其他任务。
示例：{"transfer_mode": "async"}

  • compression ：
    是否启用压缩以减少传输数据量。设置为 true 时会对 KV 缓存进行压缩。

示例：{"compression": true}

  • batch_size ：
    指定每次传输的批量大小，以控制传输粒度。

示例：{"batch_size": 16}

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --kv-transfer-config '{"transfer_mode": "async", "compression": true}' \
    --gpu-memory-utilization 0.8 \
    --port 8000

--kv-transfer-config '{"transfer_mode": "async", "compression": true}' :覆盖分布式 KV 缓存传输的默认配置，启用异步传输模式并启用压缩功能。

使用场景

  1. 分布式推理：在多 GPU 或多节点的分布式推理场景中，可以通过优化 KV 缓存传输策略来提高整体性能。
  2. 网络带宽受限：如果网络带宽有限，可以通过启用压缩（compression=true）来减少传输数据量。
  3. 低延迟需求：在需要快速响应的场景中，可以选择异步传输模式（transfer_mode="async"）以减少等待时间。

量化与精度控制

1、--quantization, -q

说明

用于指定模型权重的量化方法。量化是一种通过降低权重精度来减少模型大小和计算开销的技术，同时尽量保持模型性能。
该参数允许用户选择一种量化方法（如 awq, gptq, bitsandbytes 等），以优化模型的推理性能。
如果未指定量化方法（即值为 None），系统会尝试从模型配置文件中读取 quantization_config 属性。如果该属性也不存在，则假设模型权重未被量化，并根据 --dtype 参数确定权重的数据类型。

支持多种量化方法：

  • 通用量化方法 ：awq, gptq, bitsandbytes, fp8, hqq 等。
  • 硬件特定方法 ：tpu_int8, neuron_quant, ipex 等。
  • 混合精度量化 ：deepspeedfp, compressed-tensors 等。
  • 无量化 ：None。

除以上的方法外还支持：aqlm, fbgemm_fp8, modelopt, marlin, gguf, gptq_marlin_24, gptq_marlin, awq_marlin,bitsandbytes, qqq, experts_int8, quark, moe_wna16

默认值

默认值为 None

参数选项

# 使用 AWQ 量化方法
vllm serve \
  --quantization=awq

# 使用 GPTQ 量化方法
vllm serve \
  --quantization=gptq

# 不使用量化
vllm serve \
  --quantization=None

使用场景

  1. GPU 推理（如 awq, gptq, fp8）。
  2. TPU 推理（如 tpu_int8, neuron_quant）。
  3. 无需量化（None）。

2、--dtype

说明

用于指定模型权重和激活值的数据类型（data type）。

默认值

ConfigFormat.AUTO

参数选项

auto

自动选择数据类型,如果模型是 FP32 或 FP16 格式，系统会使用 FP16 精度,如果模型是 BF16 格式，系统会使用 BF16 精度,适用与不确定模型的最佳数据类型，或者希望系统选择最佳实现，可以使用auto.

优点:
简单易用，无需手动配置。

缺点:
自动选择可能不总是符合特定需求（如需要更高精度时）

half / float16

使用 FP16（半精度浮点数）格式,FP16 是一种低精度格式，占用 16 位（2 字节），相比 FP32 减少了内存占用和计算时间,常用于 GPU 加速推理，尤其是支持 Tensor Cores 的硬件（如 NVIDIA Ampere 架构）
推荐用于 AWQ（Activation-aware Weight Quantization）量化,在 GPU 上运行大模型时，优先考虑使用 FP16。

优点:
显著减少内存占用和计算时间

缺点:
数值范围较小，可能导致溢出或下溢问题

bfloat16

使用 BF16（Brain Floating Point 16）格式,BF16 是一种低精度格式，占用 16 位（2 字节），与 FP16 类似，但具有更大的数值范围（与 FP32 相同）,常用于需要平衡精度和范围的场景,在支持 BF16 的硬件（如 Google TPU 或 Intel CPU/GPU）上运行模型时使用。

优点:
在减少内存占用的同时，保留了较大的数值范围

缺点:
需要硬件支持

float / float32

使用 FP32（单精度浮点数）格式,FP32 是一种高精度格式，占用 32 位（4 字节），提供更高的数值精度, 常用于需要高精度的场景（如科学计算或训练）,适用于模型对数值精度要求较高，或者硬件不支持低精度格式时使用。

优点:
提供更高的数值精度。

缺点:
内存占用和计算时间较高。

使用场景

  1. 默认选择
    没有特殊需求，可以直接使用 auto 模式，让系统选择最佳实现。
  2. 高性能推理
    需要在 GPU 上运行大模型，并且硬件支持 FP16，可以使用 half 或 float16。
  3. 平衡精度和范围
    需要在减少内存占用的同时保留较大的数值范围，可以使用 bfloat16。
  4. 高精度任务
    任务对数值精度要求较高（如训练或科学计算），可以使用 float 或 float32。
  5. 量化推理
    使用 AWQ 量化方法，推荐使用 half 或 float16。

3、--lora-dtype

说明

用于指定 LoRA 适配器中权重的数据类型（data type）,数据类型的选择会影响模型的计算精度、内存占用和推理速度。

  • 如果设置为 "auto"，LoRA 适配器将使用与基础模型相同的默认数据类型（如 float16 或 bfloat16）。
  • 如果显式指定数据类型（如 float16 或 bfloat16），LoRA 适配器将强制使用该数据类型，而不依赖基础模型的配置。

默认值

默认情况下，该参数值为 "auto"，即 LoRA 适配器的数据类型与基础模型的数据类型保持一致。

参数选项

# 使用基础模型的默认数据类型（auto）。
vllm serve \
  --model /path/to/model \
  --enable-lora

# 显式设置 LoRA 数据类型为 float16。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --lora-dtype float16

# 显式设置 LoRA 数据类型为 bfloat16。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --lora-dtype bfloat16

使用场景

  1. 自动匹配基础模型:希望 LoRA 适配器的数据类型与基础模型保持一致，可以使用默认值 "auto"。
  2. 优化性能:对计算速度要求较高，可以选择 float16 数据类型。float16 在大多数现代 GPU 上具有更高的计算效率和更低的内存占用。
  3. 提高数值稳定性:任务对数值稳定性要求较高（如涉及梯度较大的训练过程），可以选择 bfloat16 数据类型。bfloat16 提供更高的动态范围，适合某些特定硬件（如 TPU 或 Ampere 架构 GPU）。
  4. 调试和对比性能:用户可以通过调整 --lora-dtype 的值，对比不同数据类型下的模型性能（如准确性、推理速度和内存占用），从而找到最优的配置。

4、--speculative-model-quantization

说明

用于指定 草稿模型（speculative model）的权重量化方法 。
草稿模型的量化 ：

  • 草稿模型通常是一个小型模型，但即使如此，它的推理速度和内存占用仍然可能成为瓶颈。
  • 使用量化技术可以进一步加速草稿模型的推理，并减少其对 GPU 内存的需求。

默认值

如果未指定 --speculative-model-quantization，框架会按照以下顺序确定草稿模型的量化方式：

  1. 检查模型配置文件 ：
  • 查看草稿模型的配置文件中是否有 quantization_config 属性,如果存在，则使用该配置进行量化。
  1. 假设未量化 ：
  • 如果配置文件中没有量化信息，则假设草稿模型的权重未被量化,此时，框架会根据主模型的 dtype 推断草稿模型的权重数据类型（例如 FP16 或 BF16）。

参数选项

--speculative-model-quantization 支持的量化方法及其简要说明：

方法名称描述
aqlm基于自适应量化的方法，适合动态范围较大的权重。
awq一种高效的权重量化方法，适用于 Transformer 模型。
deepspeedfpDeepSpeed 提供的浮点量化方法，优化了精度和性能之间的平衡。
tpu_int8针对 TPU 优化的 INT8 量化方法。
fp8使用 FP8 格式进行量化，适合 NVIDIA Hopper 架构及更高版本的 GPU。
fbgemm_fp8Facebook 的 FBGEMM 库提供的 FP8 量化实现。
modeloptIntel 提供的模型优化工具链中的量化方法。
marlinMarlin 是一种高效的 GPTQ 量化方法，针对 Transformer 模型进行了优化。
ggufGGUF 是一种通用的量化格式，适合多种硬件平台。
gptq_marlin_24GPTQ 和 Marlin 结合的量化方法，支持更高效的推理。
gptq_marlinGPTQ 和 Marlin 的基础结合版本。
awq_marlinAWQ 和 Marlin 的结合版本，进一步优化了量化效果。
gptq基于 GPTQ 的量化方法，适合大语言模型。
compressed-tensors一种通用的张量压缩方法，适用于多种模型架构。
bitsandbytes一种流行的量化库，支持 INT8 和混合精度量化。
qqq一种轻量级量化方法，适合资源受限的环境。
hqqHQQ 是一种高效的量化方法，支持低精度推理。
experts_int8针对 MoE（Mixture of Experts）模型的 INT8 量化方法。
neuron_quantAWS Neuron SDK 提供的量化方法，针对 AWS Inferentia 硬件优化。
ipexIntel Extension for PyTorch 提供的量化优化方法。
quarkQuark 是一种新兴的量化方法，专注于极低精度推理。
moe_wna16针对 MoE 模型的 WNA16 量化方法。
None不使用量化，假设模型权重未被量化，并根据 dtype 推断数据类型。
vllm serve /models02/unsloth-DeepSeek-R1-BF16/ \
    --speculative-model gpt2-small \
    --speculative-model-quantization awq \
    --tensor-parallel-size 8 \
    --pipeline-parallel-size 3 \
    --max-model-len 8192 \
    --swap-space 16

主模型是 DeepSeek-R1。
草稿模型是 gpt2-small，并使用 AWQ 方法对其权重进行量化。

使用场景

  1. 在硬件资源受限的场景:草稿模型虽然比主模型小，但在 GPU 内存或计算能力有限的情况下，仍然可能成为瓶颈，使用量化方法（如 bitsandbytes、awq 或 gptq）将草稿模型的权重从 FP32/FP16 降低到 INT8 或更低精度，减少草稿模型的内存占用和推理延迟。
  2. 高性能推理需求的场景：推测解码需要草稿模型快速生成候选 token，如果草稿模型推理速度较慢，会拖累整体性能，使用高性能量化方法（如 fp8、fbgemm_fp8 或 marlin）加速草稿模型的推理，这些方法通常针对特定硬件（如 NVIDIA Hopper 架构 GPU）进行了优化，提供极高的推理速度。
  3. 跨平台部署的场景：草稿模型需要在不同硬件平台上运行（如 CPU、TPU 或多种 GPU 架构），使用通用的量化格式（如 gguf）或跨平台优化工具（如 modelopt 和 neuron_quant），确保草稿模型可以在多种硬件上高效运行。
  4. 特定模型架构的场景：某些模型架构（如 MoE 模型或多专家模型）对量化有特殊需求，使用专门为这些架构设计的量化方法（如 experts_int8 或 moe_wna16），可以更好地处理模型的稀疏性和复杂性。

高级功能/实验性选项

1、--speculative-model

说明

主要用于加速大语言模型的推理过程。
推测解码是一种优化技术，旨在通过使用一个小而快速的“草稿模型”（draft model）来生成候选 token，然后由主模型验证这些候选 token 的正确性。这样可以减少主模型的计算量，从而提高推理速度。

  • 草稿模型（Draft Model） ：一个小模型，负责快速生成候选 token。
  • 主模型（Main Model） ：大模型，负责验证草稿模型生成的 token 是否合理。

默认值

未设置 --speculative-model 推测解码功能将被禁用,主模型会按照常规方式生成 token，不依赖任何草稿模型。

参数选项

vllm serve /models02/unsloth-DeepSeek-R1-BF16/ \
    --speculative-model gpt2-small \
    --tensor-parallel-size 8 \
    --pipeline-parallel-size 3 \
    --max-model-len 8192 \
    --swap-space 16
  • gpt2-small 会快速生成候选 token。
  • DeepSeek-R1 会验证这些候选 token 的正确性。

如果候选 token 被接受，则直接输出结果；否则，主模型会重新计算。

使用场景

  1. 假设您有一个大型语言模型 DeepSeek-R1，并且希望使用一个小模型 gpt2-small 作为草稿模型来加速推理，

2、--num-speculative-tokens

说明

vLLM 中用于控制推测解码行为的关键参数，其值决定了草稿模型生成的推测 token 数量。默认值为 5，可以根据具体场景调整为不同的值。合理设置该参数可以在推理速度和输出质量之间取得最佳平衡，适用于高性能推理、资源受限、高质量输出等多种场景。

  • 推测解码（Speculative Decoding） 是一种加速推理的技术，通过使用一个小而快速的草稿模型生成候选 token 序列，然后由主模型验证这些候选序列的正确性。这种方法可以在保证输出质量的同时显著提高推理速度。
  • --num-speculative-tokens 决定了草稿模型每次生成的推测 token 数量。这个值越大，草稿模型生成的候选序列越长，可能减少主模型的计算次数，但也会增加草稿模型的负担和潜在的错误率。

默认值

默认值：5 在没有显式设置该参数时，vLLM 会在每次推测解码中从草稿模型中采样 5 个 token。

参数选项

--num-speculative-tokens 是一个整数类型的参数，理论上可以设置为任意正整数。然而，实际使用中需要根据硬件性能、模型大小和应用场景进行合理调整。常见的选项包括：

  • 小值（如 1-5） ：适用于对推理延迟要求较高、硬件资源有限的场景。
  • 中值（如 6-10） ：适用于平衡推理速度和输出质量的场景。
  • 大值（如 11+） ：适用于对推理速度要求极高、硬件资源充足的场景。
vllm serve \
    --model meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--num-speculative-tokens 8 :设置草稿模型每次生成的推测 token 数量为 8。这意味着草稿模型会一次性生成 8 个 token，然后由主模型验证这些 token 的正确性。

使用场景

  1. 高性能推理场景:在需要快速生成文本的场景中（如在线聊天机器人、实时翻译等），可以通过增加 --num-speculative-tokens 的值来减少主模型的计算次数，从而提高推理速度。
  2. 资源受限场景:在硬件资源有限（如 GPU 显存较小）的情况下，可以设置较小的值以减少草稿模型的计算负担，同时确保主模型的验证效率。
  3. 高质量输出场景:在对输出质量要求较高的场景中（如内容创作、专业翻译等），可以设置较小的值以降低草稿模型生成错误候选序列的概率，从而提高主模型的验证准确性。
  4. 实验与调优:在模型部署初期，可以通过调整该参数进行性能调优，找到推理速度与输出质量的最佳平衡点。

3、--ngram-prompt-lookup-max

说明

用于控制推测解码中 提示查找（n-gram Prompt Lookup） 的最大窗口大小。合理设置该参数可以在生成质量和计算开销之间取得最佳平衡，适用于不同硬件资源和负载场景。

  1. n-gram 提示查找 ：
    在推测解码过程中，草稿模型会尝试利用输入序列中的 n-gram 模式（即连续的 n 个 token）来生成候选 token 序列。这种技术可以提高草稿模型生成候选序列的准确性和效率。
  2. 窗口大小限制 ：
    --ngram-prompt-lookup-max 定义了 n-gram 提示查找的最大窗口大小。窗口越大，草稿模型能够利用的上下文信息越多，但计算开销也会随之增加。

默认值

默认值：无（由框架自动决定）vLLM 会根据草稿模型的能力和输入序列的长度自动决定 n-gram 提示查找的最大窗口大小。

参数选项

--ngram-prompt-lookup-max 是一个整数类型的参数，理论上可以设置为任意正整数。实际使用中，常见的选项包括：

  • 小值（如 5、10） ：适用于草稿模型规模较小、硬件资源有限的场景。
  • 中值（如 20、50） ：适用于草稿模型规模适中、硬件资源充足的场景。
  • 大值（如 100+） ：适用于草稿模型规模较大、硬件资源非常充足的场景。
    需要注意的是，设置的值不能超过输入序列的长度。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --ngram-prompt-lookup-max 20 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--ngram-prompt-lookup-max 20 :设置 n-gram 提示查找的最大窗口大小为 20。

使用场景

  1. 优化草稿模型生成质量:在草稿模型生成候选 token 序列时，通过增加 n-gram 提示查找的窗口大小，可以提高生成序列的准确性和连贯性。
  2. 节省计算资源:在硬件资源有限的情况下，可以通过限制 n-gram 提示查找的窗口大小，减少计算开销。
  3. 动态性能调优:在不同负载或输入序列长度下，可以通过调整该参数找到推理速度和输出质量的最佳平衡点。

4、--ngram-prompt-lookup-min

说明

用于控制推测解码中 n-gram 提示查找的最小窗口大小。合理设置该参数可以在生成质量和计算开销之间取得最佳平衡，适用于不同硬件资源和负载场景。

  1. n-gram 提示查找 ：
    在推测解码过程中，草稿模型会尝试利用输入序列中的 n-gram 模式（即连续的 n 个 token）来生成候选 token 序列。这种技术可以提高草稿模型生成候选序列的准确性和效率。
  2. 最小窗口限制 ：
    --ngram-prompt-lookup-min 定义了 n-gram 提示查找的最小窗口大小。窗口越小，草稿模型能够利用的上下文信息越少，但计算开销也会降低。

默认值

默认值：无（由框架自动决定）vLLM 会根据草稿模型的能力和输入序列的长度自动决定 n-gram 提示查找的最大窗口大小。

参数选项

--ngram-prompt-lookup-min 是一个整数类型的参数，理论上可以设置为任意正整数。实际使用中，常见的选项包括：

  • 小值（如 2、3） ：适用于草稿模型规模较小、硬件资源有限的场景。
  • 中值（如 4、5） ：适用于草稿模型规模适中、硬件资源充足的场景。
  • 大值（如 6+） ：适用于草稿模型规模较大、硬件资源非常充足的场景。
    需要注意的是，设置的值不能超过输入序列的长度，并且通常应小于或等于 --ngram-prompt-lookup-max 的值。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --ngram-prompt-lookup-min 3 \
    --ngram-prompt-lookup-max 20 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--ngram-prompt-lookup-min 3 :设置 n-gram 提示查找的最小窗口大小为 3。

使用场景

  1. 优化草稿模型生成质量:在草稿模型生成候选 token 序列时，通过增加 n-gram 提示查找的窗口大小，可以提高生成序列的准确性和连贯性。
  2. 节省计算资源:在硬件资源有限的情况下，可以通过限制 n-gram 提示查找的窗口大小，减少计算开销。
  3. 动态性能调优:在不同负载或输入序列长度下，可以通过调整该参数找到推理速度和输出质量的最佳平衡点。

5、--long-lora-scaling-factors

说明

用于指定多个缩放因子（scaling factors），以支持同时加载和使用多个 LoRA 适配器,LoRA 适配器通常会在训练时使用特定的缩放因子来调整低秩矩阵的权重贡献。如果需要在推理或微调过程中同时加载多个 LoRA 适配器，而这些适配器可能使用了不同的缩放因子，则可以通过该参数指定这些缩放因子,如果未指定该参数，系统将仅允许加载使用基础模型默认缩放因子训练的 LoRA 适配器。

默认值

默认情况下，该参数为空，即仅允许加载使用基础模型默认缩放因子训练的 LoRA 适配器。

参数选项

# 使用基础模型的默认缩放因子（未指定额外缩放因子）。
vllm serve \
  --model /path/to/model \
  --enable-lora

# 指定多个缩放因子（例如 0.5, 1.0, 2.0）。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --long-lora-scaling-factors "0.5,1.0,2.0"

使用场景

  1. 支持多缩放因子的 LoRA 适配器:需要同时加载多个 LoRA 适配器，而这些适配器在训练时使用了不同的缩放因子。通过指定 --long-lora-scaling-factors，可以确保系统能够正确处理这些适配器。
  2. 兼容性扩展:任务涉及多个领域或任务，并且每个领域的 LoRA 适配器使用了不同的缩放因子，可以通过该参数实现兼容性扩展。
  3. 调试和对比性能:可以通过调整 --long-lora-scaling-factors 的值，对比不同缩放因子对模型性能的影响（如准确性、推理速度和内存占用），从而找到最优的配置。
  4. 动态任务切换:如果服务需要动态切换不同的 LoRA 适配器（例如根据用户请求加载特定的适配器），可以通过指定多个缩放因子来支持更多的适配器组合。

6、--enable-lora

说明

用于控制是否启用对 LoRA 适配器的支持。
LoRA 是一种高效的微调方法，通过在预训练模型的基础上引入低秩矩阵来实现参数高效的微调（Parameter-Efficient Fine-Tuning, PEFT）。这种方法能够在保持模型性能的同时，显著减少需要训练的参数量。

如果设置为 True，服务将支持加载和处理 LoRA 适配器，允许用户使用 LoRA 方法对模型进行微调或推理。

如果设置为 False（默认值），服务将不支持 LoRA 适配器，仅使用原始的预训练模型。

默认值

默认情况下，该参数值为 False，即不启用 LoRA 支持。

参数选项

# 不启用 LoRA 支持（默认行为）。
vllm serve \
  --model /path/to/model

# 启用 LoRA 支持。
vllm serve \
  --model /path/to/model \
  --enable-lora

使用场景

  1. 高效微调:在资源受限的环境中，可以通过 LoRA 方法对大型语言模型进行高效微调。相比全量微调，LoRA 能够显著减少训练所需的计算资源和时间。
  2. 推理时加载 LoRA 适配器:已经通过 LoRA 方法对模型进行了微调，并希望在推理时加载特定的 LoRA 适配器，可以启用该参数。
  3. 多任务适配:多任务场景中，可以通过加载不同的 LoRA 适配器来适应不同的下游任务，而无需重新加载整个模型。
  4. 调试和测试:需要验证 LoRA 适配器的效果，或者测试其对推理性能的影响，可以临时启用该参数。

7、--enable-lora-bias

说明

用于控制是否在 LoRA 适配器中启用偏置（bias）,LoRA 是一种高效的微调方法，通过引入低秩矩阵来实现参数高效的微调。偏置是神经网络中的一种可学习参数，通常用于调整激活值的分布。

如果设置为 True，LoRA 适配器会包含偏置参数，允许在微调过程中学习和调整偏置。

如果设置为 False（默认值），LoRA 适配器将不包含偏置参数，仅使用低秩矩阵进行调整。

默认值

默认情况下，该参数值为 False，即不启用 LoRA 适配器中的偏置。

参数选项

# 不启用 LoRA 偏置（默认行为）。
vllm serve \
  --model /path/to/model \
  --enable-lora

# 启用 LoRA 偏置。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --enable-lora-bias

使用场景

  1. 提高模型表达能力:偏置参数可以帮助模型更好地适应特定的数据分布或任务需求。
  2. 调试和对比性能:可以通过启用或禁用偏置，对比不同配置下的模型性能（如准确性、收敛速度等），从而评估偏置对任务的影响。
  3. 特定任务需求:任务对模型的输出分布有较高要求（如分类任务中的类别不平衡问题），可以尝试启用偏置以优化模型表现。

8、--enable-prompt-adapter

说明

与 Prompt Adapter 相关的启动参数，用于控制是否启用对 Prompt Adapter 的支持。Prompt Adapter 是一种轻量级的微调方法，允许通过调整模型的输入提示（prompt）来适配特定任务或领域，而无需修改模型的核心权重。

  • 如果设置为 True，服务将支持加载和处理 Prompt Adapter，允许用户使用该方法对模型进行微调或推理。
  • 如果设置为 False（默认值），服务将不支持 Prompt Adapter，仅使用原始的预训练模型。

默认值

默认情况下，该参数值为 False，即不启用 Prompt Adapter 支持。

参数选项

# 不启用 Prompt Adapter 支持（默认行为）。
vllm serve \
  --model /path/to/model

# 启用 Prompt Adapter 支持。
vllm serve \
  --model /path/to/model \
  --enable-prompt-adapter

使用场景

  1. 高效微调:在资源受限的环境中，可以通过 Prompt Adapter 方法对大型语言模型进行高效微调。相比全量微调，Prompt Adapter 能够显著减少训练所需的计算资源和时间。
  2. 推理时加载 Prompt Adapter:已经通过 Prompt Adapter 方法对模型进行了微调，并希望在推理时加载特定的 Prompt Adapter，可以启用该参数。
  3. 多任务适配:在多任务场景中，可以通过加载不同的 Prompt Adapter 来适应不同的下游任务，而无需重新加载整个模型。
  4. 调试和测试:需要验证 Prompt Adapter 的效果，或者测试其对推理性能的影响，可以临时启用该参数。

9、--fully-sharded-loras

说明

用于控制 LoRA 适配器的张量并行计算模式。

  • 默认行为：在 LoRA 计算中，仅有一半的计算会通过张量并行化进行分片,启用 --fully-sharded-loras 后，所有的 LoRA 层都会被完全分片，并利用张量并行化来加速计算。
  • 在高序列长度、大秩值（rank）或较大的张量并行规模下，完全分片的方式通常能够提供更高的性能。

默认值

默认情况下，该参数未启用（即 False），LoRA 的计算仅部分分片。

参数选项

# 使用默认的部分分片模式。
vllm serve \
  --model /path/to/model \
  --enable-lora

# 启用完全分片模式。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --fully-sharded-loras

使用场景

  1. 高序列长度任务:在处理长序列输入（如长文本生成或长上下文推理）时，默认的部分分片模式无法充分利用硬件资源。启用完全分片模式可以更好地分配计算负载，从而提高性能。
  2. 大秩值（rank）场景:LoRA 的秩值（rank）较大（如通过 --max-lora-rank 设置为较高的值），默认的部分分片模式导致计算瓶颈。启用完全分片模式可以缓解这一问题。
  3. 大规模张量并行:多 GPU 环境中，如果张量并行规模较大（如使用多个 GPU 进行分布式推理），完全分片模式可以更高效地利用硬件资源，减少通信开销。
  4. 调试和对比性能:用户可以通过启用或禁用 --fully-sharded-loras，对比不同配置下的性能表现（如吞吐量、延迟和 GPU 利用率），从而找到最优的配置。

10、--enable-chunked-prefill

说明

与 预填充（Prefill） 阶段相关的启动参数，用于控制是否启用基于 max_num_batched_tokens 的分块（chunked）预填充机制。

  • 在推理过程中，预填充阶段负责处理输入序列的初始计算（如生成注意力权重和隐藏状态）。如果输入序列较长或批量大小较大，可能会导致显存占用过高。
  • 启用该参数后，vLLM 会将预填充请求分块处理，每块的大小由 max_num_batched_tokens 参数限制。这种方式可以有效降低显存峰值，提升系统在高负载场景下的稳定性。
  • 如果未启用该参数，则预填充阶段会一次性处理所有输入序列，可能导致显存不足的问题。

默认值

默认情况下，该参数未启用（即 False），预填充阶段不会分块处理。

参数选项

# 不启用分块预填充（默认行为）。
vllm serve \
  --model /path/to/model

# 启用分块预填充。
vllm serve \
  --model /path/to/model \
  --enable-chunked-prefill

使用场景

  1. 长序列输入:任务涉及长序列输入（如长文档生成或上下文推理），预填充阶段可能会占用大量显存。通过启用分块预填充，可以将长序列分块处理，从而降低显存峰值。
  2. 高并发场景:在高并发场景中，多个请求可能同时进入预填充阶段，导致显存压力过大。通过启用分块预填充，可以减少显存占用，提高系统的吞吐量和稳定性。
  3. 资源受限环境:如果硬件资源有限（如 GPU 显存较小），可以通过启用分块预填充来优化显存使用，避免因显存不足导致的任务失败。
  4. 调试和对比性能:可以通过启用或禁用分块预填充，对比不同配置下的性能表现（如显存占用、延迟和吞吐量），从而找到最优的配置。

11、--multi-step-stream-outputs

说明

多步推理（Multi-Step Inference） 和 流式输出（Streaming Outputs） 相关的启动参数，用于控制在多步推理过程中是否逐步流式输出结果。

  • 如果设置为 True（默认值），vLLM 将在每一步推理完成后立即流式输出结果。这种方式适合需要实时获取部分结果的场景。
  • 如果设置为 False，vLLM 将在所有步骤完成后再一次性输出最终结果。这种方式适合对完整结果有需求且不关心中间状态的场景。

默认值

默认情况下，该参数值为 True，即在多步推理过程中逐步流式输出结果。

参数选项

# 使用默认值（逐步流式输出结果）。
vllm serve \
  --model /path/to/model

# 禁用逐步流式输出，仅在所有步骤完成后输出最终结果。
vllm serve \
  --model /path/to/model \
  --multi-step-stream-outputs False

使用场景

  1. 实时流式输出:需要实时获取推理结果的场景中（如在线聊天机器人或语音转文字系统），可以启用逐步流式输出（True），以便用户能够尽快看到部分结果。
  2. 批量处理:在需要完整结果的场景中（如离线批量推理任务或生成长文本的任务），可以禁用逐步流式输出（False），以减少中间结果的传输开销，并确保最终结果的完整性。
  3. 调试和对比性能:用户可以通过调整 --multi-step-stream-outputs 的值，对比不同配置下的性能表现（如延迟、吞吐量和用户体验），从而找到最优的配置。

Tokenizer配置

1、--tokenizer-pool-size

说明

用于控制分词操作的并发能力,定义了分词池的大小，从而决定是否启用异步分词以及并发分词的线程数或进程数。
设置为 0 ：禁用分词池，使用同步分词。分词操作将在主线程中顺序执行，适用于低并发场景或对延迟要求不高的任务。
设置为大于 0 的值 ：启用分词池，使用异步分词。分词操作将在指定数量的线程或进程中并行执行，适用于高并发场景或需要加速分词的任务。
通过调整该参数，可以优化分词性能，尤其是在处理大量输入数据时。

默认值

默认情况下，该参数值为 0，即禁用分词池，使用同步分词。

参数选项

# 设置为 0：禁用分词池，使用同步分词。
vllm serve \
  --model /path/to/model \
  --tokenizer-pool-size 0

# 设置为大于 0 的值：启用分词池，使用异步分词。
vllm serve \
  --model /path/to/model \
  --tokenizer-pool-size 4

使用场景

  1. 低并发场景:服务的请求量较低或者分词操作不是性能瓶颈，可以保持默认值 0，使用同步分词以简化实现和减少资源开销。
  2. 高并发场景:在高并发场景下，分词操作可能成为性能瓶颈。通过设置 --tokenizer-pool-size 为大于 0 的值（如 4 或 8），可以启用异步分词，提升分词吞吐量。
  3. 大规模批处理任务:在处理大规模批处理任务时，启用分词池可以显著加速分词操作，从而提高整体任务的效率。
  4. 性能调优:用户可以通过调整 --tokenizer-pool-size 的值，对比不同配置下的分词性能（如吞吐量和延迟），从而找到最优的分词池大小。
  5. 资源受限环境:在资源受限的环境中（如 CPU 核心数较少或内存有限），可以将 --tokenizer-pool-size 设置为较小的值，以避免过度消耗系统资源。

2、--tokenizer-pool-type

说明

用于指定分词池的类型。决定了在启用异步分词时（即 --tokenizer-pool-size > 0），分词操作将使用哪种并发框架或机制来实现。
如果 --tokenizer-pool-size 设置为 0，则该参数被忽略，因为此时分词操作是同步的，不涉及分词池。

默认值

默认情况下，该参数值为 "ray"，即使用 Ray 框架作为分词池的实现。

参数选项

# 使用 Ray 作为分词池类型（默认行为）。
vllm serve \
  --model /path/to/model \
  --tokenizer-pool-size 4 \
  --tokenizer-pool-type ray

# 使用其他分词池类型（假设支持其他选项，如 "thread" 或 "process"）。
vllm serve \
  --model /path/to/model \
  --tokenizer-pool-size 4 \
  --tokenizer-pool-type thread

注意：目前 vLLM 官方文档中仅明确支持 "ray" 类型。如果需要使用其他类型（如线程池或进程池），需要确认 vLLM 是否支持这些选项。

使用场景

  1. 默认使用 Ray:系统环境中已经安装了 Ray，并且任务对分词性能要求较高，可以直接使用默认的 "ray" 类型。
  2. 调试和对比性能:可以通过调整 --tokenizer-pool-type 的值，对比不同分词池类型的性能表现，从而选择最适合当前任务的配置。
  3. 资源受限环境:在资源受限的环境中（如内存有限或无法安装 Ray），可以选择更轻量级的分词池类型（如线程池），以减少资源消耗。

3、--tokenizer-pool-extra-config

说明

用于为分词池提供额外的配置选项。这些配置以 JSON 格式的字符串形式传递，并会被解析为字典，供分词池实现框架（如 Ray）使用。
该参数仅在 --tokenizer-pool-size > 0 时生效。如果 --tokenizer-pool-size 设置为 0，则该参数被忽略，因为此时分词操作是同步的，不涉及分词池,通过该参数，用户可以对分词池的行为进行更细粒度的控制，例如调整线程数、内存限制或其他框架特定的配置。

默认值

默认情况下，该参数为空，即不传递任何额外配置。

参数选项

# 不传递额外配置（默认行为）。
vllm serve \
  --model /path/to/model \
  --tokenizer-pool-size 4

# 传递额外配置（JSON 字符串格式）。
vllm serve \
  --model /path/to/model \
  --tokenizer-pool-size 4 \
  --tokenizer-pool-extra-config '{"resources": {"CPU": 2, "GPU": 0.5}}' 
  #{"memory": 4 * 1024 * 1024 * 1024}  // 4GB 内存
  #{"scheduling_strategy": "SPREAD"}

"CPU"：指定所需的 CPU 核心数（如 2 表示需要 2 个 CPU 核心）。
"GPU"：指定所需的 GPU 资源（如 0.5 表示需要半个 GPU）。

scheduling_strategy:

  • "SPREAD"：将任务均匀分布在集群中的节点上。
  • "DEFAULT"：使用默认的调度策略。
  • "NODE_AFFINITY"：将任务绑定到特定的节点。

使用场景

  1. 调整分词池性能:高并发场景下，可以通过传递额外配置来优化分词池的性能。
  2. 资源限制:在资源受限的环境中，可以通过传递额外配置来限制分词池的资源使用。
  3. 框架特定配置:使用 "ray" 作为分词池类型，可以通过该参数传递 Ray 框架的特定配置。
  4. 调试和对比性能:可以通过调整 --tokenizer-pool-extra-config 的值，对比不同配置下的分词性能，从而找到最优的配置。

调度与性能优化

1、--scheduler-delay-factor

说明

用于在调度下一个提示（prompt）之前引入一个延迟。这个延迟的大小是基于前一个提示的推理延迟（latency）乘以一个延迟因子（delay factor）来计算的。
延迟的计算公式：延迟时间=delay factor×前一个提示的推理延迟
如果设置为 0.0（默认值），则不引入任何延迟，调度器会尽可能快地调度新任务。

默认值

默认情况下，该参数值为 0.0，即不引入延迟。

参数选项

# 使用默认值（不引入延迟）。
vllm serve \
  --model /path/to/model

# 设置延迟因子为 0.5。
vllm serve \
  --model /path/to/model \
  --scheduler-delay-factor 0.5

# 设置延迟因子为 1.0。
vllm serve \
  --model /path/to/model \
  --scheduler-delay-factor 1.0

使用场景

  1. 避免系统资源过载:在高并发场景中，如果调度器过于频繁地调度新任务，可能会导致系统资源（如 GPU 显存或 CPU 计算能力）过载。通过引入延迟，可以缓解资源压力，确保系统稳定运行。
  2. 平衡吞吐量和延迟:如果任务对延迟要求较高（如实时对话系统），可以保持较小的延迟因子，以确保快速响应.如果任务对吞吐量要求较高（如批量推理任务），可以增加延迟因子，以减少调度频率并提高整体效率。
  3. 调试和对比性能:用户可以通过调整 --scheduler-delay-factor 的值，对比不同配置下的性能表现（如吞吐量、延迟和资源利用率），从而找到最优的配置。

2、--num-scheduler-steps

说明

用于控制每次调度器调用时的最大前向计算步数（forward steps）。调度器是 vLLM 中负责管理推理任务的核心组件，它决定了如何将输入数据分批处理并分配到硬件设备上。

  • 增加该值可以减少调度器调用的频率，从而降低调度开销；但可能会增加单次计算的延迟。
  • 减少该值可以提高调度的灵活性，但可能会增加调度器调用的频率和开销。

默认值

默认情况下，该参数值为 1，即每次调度器调用仅执行 1 次前向计算。

参数选项

# 使用默认值（每次调度器调用执行 1 次前向计算）。
vllm serve \
  --model /path/to/model

# 设置每次调度器调用执行 4 次前向计算。
vllm serve \
  --model /path/to/model \
  --num-scheduler-steps 4

使用场景

  1. 优化调度开销:在高并发场景中，频繁的调度器调用可能会导致额外的开销。通过增加 --num-scheduler-steps 的值，可以减少调度器调用的频率，从而优化性能。
  2. 平衡延迟和吞吐量:如果任务对延迟要求较高（如实时对话系统），可以保持较小的 --num-scheduler-steps 值，以确保快速响应.如果任务对吞吐量要求较高（如批量推理任务），可以增加 --num-scheduler-steps 的值，以提高整体效率。
  3. 调试和对比性能:用户可以通过调整 --num-scheduler-steps 的值，对比不同配置下的性能表现（如吞吐量、延迟和资源利用率），从而找到最优的配置。

3、--scheduling-policy

说明

用于指定模型推理服务的调度策略。通过合理设置该参数，可以在公平性和优先级之间取得最佳平衡，适用于不同场景下的性能优化需求。
--scheduling-policy 提供了两种选项：

  • fcfs（First Come First Served，先到先服务） ：
    请求按照到达顺序依次处理。

特点：简单、公平，适合大多数场景。

  • priority（优先级调度） ：
    请求根据优先级值进行处理，优先级较低的请求会优先被处理。如果优先级相同，则按照到达时间决定顺序。

特点：灵活，适合需要区分请求重要性的场景。

默认值

默认值：fcfs 在默认情况下，vLLM 使用先到先服务的调度策略来处理请求。

参数选项

--scheduling-policy 是一个字符串类型的参数，支持以下两种选项：

  • fcfs ：
    使用先到先服务的调度策略。
  • priority ：
    使用优先级调度策略。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --scheduling-policy priority \
    --gpu-memory-utilization 0.8 \
    --port 8000

--scheduling-policy priority :启用优先级调度策略，允许根据请求的优先级值进行处理。

使用场景

  1. 公平性优先的场景:在需要确保所有请求公平处理的场景中（如在线聊天机器人、实时翻译等），可以选择 fcfs 策略。
  2. 优先级区分的场景:在需要区分请求重要性的场景中（如高优先级用户或任务），可以选择 priority 策略，并为不同请求分配优先级值。

4、--enable-sleep-mode

说明

用于启用 GPU 的睡眠模式以优化能耗。通过合理设置该参数，可以在能耗和性能之间取得最佳平衡，适用于不同场景下的推理任务需求。
睡眠模式是一种优化机制，旨在减少 GPU 的空闲时间功耗，同时在需要时快速唤醒以处理推理任务。

  • 睡眠模式的作用 ：
    在推理任务之间存在空闲时间的情况下，睡眠模式会将 GPU 置于低功耗状态（类似于“休眠”），从而节省能源。

当有新的推理请求到达时，GPU 会快速唤醒并恢复到正常工作状态。

  • 适用平台 ：
    目前，该功能仅支持 CUDA 平台（即 NVIDIA GPU）。

默认值

默认值：未启用（需显式设置） 在默认情况下，睡眠模式不会被启用。如果需要启用该功能，则必须显式设置该参数。

参数选项

--enable-sleep-mode 是一个布尔型参数，支持以下两种选项：

  • True ：
    启用睡眠模式，GPU 在空闲时进入低功耗状态。
  • False ：
    禁用睡眠模式（默认行为），GPU 始终保持活动状态。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --enable-sleep-mode True \
    --gpu-memory-utilization 0.8 \
    --port 8000

--enable-sleep-mode True :启用睡眠模式，GPU 在空闲时进入低功耗状态。

使用场景

  1. 节能优化:在推理任务负载较低的场景中（如夜间或低流量时段），可以通过启用睡眠模式减少 GPU 的空闲功耗，从而降低能源消耗和运行成本。
  2. 高性能需求:在需要持续高吞吐量的场景中（如实时聊天机器人或批量推理任务），建议禁用睡眠模式以避免唤醒延迟。

5、--calculate-kv-scales

说明

用于控制是否动态计算 FP8 数据类型的缩放因子（k_scale 和 v_scale）。通过合理设置该参数，可以在数值精度和性能之间取得最佳平衡，适用于不同场景下的推理任务需求。
这些缩放因子（scales）用于量化和反量化操作，确保低精度数据类型的数值范围能够正确表示。

  1. FP8 数据类型的背景 ：

    • FP8 是一种低精度浮点数格式，广泛应用于高性能推理场景中以减少显存占用和提高计算效率。
    • 在 FP8 中，k_scale 和 v_scale 是缩放因子，用于将高精度数据（如 FP16 或 FP32）映射到 FP8 范围，并在需要时恢复原始值。

  2. 动态计算的作用 ：

    • 如果启用动态计算（--calculate-kv-scales=True），系统会在运行时根据输入数据动态计算 k_scale 和 v_scale，从而确保最佳的数值精度。
    • 如果禁用动态计算（--calculate-kv-scales=False），系统会尝试从模型检查点加载预定义的缩放因子；如果检查点中没有提供，则默认使用 1.0。

默认值

默认值：未明确说明（需显式设置） 在默认情况下，系统可能会根据上下文自动选择是否动态计算缩放因子。如果需要明确控制该行为，则必须显式设置该参数。

参数选项

--calculate-kv-scales 是一个布尔型参数，支持以下两种选项：

  • True ：
    启用动态计算，系统会在运行时根据输入数据动态计算 k_scale 和 v_scale。
  • False ：
    禁用动态计算，系统会尝试从模型检查点加载预定义的缩放因子；如果检查点中没有提供，则默认使用 1.0。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --kv-cache-dtype fp8 \
    --calculate-kv-scales True \
    --gpu-memory-utilization 0.8 \
    --port 8000

--calculate-kv-scales True :启用动态计算，系统会在运行时根据输入数据动态计算 k_scale 和 v_scale。

使用场景

  1. 动态精度优化:在需要动态调整数值精度的场景中（如输入数据分布变化较大的任务），可以通过启用动态计算确保 FP8 数据的数值范围始终适配输入数据。
  2. 固定缩放因子:如果模型检查点中已经提供了预定义的缩放因子，并且输入数据分布较为稳定，可以选择禁用动态计算以减少运行时开销。

6、--disable-async-output-proc

说明

用于控制是否禁用异步输出处理。默认值为 False，即启用异步输出处理以优化性能。在需要简化调试或避免并发问题的场景中，可以通过设置为 True 禁用该功能。合理使用该参数可以在性能和调试便利性之间取得最佳平衡。

  1. 异步输出处理的作用 ：
  • 在默认情况下，vLLM 使用异步输出处理来加速推理结果的生成和返回。例如，当主模型完成推理后，输出处理（如格式化、编码等）可以在后台线程中进行，而无需阻塞主线程。
  1. 禁用异步输出处理 ：
  • 如果设置 --disable-async-output-proc=True，则会禁用异步输出处理，所有操作将在单一线程中同步执行。这可能会降低性能，但在某些场景下可以简化调试或避免潜在的并发问题。

默认值

默认值：False 在默认情况下，vLLM 启用异步输出处理以优化性能。如果需要禁用该功能，则必须显式设置该参数。

参数选项

--disable-async-output-proc 是一个布尔型参数，支持以下两种选项：

  • True ：
    禁用异步输出处理，所有操作将在单一线程中同步执行。
  • False ：
    启用异步输出处理（默认行为），允许模型推理和结果处理并行执行。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --disable-async-output-proc True \
    --gpu-memory-utilization 0.8 \
    --port 8000

--disable-async-output-proc True :禁用异步输出处理，所有操作将在单一线程中同步执行。

使用场景

  1. 性能优化:在大多数情况下，建议保持异步输出处理启用（即不设置该参数或设置为 False），以充分利用多线程的优势，提高推理性能。
  2. 资源受限场景:在硬件资源有限的情况下（如单核 CPU 或低性能 GPU），禁用异步输出处理可以减少线程切换的开销。
  3. 简化调试:在调试模型推理过程时，禁用异步输出处理可以避免并发问题，从而更容易定位错误。

模型结构与参数调整

1、--rope-scaling

说明

用于配置 RoPE（Rotary Position Embedding）缩放 的行为,RoPE 缩放是一种技术，用于扩展模型对长序列的支持能力。
默认情况下，RoPE 的位置编码是基于固定的最大上下文长度设计的。如果输入序列超过这个长度，模型可能会出现性能下降。
通过设置 --rope-scaling，可以动态调整 RoPE 的缩放因子，使模型更好地处理长序列。

默认值

默认不会启用 RoPE 缩放。

参数选项

# 启用动态 RoPE 缩放，缩放因子为 2.0
vllm serve \
  --rope-scaling='{"rope_type":"dynamic","factor":2.0}'

rope_type 设置为 "dynamic"，表示使用动态缩放。
factor 设置为 2.0，表示将 RoPE 的有效范围扩展为原来的 2 倍。模型的最大上下文长度为 2048，但输入序列长度为 4096，可以通过设置 factor=2.0 将 RoPE 的有效范围扩展到 4096。

使用场景

  1. 长序列任务（如文档生成、长文本摘要）。
  2. 调试和验证。
  3. 动态调整。

2、--rope-theta

说明

用于调整 RoPE（Rotary Position Embedding） 的基础频率参数 theta。
RoPE 使用正弦和余弦函数生成位置编码，其频率由 theta 控制。
默认情况下，theta 的值是固定的（例如，LLaMA 中默认为 10000），但在某些情况下，调整 theta 可以改善模型的性能，尤其是在启用 RoPE 缩放 （--rope-scaling）时。
--rope-theta 通常与 --rope-scaling 配合使用,在启用 RoPE 缩放时，调整 theta 可以进一步优化模型对长序列的支持能力。

默认值

默认情况下 theta 的值通常是模型预设的固定值（如 R1 中的 10000）。可在模型文件的config.json中查看

{
"rope_theta": 10000
}

参数选项

# 启用动态 RoPE 缩放，并调整 theta 为 5000
vllm serve \
  --rope-scaling='{"rope_type":"dynamic","factor":2.0}' \
  --rope-theta=5000

--rope-scaling 启用了动态缩放，缩放因子为 2.0。
--rope-theta 将 theta 设置为 5000，以优化 RoPE 的频率分布。

使用场景

  1. 长序列任务（如文档生成、长文本摘要）。
  2. 调试和验证。
  3. 动态调整。

3、--max-seq-len-to-capture

说明

用于设置 CUDA Graphs 能够捕获的最大序列长度
CUDA Graphs 是一种优化技术，通过将计算图编译为静态图来减少 GPU 调度开销，从而提高推理性能。
然而，CUDA Graphs 的捕获范围是有限的。如果输入序列的上下文长度（context length）超过了 --max-seq-len-to-capture 的值，系统会回退到 eager 模式 （动态图模式）。
对于编码器-解码器模型（如 T5、BART），如果编码器输入的序列长度超过此值，也会回退到 eager 模式。

默认值

默认值为 8192，即 CUDA Graphs 默认能够捕获的最大序列长度为 8192。

参数选项

# 设置 CUDA Graphs 能够捕获的最大序列长度为 16384
vllm serve \
  --max-seq-len-to-capture=16384

--max-seq-len-to-capture=16384 表示 CUDA Graphs 能够捕获的最大序列长度为 16384。
如果输入序列的上下文长度超过 16384，系统会回退到 eager 模式。

使用场景

  1. 短序列任务（如上下文长度小于 8192）。
  2. 长序列任务（如上下文长度超过 8192）。
  3. 调试和验证。

4、--generation-config

说明

用于指定生成配置的加载路径。通过合理设置该参数，可以统一管理推理任务的生成参数，适用于不同场景下的文本生成需求。
生成配置包含与文本生成相关的参数设置，例如最大生成长度（max_new_tokens）、温度（temperature）、Top-K 和 Top-P 等。

  1. 生成配置的作用 ：

    • 生成配置允许用户自定义模型的推理行为，而无需在每次请求中显式传递这些参数。通过加载生成配置文件，可以统一管理推理任务的行为。

  2. 加载方式 ：

    • 如果未指定该参数，则使用 vLLM 的默认生成配置。
    • 如果设置为 'auto'，则从模型路径中自动加载生成配置。
    • 如果设置为一个文件夹路径，则从指定路径加载生成配置。

默认值

默认值：None 在默认情况下，vLLM 不会加载任何生成配置，而是使用其内置的默认值。

参数选项

  1. --generation-config 是一个字符串类型的参数，支持以下三种格式：

    • None ：
      不加载任何生成配置，使用 vLLM 的默认生成配置。
    • auto ：
      自动从模型路径中加载生成配置文件（如 generation_config.json）。
    • 文件夹路径 ：
      指定一个文件夹路径，从该路径加载生成配置文件。

  2. 常见的生成配置参数包括：

    • max_new_tokens ：
      设置生成的最大 token 数量。如果指定了该参数，则会对所有请求设置一个全局限制。
    • temperature ：
      控制生成文本的随机性。较低的值（如 0.1）会生成更确定性的文本，较高的值（如 1.0）会生成更多样化的文本。
    • top_k 和 top_p ：
      分别控制 Top-K 和 Top-P 采样的参数，用于调整生成文本的质量和多样性。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --generation-config "auto" \
    --gpu-memory-utilization 0.8 \
    --port 8000

--generation-config "auto" :自动从模型路径中加载生成配置文件（如 generation_config.json）。

使用场景

  1. 统一管理生成参数:在需要对所有推理请求应用相同生成参数的场景中，可以通过加载生成配置文件来统一管理这些参数。
  2. 设置全局限制:如果需要对所有请求设置一个全局的最大生成长度限制，可以在生成配置文件中指定 max_new_tokens。
  3. 适配特定任务:针对不同的任务需求（如创意写作、问答系统等），可以加载不同的生成配置文件以优化生成效果。

5、--override-generation-config

说明

用于覆盖或设置生成配置。通过合理设置该参数，可以动态调整模型的推理行为，适用于不同场景下的文本生成需求。
允许用户以 JSON 格式传递生成参数，从而动态调整模型的推理行为。

  • 覆盖生成配置的作用 ：
    通过 --override-generation-config，可以覆盖默认生成配置中的某些参数，或者在未加载生成配置文件时直接指定生成参数。

如果与 --generation-config=auto 或 --generation-config=<path> 一起使用，覆盖参数会与加载的生成配置合并；如果未加载生成配置，则仅使用覆盖参数。

默认值

默认值：无（需显式设置） 在默认情况下，不会应用任何覆盖参数。如果需要自定义生成配置，则必须显式设置该参数。

参数选项

--override-generation-config 是一个字符串类型的参数，必须是有效的 JSON 格式。常见的生成参数包括：

  • temperature ：
    控制生成文本的随机性。较低的值（如 0.1）会生成更确定性的文本，较高的值（如 1.0）会生成更多样化的文本。

示例：{"temperature": 0.5}

  • top_k 和 top_p ：
    分别控制 Top-K 和 Top-P 采样的参数，用于调整生成文本的质量和多样性。

示例：{"top_k": 50, "top_p": 0.9}

  • max_new_tokens ：
    设置生成的最大 token 数量。如果指定了该参数，则会对所有请求设置一个全局限制。

示例：{"max_new_tokens": 128}

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --override-generation-config '{"temperature": 0.5, "max_new_tokens": 64}' \
    --gpu-memory-utilization 0.8 \
    --port 8000

--override-generation-config '{"temperature": 0.5, "max_new_tokens": 64}' :覆盖生成配置，将温度设置为 0.5，并限制最大生成长度为 64 个 token。

使用场景

  1. 动态调整生成参数:在需要对特定任务动态调整生成参数的场景中，可以通过覆盖生成配置快速实现。
  2. 与生成配置文件结合使用:如果已经加载了生成配置文件，但需要覆盖其中的某些参数，可以通过该参数实现。
  3. 适配特定任务:针对不同的任务需求（如创意写作、问答系统等），可以动态调整生成参数以优化生成效果。

LoRA/适配器配置

1、--max-loras

说明

用于控制在推理或微调过程中单个批次（batch）可以同时加载和处理的 LoRA 适配器的最大数量。
如果任务需要在单个批次中处理多个 LoRA 适配器（例如多任务场景），可以通过调整该参数来满足需求。

默认值

默认支持 1 个 LoRA 适配器。

参数选项

# 设置单个批次中最多支持 4 个 LoRA 适配器。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --max-loras 4

# 使用默认值（通常为 1）。
vllm serve \
  --model /path/to/model \
  --enable-lora

使用场景

  1. 多任务推理:多任务场景中，需要在单个批次中加载多个 LoRA 适配器以适应不同的下游任务。通过设置 --max-loras，可以确保系统能够支持所需的适配器数量。
  2. 动态任务切换:服务需要动态切换不同的 LoRA 适配器（例如根据用户请求加载特定的适配器），可以通过增加 --max-loras 的值来支持更多的并发适配器。
  3. 性能优化:高并发场景下，增加 --max-loras 的值可以减少适配器切换的频率，提高整体吞吐量。
  4. 调试和对比性能:可以通过调整 --max-loras 的值，对比不同配置下的性能表现（如吞吐量、延迟和内存使用），从而找到最优的配置。

2、--max-lora-rank

说明

用于控制 LoRA 适配器中低秩矩阵的最大秩（rank）。
秩是低秩矩阵的一个关键超参数，决定了 LoRA 适配器的表达能力和计算开销。

  • 该参数定义了 LoRA 适配器中低秩矩阵的最大秩值。
  • 较大的秩值可以提高模型的表达能力，但会增加计算和内存开销。
  • 较小的秩值可以降低资源消耗，但可能限制模型的表现。

默认值

默认情况下，该参数值为 16，即 LoRA 适配器中低秩矩阵的最大秩为 16。

参数选项

# 使用默认最大秩值（16）。
vllm serve \
  --model /path/to/model \
  --enable-lora

# 设置最大秩值为 32。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --max-lora-rank 32

使用场景

  1. 提高模型表现:任务对模型的表达能力要求较高（如复杂任务或高精度需求），可以通过增加 --max-lora-rank 的值来提高 LoRA 适配器的表达能力。
  2. 优化资源使用:资源受限的环境中（如 GPU 显存较小），可以通过减小 --max-lora-rank 的值来降低计算和内存开销。
  3. 调试和对比性能:用户可以通过调整 --max-lora-rank 的值，对比不同配置下的模型性能（如准确性、推理速度和内存占用），从而找到最优的秩值。
  4. 多任务场景:在多任务场景中，不同的任务可能需要不同的秩值。通过设置 --max-lora-rank，可以确保系统能够支持所需的秩值范围。

3、--lora-extra-vocab-size

说明

用于控制 LoRA 适配器中可以扩展的最大额外词汇表大小。LoRA 适配器允许在预训练模型的基础上引入新的词汇（例如特定领域的术语）,如果任务需要扩展词汇表可以通过调整该参数来满足需求。

默认值

默认情况下，该参数值为 256，即 LoRA 适配器最多可以扩展 256 个额外词汇。

参数选项

# 使用默认最大额外词汇表大小（256）。
vllm serve \
  --model /path/to/model \
  --enable-lora

# 设置最大额外词汇表大小为 512。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --lora-extra-vocab-size 512

使用场景

  1. 扩展词汇表:在某些任务中，可能需要处理特定领域的新词或未登录词（如医学术语、法律术语等）。通过增加 --lora-extra-vocab-size 的值，可以支持更多的额外词汇。
  2. 多领域适配:任务涉及多个领域（如金融、医疗、科技等），每个领域可能需要扩展不同的词汇表。通过设置较大的 --lora-extra-vocab-size，可以确保系统能够支持所需的词汇扩展。
  3. 优化资源使用:在资源受限的环境中，可以通过减小 --lora-extra-vocab-size 的值来降低内存和计算开销。
  4. 调试和对比性能:用户可以通过调整 --lora-extra-vocab-size 的值，对比不同配置下的模型性能（如准确性、推理速度和内存占用），从而找到最优的词汇表扩展范围。

4、--max-cpu-loras

说明

用于控制可以存储在 CPU 内存中的 LoRA 适配器的最大数量。

  • 如果任务需要处理的 LoRA 适配器数量较多，但 GPU 显存不足以同时加载所有适配器时，可以通过将部分适配器存储在 CPU 内存中来缓解显存压力。
  • --max-cpu-loras 的值必须大于或等于 --max-loras（单个批次中支持的最大 LoRA 适配器数量）。如果未显式设置，默认值为 --max-loras。

默认值

默认情况下，该参数值等于 --max-loras，即 CPU 内存中缓存的 LoRA 适配器数量与单个批次中支持的最大适配器数量相同。

参数选项

# 使用默认值（等于 max_loras）。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --max-loras 4

# 显式设置最大 CPU 缓存的 LoRA 数量。
vllm serve \
  --model /path/to/model \
  --enable-lora \
  --max-loras 4 \
  --max-cpu-loras 8

使用场景

  1. 缓解 GPU 显存压力:在高并发或多任务场景中，可能需要加载多个 LoRA 适配器，但 GPU 显存不足以同时容纳所有适配器。通过增加 --max-cpu-loras 的值，可以将部分适配器存储在 CPU 内存中，从而缓解显存压力。
  2. 动态任务切换:如果服务需要动态切换不同的 LoRA 适配器（例如根据用户请求加载特定的适配器），可以通过增加 --max-cpu-loras 的值来减少适配器从磁盘加载到内存的频率，从而提高切换效率。
  3. 优化资源使用:在资源受限的环境中，可以通过调整 --max-cpu-loras 的值，在 GPU 和 CPU 资源之间找到平衡。
  4. 调试和对比性能:用户可以通过调整 --max-cpu-loras 的值，对比不同配置下的性能表现（如吞吐量、延迟和内存占用），从而找到最优的资源配置。

5、--max-prompt-adapters

说明

该参数定义了在推理或微调过程中，单个批次中可以同时加载和处理的 Prompt Adapter 的最大数量。
如果任务需要在单个批次中处理多个 Prompt Adapter（例如多任务场景），可以通过调整该参数来满足需求。

默认值

默认情况下，该参数值为 1，即单个批次中最多支持加载 1 个 Prompt Adapter。

参数选项

# 使用默认值（单个批次中最多支持 1 个 Prompt Adapter）。
vllm serve \
  --model /path/to/model \
  --enable-prompt-adapter

# 设置单个批次中最多支持 4 个 Prompt Adapter。
vllm serve \
  --model /path/to/model \
  --enable-prompt-adapter \
  --max-prompt-adapters 4

使用场景

  1. 多任务推理:在多任务场景中，可能需要在单个批次中加载多个 Prompt Adapter 以适应不同的下游任务。通过设置 --max-prompt-adapters，可以确保系统能够支持所需的适配器数量。
  2. 动态任务切换:服务需要动态切换不同的 Prompt Adapter（例如根据用户请求加载特定的适配器），可以通过增加 --max-prompt-adapters 的值来支持更多的并发适配器。
  3. 性能优化:在高并发场景下，增加 --max-prompt-adapters 的值可以减少适配器切换的频率，从而提高整体吞吐量。
  4. 调试和对比性能:可以通过调整 --max-prompt-adapters 的值，对比不同配置下的性能表现（如吞吐量、延迟和内存使用），从而找到最优的配置。

6、--max-prompt-adapter-token

说明

用于控制 Prompt Adapter 中允许的最大 token 数量。

  • 如果设置为 0（默认值），表示不限制 Prompt Adapter 的 token 数量。
  • 如果设置为大于 0 的值，则会限制 Prompt Adapter 的最大长度，从而优化内存使用和计算效率。

默认值

默认情况下，该参数值为 0，即不限制 Prompt Adapter 的 token 数量。

参数选项

# 不限制 Prompt Adapter 的 token 数量（默认行为）。
vllm serve \
  --model /path/to/model \
  --enable-prompt-adapter

# 限制 Prompt Adapter 的最大 token 数量为 128。
vllm serve \
  --model /path/to/model \
  --enable-prompt-adapter \
  --max-prompt-adapter-token 128

使用场景

  1. 优化资源使用:资源受限的环境中（如 GPU 显存较小），可以通过限制 Prompt Adapter 的 token 数量来降低内存和计算开销。
  2. 控制输入长度:任务对 Prompt Adapter 的长度有明确要求（如需要短提示或长提示），可以通过该参数强制限制其最大长度。
  3. 多任务推理:在多任务场景中，不同的任务可能需要不同长度的 Prompt Adapter。通过设置合理的最大 token 数量，可以确保系统能够支持所需的适配器长度。
  4. 调试和对比性能:用户可以通过调整 --max-prompt-adapter-token 的值，对比不同配置下的性能表现（如吞吐量、延迟和内存占用），从而找到最优的配置。

硬件与设备指定

1、--device

说明

用于指定 vLLM 的执行设备。vLLM 支持多种硬件设备（如 GPU、CPU 和专用加速器），通过该参数可以选择适合任务需求的设备类型。

  • 如果设置为 "auto"，vLLM 会根据当前环境自动选择最优的设备（例如优先使用 GPU，如果没有 GPU 则回退到 CPU）。
  • 如果显式指定设备类型（如 "cuda" 或 "cpu"），vLLM 将强制使用该设备，而不依赖自动检测。

默认值

默认情况下，该参数值为 "auto"，即 vLLM 会根据当前环境自动选择最优的设备。

参数选项

# 使用自动检测设备（默认行为）。
vllm serve \
  --model /path/to/model

# 强制使用 CUDA 设备（GPU）。
vllm serve \
  --model /path/to/model \
  --device cuda

# 强制使用 CPU。
vllm serve \
  --model /path/to/model \
  --device cpu

# 强制使用其他设备类型（如 Neuron、TPU 等）。
vllm serve \
  --model /path/to/model \
  --device tpu
设备类型说明
auto自动检测设备类型。优先使用 GPU（如 CUDA），如果没有 GPU，则回退到 CPU。
cuda使用 NVIDIA GPU 进行计算（需要安装 CUDA 和相关驱动）。
neuron使用 AWS 的 Neuron 加速器（专为 Inferentia 芯片优化）。
cpu使用 CPU 进行计算，适合没有 GPU 或资源受限的环境。
openvino使用 OpenVINO 工具套件进行推理优化（适用于 Intel CPU 和集成 GPU）。
tpu使用 Google TPU 进行计算（需要支持 TPU 的环境，如 Google Cloud 或 Colab TPU）。
xpu使用 Intel 的 XPU（如 GPU 或其他加速器）。
hpu使用 Habana Labs 的 Gaudi 加速器（专为深度学习训练和推理优化）。

使用场景

  1. 自动检测设备:不确定当前环境支持哪些设备，可以使用默认值 "auto"，让 vLLM 自动选择最优设备。
  2. 强制使用 GPU:环境中有多块 GPU，并希望确保使用 GPU 进行计算，可以显式指定 "cuda"。
  3. 资源受限环境:如果环境中没有 GPU 或 GPU 资源不足，可以强制使用 "cpu"，以避免 GPU 显存不足的问题。
  4. 专用加速器:使用的是专用硬件加速器（如 AWS Inferentia、Google TPU 或 Habana Gaudi），可以指定相应的设备类型。
  5. 调试和对比性能:用户可以通过调整 --device 的值，对比不同设备类型下的性能表现（如吞吐量、延迟和内存占用），从而找到最优的配置。

2、--override-neuron-config

说明

用于覆盖或设置 Neuron 设备的配置。通过合理设置该参数，可以在显存占用、推理速度和输出质量之间取得最佳平衡，适用于不同硬件资源和负载场景下的性能优化需求。

  • Neuron 配置的作用 ：
    Neuron 设备的默认配置可能无法完全满足特定场景的需求。通过 --override-neuron-config，可以覆盖默认配置，从而优化性能或适配特定任务。
  • JSON 格式 ：
    该参数接受一个 JSON 字符串，解析后会作为字典传递给 Neuron 设备的配置接口。

默认值

默认值：无（需显式设置） 在默认情况下，Neuron 设备会使用其默认配置。如果需要自定义配置，则必须显式设置该参数。

参数选项

--override-neuron-config 是一个字符串类型的参数，必须是有效的 JSON 格式。常见的配置选项包括：

  • cast_logits_dtype ：
    指定 logits 数据类型的转换方式。例如，将 logits 转换为 bfloat16 或 float16，以减少显存占用和计算开销。

示例：{"cast_logits_dtype": "bfloat16"}

  • memory_optimization ：
    启用或禁用内存优化策略。例如，设置为 true 可以减少显存占用。

示例：{"memory_optimization": true}

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --override-neuron-config '{"cast_logits_dtype": "bfloat16"}' \
    --gpu-memory-utilization 0.8 \
    --port 8000

--override-neuron-config '{"cast_logits_dtype": "bfloat16"}' :覆盖 Neuron 设备的默认配置，将 logits 数据类型转换为 bfloat16。

使用场景

  1. 显存优化:在显存资源有限的情况下，可以通过设置 cast_logits_dtype 将 logits 转换为低精度数据类型（如 bfloat16），从而减少显存占用。
  2. 性能调优:在需要更高推理速度的场景中，可以通过启用内存优化或其他高级选项来提升性能。

调试与日志

1、--disable-log-stats

说明

用于控制是否禁用统计信息的日志记录（logging statistics）
在推理或训练过程中,系统会记录各种统计信息（如吞吐量、延迟、显存使用等），以便监控性能和调试问题,--disable-log-stats 参数可以禁用这些统计信息的日志记录。

默认值

默认情况下统计信息的日志记录是启用的。

参数选项

vllm serve \
  --disable-log-stats

使用场景

  1. 生产环境（减少日志输出）。
  2. 资源受限环境（降低系统开销）。
  3. 调试和优化（分析性能指标）。

2、--collect-detailed-traces

说明

用于控制是否收集模型推理过程中特定模块的详细追踪数据。通过启用该功能，可以深入分析系统性能瓶颈或调试分布式系统问题，但需要注意其可能带来的性能影响。适用于需要详细性能分析或故障排查的场景。

  • 该参数支持以下三种模块：

    • model ：仅收集与主模型相关的详细追踪数据。
    • worker ：仅收集与工作线程（Worker Threads）相关的详细追踪数据。
    • all ：收集所有模块（包括模型和工作线程）的详细追踪数据。

  • 性能影响 ：

    • 收集详细追踪数据可能会引入额外的计算开销或阻塞操作，从而对推理性能产生一定影响。因此，建议仅在需要深入分析时启用该功能。

默认值

默认值：无（需显式设置） 在默认情况下，vLLM 不会收集详细追踪数据。如果需要启用该功能，则必须显式设置该参数。

参数选项

--collect-detailed-traces 是一个字符串类型的参数，支持以下三种选项：

  • model ：
    仅收集与主模型相关的详细追踪数据。
  • worker ：
    仅收集与工作线程相关的详细追踪数据。
  • all ：
    收集所有模块（包括模型和工作线程）的详细追踪数据。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --otlp-traces-endpoint http://localhost:4318/v1/traces \
    --collect-detailed-traces model \
    --gpu-memory-utilization 0.8 \
    --port 8000

--collect-detailed-traces model :仅收集与主模型相关的详细追踪数据。

使用场景

  1. 性能瓶颈分析:在生产环境中，如果发现模型推理性能下降，可以通过收集详细追踪数据（如 --collect-detailed-traces=model）分析主模型的执行情况，定位性能瓶颈。
  2. 分布式系统调试:在分布式部署中，如果工作线程之间的通信或任务分配存在问题，可以通过收集工作线程的详细追踪数据（如 --collect-detailed-traces=worker）进行调试。
  3. 全面性能监控:如果需要对整个系统的性能进行全面分析，可以收集所有模块的详细追踪数据（如 --collect-detailed-traces=all）。

3、--otlp-traces-endpoint

说明

用于指定 OpenTelemetry 追踪数据的目标 URL。通过启用追踪功能，可以将模型推理过程中的性能数据发送到观测性平台，从而实现性能监控、故障排查和系统优化。适用于生产环境中的性能分析和分布式系统的可观测性需求。
OpenTelemetry 是一个开源的观测性框架，用于收集分布式系统的追踪（traces）、指标（metrics）和日志（logs）。通过设置该参数，可以将模型推理过程中的追踪数据发送到指定的目标服务（如 Jaeger、Zipkin 或其他兼容 OTLP 的后端）。

  1. 追踪数据的作用 ：
    追踪数据记录了模型推理过程中各个组件的执行情况（如请求处理时间、GPU 利用率等），有助于性能分析、故障排查和系统优化。
  2. 目标 URL 的格式 ：
    --otlp-traces-endpoint 指定的目标 URL 必须支持 OTLP 协议，通常以 http:// 或 grpc:// 开头。

默认值

默认值：无（需显式设置） 在默认情况下，vLLM 不会发送 OpenTelemetry 追踪数据。如果需要启用追踪功能，则必须显式设置该参数。

参数选项

--otlp-traces-endpoint 是一个字符串类型的参数，支持以下两种协议格式：

  • HTTP 协议 ：
    使用 http:// 开头的 URL，例如 http://localhost:4318/v1/traces。
  • gRPC 协议 ：
    使用 grpc:// 开头的 URL，例如 grpc://localhost:4317。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --otlp-traces-endpoint http://localhost:4318/v1/traces \
    --gpu-memory-utilization 0.8 \
    --port 8000

--otlp-traces-endpoint http://localhost:4318/v1/traces :将追踪数据发送到本地运行的 Jaeger 收集器，其 HTTP 接口地址为 http://localhost:4318/v1/traces。

使用场景

  1. 性能监控:在生产环境中，可以通过启用 OpenTelemetry 追踪功能，将模型推理过程中的性能数据发送到监控系统（如 Jaeger 或 Zipkin），从而实时分析系统性能。
  2. 故障排查:在分布式系统中，追踪数据可以帮助定位性能瓶颈或错误来源。例如，通过分析请求链路中的延迟分布，快速找到问题组件。

安全与远程控制

1、--trust-remote-code

说明

用于控制是否信任从 HuggingFaceHub 加载的远程代码。默认情况下，Hugging Face 的 transformers 库会限制加载未经验证的远程代码，以防止潜在的安全风险。启用此参数后，系统将允许加载和执行远程存储库中的自定义代码或加载本地模型目录中包含自定义代码（例如自定义的模型架构或分词器实现），这些代码也需要通过 --trust-remote-code 来加载。

默认值

null

参数选项

null

使用场景

需要加载和执行远程存储库中的自定义代码或加载本地模型目录中包含自定义代码时需要启用

2、--allowed-local-media-path

说明

允许 使用 API 请求从服务器文件系统中指定的目录读取本地图像或视频文件。

默认值

null

参数选项

--allowed-local-media-path="<PATH&&filename>"

使用场景

需要处理存储在服务器本地的图像或视频文件，可以通过此参数指定文件所在的目录,通常适用于多模态模型

多媒体处理

1、--limit-mm-per-prompt

说明

用于限制每个提示（prompt）中允许的多模态输入实例数量。通过该参数，用户可以为不同的多模态类型（如图像、视频等）设置最大输入数量，从而控制资源使用和避免性能瓶颈。
用逗号分隔的键值对列表，形式为 modality1=value1,modality2=value2,...。
modality 表示多模态类型（如 image、video 等）。
value 表示该类型的最大输入实例数量。

默认值

默认情况下，每种多模态类型的输入实例数量限制为 1。

例如：

  • 图像（image）：最多 1 张。
  • 视频（video）：最多 1 段。

参数选项

# 设置每种多模态类型的输入实例数量限制。
vllm serve \
  --model /path/to/model \
  --limit-mm-per-prompt image=16,video=2

# 使用默认限制（每种多模态类型最多 1 个实例）。
vllm serve \
  --model /path/to/model

使用场景

  1. 高并发多模态任务:在处理包含大量多模态输入的任务时，可以通过增加限制来支持更多的输入实例。
  2. 资源受限环境:在资源受限的环境中，可以通过减少限制来降低资源消耗。
  3. 特定任务需求:如果任务只需要处理某种特定的多模态类型，可以只为该类型设置限制。
  4. 调试和性能优化:用户可以通过调整 --limit-mm-per-prompt 的值，对比不同配置下的性能表现（如吞吐量、延迟和资源利用率），从而找到最优的配置。

2、--mm-processor-kwargs

说明

用于覆盖默认的多模态处理器配置,允许用户自定义多模态处理器的行为，接受一个 JSON 字符串，表示键值对形式的配置项。

默认值

默认情况下，该参数为空，即使用多模态处理器的默认配置。

参数选项

# 使用默认配置（不传递额外参数）。
vllm serve \
  --model /path/to/model

# 覆盖多模态处理器的默认配置。
vllm serve \
  --model /path/to/model \
  --mm-processor-kwargs '{"num_crops": 4, "resize_size": 224}'

num_crops：指定图像裁剪的数量,用于指定从单张输入图像中生成多个裁剪（crops）的数量。裁剪是指从原始图像中提取局部区域，通常是为了增强模型对图像细节的感知能力或提高鲁棒性。
resize_size：指定图像调整大小的目标尺寸,用于指定图像在预处理阶段被调整到的目标尺寸。目标尺寸通常以像素（pixels）为单位，表示图像的宽度和高度。

使用场景

  1. 调整图像裁剪数量：图像处理任务中，可以通过增加裁剪数量来提高模型对图像细节的感知能力。
  2. 调整图像尺寸：如果模型对输入图像的分辨率有特定要求，可以通过设置 resize_size 来调整图像的大小。
  3. 优化视频帧处理：在处理视频输入时，可以通过调整帧采样率或其他参数来优化性能。
  4. 调试和对比性能：以通过调整 --mm-processor-kwargs 的值，对比不同配置下的性能表现（如吞吐量、延迟和资源利用率），从而找到最优的配置。

3、--disable-mm-preprocessor-cache

说明

用于控制是否禁用多模态预处理器的缓存功能,缓存机制可以显著提高对重复输入（如相同的图像或视频）的处理速度，避免了重复的预处理操作,禁用缓存可能会导致每次输入都需要重新进行预处理，从而增加计算开销,官方文档明确指出，禁用缓存功能是 不推荐 的，除非有特殊需求（如调试或测试）。

默认值

默认情况下，该参数值为 False，即启用多模态预处理器的缓存功能。

参数选项

# 启用缓存（默认行为）。
vllm serve \
  --model /path/to/model

# 禁用缓存（不推荐）。
vllm serve \
  --model /path/to/model \
  --disable-mm-preprocessor-cache

使用场景

调试和测试:需要验证多模态预处理器的行为，或者测试缓存机制对性能的影响，可以临时禁用缓存。
避免缓存污染:输入数据频繁变化且重复率极低，启用缓存可能会浪费内存资源。此时可以禁用缓存以节省内存。
对比性能:可以通过启用或禁用缓存，对比不同配置下的性能表现（如吞吐量、延迟和内存使用），从而评估缓存机制的实际效果。

API/服务配置

1、--served-model-name

说明

定义模型在 API 中的名称（或名称列表），用于 API 请求、响应以及 Prometheus 指标标签。

默认值

默认值为 --model 参数中指定的模型名称。

参数选项

--served-model-name <NAME>

使用场景

适用于需要为模型设置别名、支持多名称调用或统一监控标签的场景。

2、--preemption-mode

说明

用于控制模型推理过程中抢占的处理方式。通过合理设置该参数，可以在显存资源有限的情况下优化资源利用率，适用于不同硬件资源和负载场景下的性能优化需求。

  1. --preemption-mode 提供了两种抢占模式：
  • recompute ：通过重新计算（Recomputation）来处理抢占。
    当显存不足时，丢弃当前的部分计算结果，并在需要时重新计算这些结果。

特点：显存占用较低，但可能会增加计算开销。

  • swap ：通过块交换（Block Swapping）来处理抢占。
    当显存不足时，将部分计算数据从 GPU 显存交换到 CPU 内存或磁盘存储中。

特点：计算开销较低，但可能会增加 I/O 开销和延迟。

默认值

默认值：无（需显式设置） 在默认情况下，vLLM 不会自动选择抢占模式。如果需要启用抢占功能，则必须显式设置该参数。

参数选项

--preemption-mode 是一个字符串类型的参数，支持以下两种选项：

  • recompute ：
    通过重新计算来处理抢占。

适用于显存资源有限但计算资源充足的场景。

  • swap ：
    通过块交换来处理抢占。

适用于显存资源有限但 I/O 性能较高的场景。

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --preemption-mode recompute \
    --gpu-memory-utilization 0.8 \
    --port 8000

--preemption-mode recompute :设置抢占模式为 recompute，通过重新计算来处理显存不足的问题。

使用场景

  1. 显存资源有限的场景:在显存资源有限的情况下，可以通过设置 --preemption-mode=recompute 或 --preemption-mode=swap 来释放显存资源，从而支持更大的模型或更高的并发请求。
  2. 高性能计算场景:在计算资源充足但显存不足的情况下，可以选择 recompute 模式，利用额外的计算能力来补偿显存不足的问题。
  3. 高 I/O 性能场景:在 I/O 性能较高（如高速 SSD 或大容量内存）但显存不足的情况下，可以选择 swap 模式，将部分数据交换到 CPU 内存或磁盘中。

3、--api-key

说明

用于设置访问模型推理服务所需的 API 密钥。通过合理设置该参数，可以限制对服务的访问权限，适用于生产环境中的安全性需求。
API 密钥是一种身份验证机制，用于限制对服务的访问权限，确保只有持有有效密钥的客户端能够调用推理接口。

  • API 密钥的作用 ：
    在生产环境中，API 密钥可以防止未经授权的访问，保护模型服务的安全性。

客户端在发送请求时需要在请求头或参数中提供正确的 API 密钥，否则请求会被拒绝。

默认值

默认值：无（需显式设置） 在默认情况下，vLLM 不会启用 API 密钥验证。如果需要启用该功能，则必须显式设置该参数。

参数选项

--api-key 是一个字符串类型的参数，支持以下格式：

  • 单个密钥 ：
    直接指定一个字符串作为 API 密钥，例如 token-abc123。
  • 多个密钥 ：
    如果需要支持多个密钥，可以通过逗号分隔的方式指定多个值，例如 token-abc123,token-def456。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --api-key token-abc123 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--api-key token-abc123 :启用 API 密钥验证，并将密钥设置为 token-abc123。

使用场景

  1. 生产环境安全:在生产环境中部署模型服务时，可以通过设置 API 密钥限制访问权限，防止未经授权的用户调用服务。
  2. 多用户管理:如果需要为不同的用户或团队分配独立的 API 密钥，可以通过指定多个密钥实现。

其他

1、--guided-decoding-backend

说明

用于指定 Guided Decoding(引导解码)的后端引擎。引导解码是一种技术，引导解码通过外部工具或库来限制模型的输出，使其符合特定的格式或规则(如 JSON Schema 或正则表达式)

默认值

xgrammar

参数选项

outlines

outlines 是一个开源库,支持基于 JSON Schema、正则表达式等约束的解码

优点:
灵活性高，支持多种约束类型

缺点:
性能可能不如其他专用工具(如 xgrammar)

lm-format-enforcer

lm-format-enforcer 是一个专注于格式强制的工具，能够高效地将模型输出限制为特定格式。

优点:
高效且易于使用

缺点:
功能相对简单，不适合复杂的约束

xgrammar

xgrammar 是一个高性能的语法解析工具,支持基于语法规则的解码,在处理复杂的语法规则时表现出色,同时保持较高的性能

优点:
性能优越，适合大规模应用场景

缺点:
对复杂约束的支持不如 outlines 灵活

使用场景

  1. 默认选择
    没有特殊需求，可以直接使用默认值 xgrammar,在大多数场景下都能提供良好的性能和功能
  2. 复杂约束
    需要复杂的约束(如嵌套的 JSON Schema 或正则表达式),可以使用 outlines
  3. 简单格式强制
    需要快速生成符合特定格式的输出(如 JSON、XML 等),可以使用 lm-format-enforcer
  4. 高性能需求
    需要高性能的引导解码(如实时生成符合语法规则的文本),可以使用 xgrammar

2、--seed

说明

用于设置随机种子（Random Seed）。

  1. 控制随机性 ：
    设置随机种子后，所有依赖随机数的操作（如权重初始化、数据打乱、采样等）都会产生相同的结果。
  2. 提高可重复性 ：
    在科学研究和工程实践中，可重复性是一个关键要求。通过设置随机种子，可以确保相同的输入总是产生相同的输出。
  3. 灵活性 ：
    如果不设置随机种子（或设置为不同的值），每次运行可能会产生不同的结果，适合探索性的任务。

默认值

如果未明确指定，默认值为 0，表示使用固定的随机种子。

参数选项

# 设置随机种子为 42
vllm serve \
  --seed=42

使用场景

  1. 实验结果复现。
  2. 调试和验证。
  3. 探索性任务。

3、--enforce-eager

说明

用于控制是否强制使用 PyTorch 的 eager 模式 （动态图模式）。
PyTorch 提供两种主要的执行模式：

  • Eager Mode（动态图模式） ：逐行执行代码，灵活性高，但性能可能较低。
  • CUDA Graph（静态图模式） ：将计算图编译为静态图，提高性能，但灵活性较低。
    默认情况下，推理框架（如 vLLM）会根据任务需求在 eager 模式 和 CUDA Graph 之间切换，以实现性能和灵活性的最佳平衡。

如果设置 --enforce-eager=True，则始终使用 eager 模式，禁用 CUDA Graph。

默认值

默认值为 False，即允许混合使用 eager 模式和 CUDA Graph。

参数选项

# 强制使用 eager 模式
vllm serve \
  --enforce-eager=True

# 允许混合使用 eager 模式和 CUDA Graph
vllm serve \
  --enforce-eager=False

使用场景

  1. 动态输入长度（如对话生成、文档摘要）。
  2. 高性能推理（如批量生成任务）。
  3. 调试和验证。

4、--typical-acceptance-sampler-posterior-threshold

说明

用于设置 TypicalAcceptanceSampler 方法中 token 的后验概率最低接受阈值。默认值为 0.09。通过调整该阈值，可以在推理速度和输出质量之间取得最佳平衡，适用于不同场景下的性能优化需求。

  1. 后验概率阈值 ：
    在推测解码（Speculative Decoding）过程中，草稿模型生成的候选 token 需要由主模型验证其后验概率。只有当候选 token 的后验概率高于该阈值时，才会被接受。
  2. 控制接受率 ：
    通过调整该阈值，可以动态控制草稿 token 的接受率。较低的阈值会提高接受率，从而加速推理，但可能会降低输出质量；较高的阈值会降低接受率，从而提高输出质量，但可能减慢推理速度。

默认值

默认值：0.09 默认情况下，只有后验概率大于等于 0.09 的 token 才会被接受。

参数选项

--typical-acceptance-sampler-posterior-threshold 是一个浮点数类型的参数，理论上可以设置为 [0, 1] 范围内的任意值。实际使用中，常见的选项包括：

  • 小值（如 0.05、0.09） ：适用于对推理速度要求较高、允许一定质量损失的场景。
  • 中值（如 0.1、0.2） ：适用于平衡推理速度和输出质量的场景。
  • 大值（如 0.3+） ：适用于对输出质量要求较高、允许推理速度较慢的场景。
    需要注意的是，设置的值应根据实际需求进行调整，过低的值可能导致输出质量下降，而过高的值可能导致推理效率降低。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --spec-decoding-acceptance-method typical_acceptance_sampler \
    --typical-acceptance-sampler-posterior-threshold 0.07 \
    --gpu-memory-utilization 0.8 \
    --port 8000

--typical-acceptance-sampler-posterior-threshold 0.07 :设置后验概率阈值为 0.07，以提高草稿 token 的接受率。

使用场景

  1. 高性能推理场景:在需要快速生成文本的场景中（如在线聊天机器人、实时翻译等），可以通过降低后验概率阈值（如设置为 0.05）来提高草稿 token 的接受率，从而加速推理。
  2. 高质量输出场景:在对输出质量要求较高的场景中（如内容创作、专业翻译等），可以通过提高后验概率阈值（如设置为 0.2）来降低草稿 token 的接受率，从而确保输出质量。

5、--typical-acceptance-sampler-posterior-alpha

说明

用于设置 TypicalAcceptanceSampler 方法中基于熵的 token 接受阈值的缩放因子。默认值为 0.3，通常为后验概率阈值的平方根。通过调整该参数，可以在推理速度和输出质量之间取得最佳平衡，适用于不同场景下的性能优化需求。

  1. 基于熵的阈值调整 ：

    1. 在推测解码（Speculative Decoding）过程中，草稿模型生成的候选 token 的接受与否不仅依赖于后验概率，还可能通过熵来动态调整接受标准。
      --typical-acceptance-sampler-posterior-alpha 是一个缩放因子，用于调整基于熵的阈值。它与后验概率阈值（--typical-acceptance-sampler-posterior-threshold）结合使用，进一步控制 token 的接受率。

  2. 默认关系 ：

    1. 默认情况下，--typical-acceptance-sampler-posterior-alpha 的值通常为 sqrt(--typical-acceptance-sampler-posterior-threshold)。例如，如果后验概率阈值为 0.09，则 alpha 的默认值为 sqrt(0.09) = 0.3。

默认值

默认值：0.3 默认情况下，基于熵的阈值会被缩放为后验概率阈值的平方根。

参数选项

--typical-acceptance-sampler-posterior-alpha 是一个浮点数类型的参数，理论上可以设置为 [0, 1] 范围内的任意值。实际使用中，常见的选项包括：

  • 小值（如 0.1、0.2） ：适用于对推理速度要求较高、允许一定质量损失的场景。
  • 中值（如 0.3、0.4） ：适用于平衡推理速度和输出质量的场景。
  • 大值（如 0.5+） ：适用于对输出质量要求较高、允许推理速度较慢的场景。
    需要注意的是，alpha 的值应与后验概率阈值（--typical-acceptance-sampler-posterior-threshold）协同调整，以确保两者的关系合理。

使用场景

  1. 高性能推理场景:需要快速生成文本的场景中（如在线聊天机器人、实时翻译等），可以通过降低 alpha 值（如设置为 0.2）来放宽基于熵的阈值，从而提高草稿 token 的接受率，加速推理。
  2. 高质量输出场景:在对输出质量要求较高的场景中（如内容创作、专业翻译等），可以通过提高 alpha 值（如设置为 0.5）来收紧基于熵的阈值，从而降低草稿 token 的接受率，确保输出质量。
  3. 实验与调优:在模型部署初期，可以通过对比不同 alpha 值的效果，找到推理速度和输出质量的最佳平衡点。

6、--override-pooler-config

说明

用于覆盖或设置池化模型的池化方法配置。通过合理设置该参数，可以生成适配特定任务需求的句子嵌入，适用于语义搜索、文本分类等场景下的性能优化需求。

  • 池化配置的作用 ：
    池化模型通常用于生成句子级别的嵌入（sentence embeddings），例如在文本分类、语义搜索等任务中。通过 --override-pooler-config，可以自定义池化方法以适配特定任务需求。
  • JSON 格式 ：
    该参数接受一个 JSON 字符串，解析后会作为字典传递给池化模型的配置接口。

默认值

默认值：无（需显式设置） 在默认情况下，池化模型会使用其默认的池化方法和配置。如果需要自定义池化行为，则必须显式设置该参数。

参数选项

--override-pooler-config 是一个字符串类型的参数，必须是有效的 JSON 格式。常见的配置选项包括：

  • pooling_type ：
    指定池化方法的类型。常见的池化方法包括：

"mean"：取输入序列的平均值。
"max"：取输入序列的最大值。
"cls"：直接使用 [CLS] token 的表示（适用于 BERT 等模型）。
示例：{"pooling_type": "mean"}

  • normalize ：
    是否对池化结果进行归一化（L2 归一化）。设置为 true 时会对输出向量进行归一化，使其具有单位长度。

示例：{"normalize": true}

vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --override-pooler-config '{"pooling_type": "mean", "normalize": true}' \
    --gpu-memory-utilization 0.8 \
    --port 8000

--override-pooler-config '{"pooling_type": "mean", "normalize": true}' :覆盖池化模型的默认配置，使用平均池化并启用归一化。

使用场景

  1. 语义搜索:在语义搜索任务中，通常需要生成高质量的句子嵌入。可以通过设置 pooling_type="mean" 和 normalize=true 来生成归一化的平均池化嵌入。
  2. 文本分类:在文本分类任务中，可以直接使用 [CLS] token 的表示作为句子嵌入。可以通过设置 pooling_type="cls" 来实现。
  3. 性能优化:在需要减少计算开销的场景中，可以选择更简单的池化方法（如 "max"），从而提高推理速度。

7、--compilation-config, -o

说明

用于配置模型的 Torch 编译优化。通过合理设置该参数，可以在推理性能和资源利用率之间取得最佳平衡，适用于不同场景下的性能优化需求。

  1. Torch 编译的作用 ：

    • torch.compile 是 PyTorch 提供的一种性能优化工具，通过对模型进行静态图优化、算子融合等技术来加速推理过程,该参数允许用户选择预定义的优化级别，或者通过 JSON 格式传递完整的编译配置。

  2. 优化级别的解释 ：
    当参数值为数字（如 0, 1, 2, 3）时，表示预定义的优化级别：

    • 0 ：默认级别，不启用任何优化。
    • 1 和 2 ：内部测试级别，通常不推荐用于生产环境。
    • 3 ：推荐的生产级别，提供最佳性能优化。

当参数值为 JSON 字符串时，表示自定义的完整编译配置。

默认值

默认值：0 在默认情况下，模型不会应用任何 Torch 编译优化。如果需要启用优化，则必须显式设置该参数。

参数选项

--compilation-config 是一个字符串类型的参数，支持以下两种格式：

  • 数字格式 ：
    直接指定优化级别，例如 0, 1, 2, 3。
  • JSON 格式 ：
{"mode": "reduce-overhead", "backend": "inductor"}

-o 是该参数的简写形式，支持直接指定优化级别（如 -o3）。

使用场景

  1. 高性能推理:在生产环境中，可以通过设置优化级别为 3 来启用推荐的性能优化。
  2. 调试与测试:在开发或调试阶段，可以选择较低的优化级别（如 0 或 1），以便快速验证模型行为。
  3. 自定义编译配置:如果需要更精细地控制编译行为，可以通过 JSON 格式传递完整的配置。

8、--worker-cls

说明

用于指定分布式推理中使用的工作线程类。通过合理设置该参数，可以优化性能或适配特定的硬件环境，适用于不同场景下的推理任务需求。
工作线程类是负责执行模型推理任务的核心组件，不同的实现可能针对特定的硬件环境或任务需求进行了优化。

  • 工作线程类的作用 ：
    在分布式推理场景中，工作线程类负责管理 GPU 资源、调度推理任务以及处理输入输出数据。通过选择合适的工作线程类，可以优化性能或适配特定的硬件配置。
  • 默认值 auto ：
    如果未显式指定工作线程类，vLLM 会根据当前的硬件环境和任务需求自动选择一个合适的工作线程类。

默认值

默认值："auto" 在默认情况下，vLLM 会根据运行时的上下文（如硬件类型、模型规模等）自动选择最佳的工作线程类。

参数选项

  1. --worker-cls 是一个字符串类型的参数，支持以下两种格式：

    • 预定义类名 ：
      直接指定一个预定义的工作线程类名称，例如 "gpu_worker" 或 "cpu_worker"。
    • 自定义类路径 ：
      如果需要使用自定义的工作线程类，可以通过模块路径指定，例如 "my_module.MyCustomWorker"。

  2. 常见的预定义工作线程类包括：

    • gpu_worker ：
      针对 GPU 环境优化的工作线程类，适用于大多数 GPU 推理任务。
    • cpu_worker ：
      针对 CPU 环境优化的工作线程类，适用于没有 GPU 的场景。
vllm serve \
    meta-llama/Llama-2-7b-chat-hf \
    --draft-model tiny-llama/tiny-llama-1b-chat-v0 \
    --num-speculative-tokens 8 \
    --worker-cls "gpu_worker" \
    --gpu-memory-utilization 0.8 \
    --port 8000

--worker-cls "gpu_worker" :明确指定使用 gpu_worker 类以优化 GPU 推理性能。

使用场景

  1. GPU 推理:在配备 GPU 的服务器上运行推理任务时，可以选择 gpu_worker 类以充分利用 GPU 性能。
  2. CPU 推理:在没有 GPU 的环境中运行推理任务时，可以选择 cpu_worker 类以适配 CPU 环境。
  3. 自定义硬件支持:如果使用了特定的硬件加速器（如 AWS Neuron 或 Google TPU），可以通过指定自定义工作线程类来适配这些硬件。
最后修改：2025 年 03 月 05 日
© 禁止转载
如果觉得我的文章对你有用，请随意赞赏