vLLM API Server参数调优全解析：解码、并行、缓存、调度、调试与Tool Calling/Reasoning/推测解码配置

vLLM 推理框架—参数调优方案

vLLM API server version 0.8.5

INFO 04-29 01:18:54 [api_server.py:1044] args: Namespace(host=None, port=8995, uvicorn_log_level='info', disable_uvicorn_access_log=False, allow_credentials=False, allowed_origins=[''], allowed_methods=[''], allowed_headers=['*'], api_key='<YOUR_API_KEY>', lora_modules=None, prompt_adapters=None, chat_template=None, chat_template_content_format='auto', response_role='assistant', ssl_keyfile=None, ssl_certfile=None, ssl_ca_certs=None, enable_ssl_refresh=False, ssl_cert_reqs=0, root_path=None, middleware=[], return_tokens_as_token_ids=False, disable_frontend_multiprocessing=False, enable_request_id_headers=False, enable_auto_tool_choice=False, tool_call_parser=None, tool_parser_plugin='', model='/models/Qwen3-235B-A22B', task='auto', tokenizer=None, hf_config_path=None, skip_tokenizer_init=False, revision=None, code_revision=None, tokenizer_revision=None, tokenizer_mode='auto', trust_remote_code=False, allowed_local_media_path=None, load_format='auto', download_dir=None, model_loader_extra_config={}, use_tqdm_on_load=True, config_format=<ConfigFormat.AUTO: 'auto'>, dtype='auto', max_model_len=32000, guided_decoding_backend='auto', reasoning_parser='deepseek_r1', logits_processor_pattern=None, model_impl='auto', distributed_executor_backend=None, pipeline_parallel_size=1, tensor_parallel_size=8, data_parallel_size=1, enable_expert_parallel=False, max_parallel_loading_workers=None, ray_workers_use_nsight=False, disable_custom_all_reduce=False, block_size=None, gpu_memory_utilization=0.9, swap_space=4, kv_cache_dtype='auto', num_gpu_blocks_override=None, enable_prefix_caching=None, prefix_caching_hash_algo='builtin', cpu_offload_gb=0, calculate_kv_scales=False, disable_sliding_window=False, use_v2_block_manager=True, seed=None, max_logprobs=20, disable_log_stats=False, quantization=None, rope_scaling=None, rope_theta=None, hf_token=None, hf_overrides=None, enforce_eager=False, max_seq_len_to_capture=8192, tokenizer_pool_size=0, tokenizer_pool_type='ray', tokenizer_pool_extra_config={}, limit_mm_per_prompt={}, mm_processor_kwargs=None, disable_mm_preprocessor_cache=False, enable_lora=None, enable_lora_bias=False, max_loras=1, max_lora_rank=16, lora_extra_vocab_size=256, lora_dtype='auto', long_lora_scaling_factors=None, max_cpu_loras=None, fully_sharded_loras=False, enable_prompt_adapter=None, max_prompt_adapters=1, max_prompt_adapter_token=0, device='auto', speculative_config=None, ignore_patterns=[], served_model_name=['qwen3-235b-a22b'], qlora_adapter_name_or_path=None, show_hidden_metrics_for_version=None, otlp_traces_endpoint=None, collect_detailed_traces=None, disable_async_output_proc=False, max_num_batched_tokens=None, max_num_seqs=None, max_num_partial_prefills=1, max_long_partial_prefills=1, long_prefill_token_threshold=0, num_lookahead_slots=0, scheduler_delay_factor=0.0, preemption_mode=None, num_scheduler_steps=1, multi_step_stream_outputs=True, scheduling_policy='fcfs', enable_chunked_prefill=None, disable_chunked_mm_input=False, scheduler_cls='vllm.core.scheduler.Scheduler', override_neuron_config=None, override_pooler_config=None, compilation_config=None, kv_transfer_config=None, worker_cls='auto', worker_extension_cls='', generation_config='auto', override_generation_config=None, enable_sleep_mode=False, additional_config=None, enable_reasoning=True, disable_cascade_attn=False, disable_log_requests=False, max_log_len=None, disable_fastapi_docs=False, enable_prompt_tokens_details=False, enable_server_load_tracking=False)

• This model supports multiple tasks: {‘embed’, ‘classify’, ‘generate’, ‘reward’, ‘score’}. Defaulting to ‘generate’.
• Defaulting to use mp for distributed inference
• Chunked prefill is enabled with max_num_batched_tokens=8192.

INFO 04-29 01:19:11 [core.py:58] Initializing a V1 LLM engine (v0.8.5) with config: model='/models/Qwen3-235B-A22B', speculative_config=None, tokenizer='/models/Qwen3-235B-A22B', skip_tokenizer_init=False, tokenizer_mode=auto, revision=None, override_neuron_config=None, tokenizer_revision=None, trust_remote_code=False, dtype=torch.bfloat16, max_seq_len=32000, download_dir=None, load_format=LoadFormat.AUTO, tensor_parallel_size=8, pipeline_parallel_size=1, disable_custom_all_reduce=False, quantization=None, enforce_eager=False, kv_cache_dtype=auto,  device_config=cuda, decoding_config=DecodingConfig(guided_decoding_backend='auto', reasoning_backend='deepseek_r1'), observability_config=ObservabilityConfig(show_hidden_metrics=False, otlp_traces_endpoint=None, collect_model_forward_time=False, collect_model_execute_time=False), seed=None, served_model_name=qwen3-235b-a22b, num_scheduler_steps=1, multi_step_stream_outputs=True, enable_prefix_caching=True, chunked_prefill_enabled=True, use_async_output_proc=True, disable_mm_preprocessor_cache=False, mm_processor_kwargs=None, pooler_config=None, compilation_config={"level":3,"custom_ops":["none"],"splitting_ops":["vllm.unified_attention","vllm.unified_attention_with_output"],"use_inductor":true,"compile_sizes":[],"use_cudagraph":true,"cudagraph_num_of_warmups":1,"cudagraph_capture_sizes":[512,504,496,488,480,472,464,456,448,440,432,424,416,408,400,392,384,376,368,360,352,344,336,328,320,312,304,296,288,280,272,264,256,248,240,232,224,216,208,200,192,184,176,168,160,152,144,136,128,120,112,104,96,88,80,72,64,56,48,40,32,24,16,8,4,2,1],"max_capture_size":512}

• vLLM is using nccl==2.21.5
• Using Flash Attention backend on V1 engine.
• Using FlashInfer for top-p & top-k sampling.
• Using default completion sampling params from model: {‘temperature’: 0.6, ‘top_k’: 20, ‘top_p’: 0.95}

默认参数

• –model
  • 要使用的 huggingface 模型的名称或路径。
• –dtype
  • auto, half, float16, bfloat16, float, float32。默认值：auto。
• –max-model-len
  • 模型上下文长度。如果未指定，将从模型配置中自动导出。
• –served-model-name
  • API 中使用的名称。如果未指定，模型名称将与 –model 参数相同。
• –seed
  • 随机种子。
• –enforce-eager
  • 始终使用 eager 模式 PyTorch。如果为 False，将使用 eager 模式和 CUDA 图形混合模式，以获得最高性能和灵活性。默认值：False。
• –use-v2-block-manager
  • [已弃用] 区块管理器 v1 已被移除，SelfAttnBlockSpaceManager（即区块管理器 v2）现已成为默认设置。默认值：True
• –disable-mm-preprocessor-cache
  • 禁用异步输出处理。这可能会降低性能。
• –enable-reasoning
  • 是否为模型启用 reasoning_content。启用后，模型将能够生成推理内容。默认值：False
• –enable-sleep-mode
  • 启用睡眠模式。(仅支持 cuda 平台），牺牲一定程度的性能，来优化功耗。
• –compilation-config
  • 模型的 torch.compile 配置。级别0是默认级别，没有任何优化。1级和第2级仅用于内部测试。第三级是推荐的生产水平。
• –kv-transfer-config
  • 分布式 KV 缓存传输的配置。为 JSON 字符串格式。默认值：None。
• –quantization, -q
  • 可能的量化方法：aqlm, awq, deepspeedfp, tpu_int8, fp8, ptpc_fp8, fbgemm_fp8, modelopt, nvfp4, marlin, bitblas, gguf, gptq_marlin_24, gptq_marlin, gptq_bitblas, awq_marlin, gptq, compressed-tensors, bitsandbytes, qqq, hqq, experts_int8, neuron_quant, ipex, quark, moe_wna16, torchao, None

解码策略

• –guided-decoding-backend
  • 可能的解码策略，auto, guidance, xgrammar，默认值：auto，将尝试根据请求的详细信息选择一个合适的后端。
• –reasoning-parser
  • 可能的推理解析器：deepseek_r1、granite，为 OpenAI API 格式。需先开启 –enable-reasoning。

并行策略

• –distributed-executor-backend
  • 分布式模型执行方式，可能的值：external_launcher, mp, ray, uni, None，默认值：mp
• –pipeline-parallel-size, -pp
  • 流水线并行，层间并行，对模型不同的 Transformer 层间进行分割。默认值为1。
• –tensor-parallel-size, -tp
  • 张量并行，层内并行，对模型 Transformer 层内进行分割。默认值为1
• –data-parallel-size, -dp
  • 数据并行，默认值为1
• –enable-expert-parallel, –no-enable-expert-parallel
  • 对于 MoE 层，使用专家并行性而不是张量并行性。默认值：False

缓存策略

• –block-size
  • 连续缓存块的大小，CUDA设备上最多为32，默认值：None
• –gpu-memory-utilization
  • GPU显存占用比例，默认0.9
• –swap-space
  • 每个 GPU 的 CPU 交换空间大小（单位：GiB）。默认值：4。
• –enable-prefix-caching, –no-enable-prefix-caching
  • 是否启用前缀缓存。默认情况下为V0禁用。默认为V1启用。
• –cpu-offload-gb
  • 每个 GPU 需要卸载到 CPU 的空间（以 GiB 为单位）。默认值为 0，表示不卸载。

调度策略

• –max-num-batched-tokens
  • 单次迭代中要处理的最大token数。默认值：8192（A100的80GB显存）。如果用户未指定，则将在 EngineArgs.create_engine_config 中根据使用环境。
• –max-num-seqs
  • 单次迭代处理的最大序列数。默认值：256。若减少批处理中并发请求的数量，则需要更少的KV缓存空间。
• –max-num-partial-prefills
  • 对于分块预填充，可同时进行部分预填充的最大序列数。默认值：1。
• –num-scheduler-steps
  • 每次调度程序调用的最大前移步数。默认值：1。
• –multi-step-stream-outputs, –no-multi-step-stream-outputs
  • 如果为 False，则多步骤将在所有步骤结束时流式输出。默认值：True
• –scheduling-policy
  • 可能的调度策略，fcfs, priority，默认值：fcfs（first come first served）
• –enable-chunked-prefill, –no-enable-chunked-prefill
  • 如果为 True，则可以根据剩余的 max_num_batched_tokens 对预填充请求进行分块。启用分块预填充后，策略将改为优先处理解码请求。在调度任何预填充之前，它会先将所有待处理的解码请求批量处理。

调试策略

如果其他策略无法解决问题，很可能是 vLLM 实例卡在了某个地方。你可以使用以下环境变量来帮助调试问题：

• export VLLM_LOGGING_LEVEL=DEBUG，打开更多日志记录
• export CUDA_LAUNCH_BLOCKING=1，确定是哪个 CUDA 内核导致了问题。
• export NCCL_DEBUG=TRACE，为 NCCL 打开更多日志记录。
• export VLLM_TRACE_FUNCTION=1，记录所有函数调用，以便在日志文件中进行检查，从而确定哪个函数崩溃或挂起。

Tool Calling

• –enable-auto-tool-choice
  • 自动工具选择。告诉 vLLM，您希望让模型在它认为合适时生成自己的工具调用。
• –tool-call-parser
  • 可选，选择要使用的工具解析器，也可以在 –tool-parser-plugin 中注册自己的工具解析器。
  • –tool-call-parser hermes
  • –tool-call-parser llama4_json examples/tool_chat_template_llama4_json.jinja
  • –tool-call-parser granite-20b-fc –chat-template examples/tool_chat_template_granite_20b_fc.jinja
  • –tool-call-parser jamba
• –tool-parser-plugin
  • 可选，工具解析器插件，用于将用户定义的工具解析器注册到VLLM中，可以在-tool-call-parser中指定注册的工具解析器名称。
  • –tool-parser-plugin <absolute path of the plugin file>
• –chat-template
  • 可选择自动选择工具。
  • –tool-call-parser mistral –chat-template examples/tool_chat_template_mistral_parallel.jinja
  • –tool-call-parser internlm –chat-template examples/tool_chat_template_internlm2_tool.jinja

Reasoning Outputs

推理模型在其输出中会返回一个额外的推理内容字段（reasoning_content），包含得出最终结论的推理步骤。其他模型的输出中没有这个字段。需指定 –enable-reasoning 和 –reasoning-parser 。

• –enable-reasoning
• –reasoning-parser
  • vllm serve Qwen3-235B-A22B –enable-reasoning –reasoning-parser deepseek_r1

Structured Outputs

vLLM 支持使用 xgrammar 或 guidance 作为后端生成结构化输出。

• guided_choice: 输出是选择之一。
  • extra_body={“guided_choice”: [“positive”, “negative”]},
• guided_regex: 输出将遵循正则模式。
  • extra_body={“guided_regex”: r”\w+@\w+.com\n”, “stop”: [“\n”]},
• guided_json: 输出将遵循 JSON 模式。
  • extra_body={“guided_json”: json_schema}
• guided_grammar: 输出将遵循上下文自由语法（CFG）。
  • extra_body={“guided_grammar”: simplified_sql_grammar},
• structural_tag: 在生成文本的一组指定标记内遵循 JSON 模式。

Speculative Decoding

目前(截至2025年5月12日)，vLLM 中的推测解码与流水线并行性不兼容。vLLM 中的推测解码尚未优化，且–num_speculative_tokens参数已弃用。

• –speculative-config
  • –speculative_config ‘{“model”: “facebook/opt-125m”, “num_speculative_tokens”: 5}’
  • –speculative_config ‘{“method”: “ngram”, “num_speculative_tokens”: 5, “prompt_lookup_max”: 4}’

兼容性矩阵

下表显示了相互排斥的功能。

• ✅ = 完全兼容
• 🟠 = 部分兼容
• ❌ = 不兼容