vLLM - LLM 类初始化参数

vLLM - LLM 类初始化参数

flyfish

一、模型与分词器配置

控制模型加载路径、分词器设置及远程代码信任策略。

参数名	说明	默认值	注意事项
model	HuggingFace Transformers 模型的名称或路径。	无（必传）	支持本地路径或 HuggingFace Hub 模型名（如 gpt2）。
tokenizer	HuggingFace Transformers 分词器的名称或路径。	与 model 相同	若模型与分词器不同，需显式指定（如 tokenizer="gpt2"）。
tokenizer_mode	分词器模式： - auto：优先使用快速分词器（若可用） - slow：强制使用慢速分词器	auto	快速分词器基于 Rust，性能更优，但部分模型仅支持慢速分词器。
skip_tokenizer_init	是否跳过分词器初始化（若已预处理 prompt 为 token IDs，可设为 True）。	False	输入需提供 prompt_token_ids 而非文本，用于性能优化。
trust_remote_code	是否信任远程代码（如 HuggingFace Hub 上的自定义模型实现）。	False	启用时需谨慎，可能存在安全风险（如恶意代码）。
revision	模型版本（分支名、标签名或提交 ID）。	None（默认版本）	用于指定特定模型版本（如 revision="main"）。
tokenizer_revision	分词器版本（同上）。	None	当分词器与模型版本不一致时使用。

二、安全性与本地资源访问

控制模型加载和 API 请求的安全策略，限制本地文件访问。

参数名	说明	默认值	注意事项
allowed_local_media_path	允许 API 请求读取的本地媒体路径（如图像、视频）。	None	启用后存在安全风险，仅在可信环境中使用（如内部服务）。
hf_token	HuggingFace API 访问令牌。 - True：使用本地存储的令牌（~/.huggingface） - 字符串：自定义令牌	None	用于访问私有模型或需要授权的资源。

三、分布式与并行计算

控制模型在多 GPU 上的并行方式及资源分配。

参数名	说明	默认值	注意事项
tensor_parallel_size	张量并行的 GPU 数量（模型分片数）。	1	需 ≥ 1 且 ≤ 可用 GPU 总数，推荐值为可用 GPU 数（如 4 卡则设为 4）。
disable_custom_all_reduce	禁用自定义 AllReduce 优化（影响多 GPU 通信效率）。	False	仅在特定 GPU 架构或通信库不兼容时启用。

四、模型精度与量化

控制模型权重的数据类型及量化策略，平衡精度与内存占用。

参数名	说明	默认值	注意事项
dtype	模型权重和激活函数的数据类型： - float32：全精度（最高内存） - float16：半精度（默认） - bfloat16：Brain Floating Point - auto：自动根据模型配置选择	auto	auto 通常选择 float16，除非模型明确支持 bfloat16。
quantization	模型量化方法： - awq：激活感知权重量化 - gptq：GPTQ 量化 - fp8：8 位浮点量化（实验性） - None：不量化	None	量化可显著降低内存占用，但可能损失精度（如 awq 通常保持 99% 以上精度）。

五、内存与性能优化

控制 GPU/CPU 内存分配、交换空间及执行模式，提升吞吐量或降低延迟。

参数名	说明	默认值	注意事项
gpu_memory_utilization	GPU 内存使用率（0~1），用于模型权重、激活函数和 KV 缓存。	0.9	过高可能导致 OOM，过低会浪费 GPU 资源；长序列生成时建议降低（如 0.8）。
swap_space	每个 GPU 对应的 CPU 交换空间大小（GiB），用于存储 best_of > 1 的中间状态。	4	若所有请求 best_of=1，可设为 0；否则过小可能导致 OOM。
cpu_offload_gb	用于卸载模型权重的 CPU 内存大小（GiB）。	0	增加 GPU 可用内存，但会降低推理速度（每次前向传播需 CPU-GPU 数据传输）。
enforce_eager	是否强制使用 eager 执行模式（禁用 CUDA Graph）。	False	CUDA Graph 可提升吞吐量，但动态序列长度场景可能降级，此时建议设为 True。
max_seq_len_to_capture	CUDA Graph 支持的最大序列长度。超过此长度则回退到 eager 模式。	2048	长序列（如 8k+）生成时需增大此值，否则频繁切换模式会降低性能。
disable_async_output_proc	禁用异步输出处理（可能降低性能）。	False	仅在调试或特定场景下启用。
compilation_config	编译优化配置： - 整数：优化级别（0~3） - 字典：详细配置参数	None	高级优化，如 {"level": 3, "mode": "max-performance"}。

六、随机数生成与可复现性

控制采样过程中的随机种子，确保结果可复现。

参数名	说明	默认值	注意事项
seed	随机数生成器的种子。	None	设置后，相同输入和参数将生成确定性结果（仅在 temperature > 0 时有效）。

七、HuggingFace 配置覆盖

自定义 HuggingFace 模型配置的参数或处理函数。

参数名	说明	默认值	注意事项
hf_overrides	HuggingFace 模型配置的覆盖参数： - 字典：直接覆盖配置字段（如 {"max_position_embeddings": 8192}） - 函数：自定义修改配置的函数	None	用于修改模型原生配置（如扩展最大序列长度）。

八、其他参数

通用配置参数，传递给底层 EngineArgs 类。

参数名	说明	默认值	注意事项
**kwargs	传递给 vllm.EngineArgs 的其他参数（如 log_stats=True）。	-	具体参数见 EngineArgs 文档，用于高级配置（如日志统计、KV 缓存策略等）。

最佳实践

1. 多 GPU 部署：

   • 设置 tensor_parallel_size 为可用 GPU 数，gpu_memory_utilization=0.8~0.9，平衡吞吐量与稳定性。

2. 长序列生成：

   • 增大 max_seq_len_to_capture（如 8192），降低 gpu_memory_utilization（如 0.7），避免频繁切换执行模式。

3. 内存优化：

   • 使用 quantization="awq" 或 gptq 降低模型内存占用，结合 cpu_offload_gb 进一步扩展可用空间。

4. 可复现性：

   • 设置 seed 为固定值，确保相同输入生成相同结果（需配合 temperature > 0）。

vLLM 处理多模态输入参数用法说明

from transformers import AutoProcessor
from vllm import LLM, SamplingParams
from qwen_vl_utils import process_vision_infoMODEL_PATH = "Qwen/Qwen2.5-VL-7B-Instruct"# 初始化LLM模型，设置多模态输入限制（每个提示最多10个图像和10个视频）
llm = LLM(model=MODEL_PATH,limit_mm_per_prompt={"image": 10, "video": 10},
)# 设置采样参数，控制文本生成的方式
sampling_params = SamplingParams(temperature=0.1,         # 温度参数，控制随机性，值越低生成越确定性top_p=0.001,           # 核采样概率阈值，限制候选词范围repetition_penalty=1.05, # 重复惩罚因子，大于1时抑制重复生成max_tokens=256,        # 最大生成长度stop_token_ids=[],     # 停止生成的token ID列表
)# 构建图像输入消息（使用本地文件）
image_messages = [{"role": "system", "content": "You are a helpful assistant."},{"role": "user","content": [{"type": "image","image": "path/to/your/local/image.jpg",  # 替换为本地图像路径"min_pixels": 224 * 224,"max_pixels": 1280 * 28 * 28,},{"type": "text", "text": "What is the text in the illustrate?"},],},
]# 构建视频输入消息（使用本地文件）
video_messages = [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": [{"type": "text", "text": "请用表格总结一下视频中的商品特点"},{"type": "video", "video": "path/to/your/local/video.mp4",  # 替换为本地视频路径"total_pixels": 20480 * 28 * 28, "min_pixels": 16 * 28 * 28}]},
]# 选择使用视频消息作为示例
messages = video_messages# 加载模型处理器
processor = AutoProcessor.from_pretrained(MODEL_PATH)# 构建聊天模板，将消息转换为模型可接受的格式
prompt = processor.apply_chat_template(messages,tokenize=False,add_generation_prompt=True,
)# 处理视觉信息，提取图像和视频输入
image_inputs, video_inputs, video_kwargs = process_vision_info(messages, return_video_kwargs=True)# 准备多模态输入数据
mm_data = {}
if image_inputs is not None:mm_data["image"] = image_inputs
if video_inputs is not None:mm_data["video"] = video_inputs# 构建LLM输入
llm_inputs = {"prompt": prompt,"multi_modal_data": mm_data,# FPS等视频处理参数将从video_kwargs中获取"mm_processor_kwargs": video_kwargs,
}# 生成回答
outputs = llm.generate([llm_inputs], sampling_params=sampling_params)
generated_text = outputs[0].outputs[0].textprint(generated_text)

1. LLM初始化参数

   • model: 指定模型路径或名称，如"Qwen/Qwen2.5-VL-7B-Instruct"
   • limit_mm_per_prompt: 限制每个提示中可以包含的多模态输入数量，格式为字典，如{"image": 10, "video": 10}

2. SamplingParams参数

   • temperature: 控制生成文本的随机性。较低的值(如0.1)使生成更确定性，适合事实性任务；较高的值(如1.0)增加随机性，适合创造性任务。
   • top_p: 核采样参数，只考虑概率总和达到top_p的最小词元集合，减少低概率词元的生成。
   • repetition_penalty: 重复惩罚因子，大于1的值会抑制重复生成相同的内容，有助于避免模型重复相同的短语。
   • max_tokens: 限制生成的最大token数量，防止生成过长的文本。
   • stop_token_ids: 指定停止生成的token ID列表，当遇到这些token时，模型将停止生成。