vllm.config.scheduler
¶
Classes:
-
SchedulerConfig–Scheduler configuration.
SchedulerConfig
¶
Scheduler configuration.
Methods:
-
compute_hash–WARNING: Whenever a new field is added to this config,
-
default_factory–Create a
SchedulerConfigwith default values for itsInitVars.
Attributes:
-
async_scheduling(bool | None) –If set to False, disable async scheduling. Async scheduling helps to
-
disable_chunked_mm_input(bool) –If set to true and chunked prefill is enabled, we do not want to
-
disable_hybrid_kv_cache_manager(bool | None) –If set to True, KV cache manager will allocate the same size of KV cache
-
enable_chunked_prefill(bool) –If True, prefill requests can be chunked based
-
encoder_cache_size(int) –Multimodal encoder cache size, only used in V1.
-
is_multimodal_model(bool) –True if the model is multimodal.
-
long_prefill_token_threshold(int) –For chunked prefill, a request is considered long if the prompt is
-
long_prefill_token_threshold_adaptive(bool) –Floor the effective long prefill token threshold at a fair share of
-
max_num_active_seqs(int | None) –Maximum number of requests the scheduler admits into RUNNING.
-
max_num_batched_tokens(int) –Maximum number of tokens that can be processed in a single iteration.
-
max_num_encoder_input_tokens(int) –Multimodal encoder compute budget, only used in V1.
-
max_num_queued_reqs(int | None) –Maximum number of requests that can be in-flight (waiting or running)
-
max_num_queued_tokens(int | None) –Maximum total prompt tokens of requests currently in the prefill
-
max_num_scheduled_tokens(int | None) –Maximum number of tokens that the scheduler may issue in a single iteration.
-
max_num_seqs(int) –Maximum number of sequences to be processed in a single iteration.
-
policy(SchedulerPolicy) –The scheduling policy to use:
-
prefill_schedule_interval(int) –For data-parallel deployments, only admit new prefill requests
-
runner_type(RunnerType) –The runner type to launch for the model.
-
scheduler_cls(str | type[object] | None) –The scheduler class to use. "vllm.v1.core.sched.scheduler.Scheduler" is
-
scheduler_reserve_full_isl(bool) –If True, the scheduler checks whether the full input sequence length
-
stream_interval(int) –The interval (or buffer size) for streaming in terms of token length.
-
watermark(float) –Fraction of total KV cache blocks to keep free (the watermark) when
Source code in vllm/config/scheduler.py
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | |
async_scheduling = None
class-attribute
instance-attribute
¶
If set to False, disable async scheduling. Async scheduling helps to avoid gaps in GPU utilization, leading to better latency and throughput.
disable_chunked_mm_input = False
class-attribute
instance-attribute
¶
If set to true and chunked prefill is enabled, we do not want to partially schedule a multimodal item. Only used in V1 This ensures that if a request has a mixed prompt (like text tokens TTTT followed by image tokens IIIIIIIIII) where only some image tokens can be scheduled (like TTTTIIIII, leaving IIIII), it will be scheduled as TTTT in one step and IIIIIIIIII in the next.
disable_hybrid_kv_cache_manager = None
class-attribute
instance-attribute
¶
If set to True, KV cache manager will allocate the same size of KV cache for all attention layers even if there are multiple type of attention layers like full attention and sliding window attention. If set to None, the default value will be determined based on the environment and starting configuration.
enable_chunked_prefill = True
class-attribute
instance-attribute
¶
If True, prefill requests can be chunked based
on the remaining max_num_batched_tokens.
The default value here is mainly for convenience when testing.
In real usage, this should be set in EngineArgs.create_engine_config.
encoder_cache_size = Field(init=False)
class-attribute
instance-attribute
¶
Multimodal encoder cache size, only used in V1.
NOTE: This is not currently configurable. It will be overridden by max_num_batched_tokens in case max multimodal embedding size is larger.
is_multimodal_model = False
class-attribute
instance-attribute
¶
True if the model is multimodal.
long_prefill_token_threshold = Field(default=0, ge=0)
class-attribute
instance-attribute
¶
For chunked prefill, a request is considered long if the prompt is longer than this number of tokens. 0 disables the cap (default).
The cap is not applied when the request is the only one in the batch, since there is no other request for it to starve.
long_prefill_token_threshold_adaptive = Field(default=False)
class-attribute
instance-attribute
¶
Floor the effective long prefill token threshold at a fair share of the token budget: max_num_batched_tokens divided by the number of queued and running requests. Only applies when long_prefill_token_threshold is nonzero.
max_num_active_seqs = Field(default=None, ge=1)
class-attribute
instance-attribute
¶
Maximum number of requests the scheduler admits into RUNNING.
max_num_seqs sizes the model runner (per-request buffers and CUDA
graph capture) and is also the default admission limit. Setting this
lowers only the number of requests that may occupy RUNNING, so decode
batches stay smaller without shrinking runner or graph capacity. Must
be <= max_num_seqs. None (default) keeps current behavior.
max_num_batched_tokens = Field(default=DEFAULT_MAX_NUM_BATCHED_TOKENS, ge=1)
class-attribute
instance-attribute
¶
Maximum number of tokens that can be processed in a single iteration.
The default value here is mainly for convenience when testing.
In real usage, this should be set in EngineArgs.create_engine_config.
max_num_encoder_input_tokens = Field(init=False)
class-attribute
instance-attribute
¶
Multimodal encoder compute budget, only used in V1.
NOTE: This is not currently configurable. It will be overridden by max_num_batched_tokens in case max multimodal embedding size is larger.
max_num_queued_reqs = Field(default=None, ge=0)
class-attribute
instance-attribute
¶
Maximum number of requests that can be in-flight (waiting or running) at the same time, or None for no limit. When the limit is reached, new requests are rejected with HTTP 503 so the client can retry on another instance. This bounds vLLM's otherwise unbounded request queue and is primarily a coarse capacity valve.
Unlike max_num_seqs, which applies per data-parallel rank, this
limit is enforced in the API server process and counts in-flight
requests across all DP ranks it routes to. Size it as roughly
data_parallel_size * max_num_seqs plus the desired queue depth if
it should not bind before per-rank admission does.
max_num_queued_tokens = Field(default=None, ge=0)
class-attribute
instance-attribute
¶
Maximum total prompt tokens of requests currently in the prefill phase, or None for no limit. When the limit is reached, new requests are rejected with HTTP 503.
This is a TTFT QoS mechanism: by setting it to
target_TTFT * prefill_throughput you reject requests when the
prefill backlog would exceed the latency target. In a disaggregated
prefill-decode setup this maps directly to the prefill pool's
capacity.
Like max_num_queued_reqs, this limit is enforced in the API
server process and covers the prefill backlog across all DP ranks it
routes to, so prefill_throughput in the formula above is the
aggregate throughput of the deployment.
Note: the count is conservative. A partially prefilled request
still contributes its full prompt_len until it transitions out
of the prefill phase, because the scheduler's per-iteration
num_computed_tokens progress is not propagated to the API
server process during prefill (EngineCoreOutput is only
emitted once the request starts producing tokens). Similarly,
prefix-cache hits (num_cached_tokens) are only known to the
OutputProcessor after prefill completes. This overestimates the
real backlog, causing earlier rejection than strictly necessary
— the safe direction for QoS. The impact is limited to long
prompts under chunked prefill; short prompts that prefill in a
single iteration are unaffected.
max_num_scheduled_tokens = Field(default=None, ge=0)
class-attribute
instance-attribute
¶
Maximum number of tokens that the scheduler may issue in a single iteration.
This is usually equal to max_num_batched_tokens, but can be smaller in cases when the model might append tokens into the batch (such as speculative decoding). Defaults to max_num_batched_tokens.
max_num_seqs = Field(default=DEFAULT_MAX_NUM_SEQS, ge=1)
class-attribute
instance-attribute
¶
Maximum number of sequences to be processed in a single iteration.
The default value here is mainly for convenience when testing.
In real usage, this should be set in EngineArgs.create_engine_config.
policy = 'fcfs'
class-attribute
instance-attribute
¶
The scheduling policy to use:
- "fcfs" means first come first served, i.e. requests are handled in order of arrival.
- "priority" means requests are handled based on given priority (lower value means earlier handling) and time of arrival deciding any ties).
prefill_schedule_interval = Field(default=1, ge=1)
class-attribute
instance-attribute
¶
For data-parallel deployments, only admit new prefill requests once every N engine steps, aligned across DP ranks, to better balance per-step forward-pass times.
runner_type = 'generate'
class-attribute
instance-attribute
¶
The runner type to launch for the model.
scheduler_cls = None
class-attribute
instance-attribute
¶
The scheduler class to use. "vllm.v1.core.sched.scheduler.Scheduler" is the default scheduler. Can be a class directly or the path to a class of form "mod.custom_class".
scheduler_reserve_full_isl = True
class-attribute
instance-attribute
¶
If True, the scheduler checks whether the full input sequence length fits in the KV cache before admitting a new request, rather than only checking the first chunk. Prevents over-admission and KV cache thrashing with chunked prefill.
stream_interval = Field(default=1, ge=1)
class-attribute
instance-attribute
¶
The interval (or buffer size) for streaming in terms of token length. A smaller value (1) makes streaming smoother by sending each token immediately, while a larger value (e.g., 10) reduces host overhead and may increase throughput by batching multiple tokens before sending.
watermark = Field(default=0.0, ge=0.0, lt=1.0)
class-attribute
instance-attribute
¶
Fraction of total KV cache blocks to keep free (the watermark) when admitting waiting or preempted requests into the running queue. This headroom helps avoid frequent KV cache eviction and the resulting repeated preemption of requests when GPU memory is scarce. Must be in the range [0.0, 1.0); 0.0 (the default) disables the watermark.
_skip_none_validation(value, handler)
classmethod
¶
Skip validation if the value is None when initialisation is delayed.
Source code in vllm/config/scheduler.py
compute_hash()
¶
WARNING: Whenever a new field is added to this config, ensure that it is included in the factors list if it affects the computation graph.
Provide a hash that uniquely identifies all the configs that affect the structure of the computation graph from input ids/embeddings to the final hidden states, excluding anything before input ids/embeddings and after the final hidden states.
Source code in vllm/config/scheduler.py
default_factory(**kwargs)
staticmethod
¶
Create a SchedulerConfig with default values for its InitVars.