Split View: vLLM 내부 구조 (7) — 배포 튜닝과 흔한 함정, OOM 진단 순서

Inside vLLM (7) — Deployment Tuning, Common Pitfalls, and OOM Triage

• Deciding the Tuning Order First
• gpu_memory_utilization — The First Value to Touch
• Tensor Parallelism and Pipeline Parallelism
• Choosing Quantization
• KV Cache Data Type
• The OOM Diagnostic Order
• Five Common Pitfalls
• Try It Yourself
• References

Deciding the Tuning Order First

Six parts have covered the internals, so this last part turns to deployment. Before listing out the knobs, though, the order needs to be fixed first. The most common reason tuning fails is not that someone picked a wrong value — it is that several values got changed at once, so there is no way to tell which one actually mattered.

The recommended order is this. First, get the model to fit on the GPU. Second, match the length limit to the workload. Third, secure headroom in the KV cache. Fourth, only after that, tune batching and latency. Touching the batching arguments before the first three steps are settled usually does nothing at all.

Everything here was verified against the official documentation and source on 2026-08-12. vLLM moves fast, so re-check settings and behavior against the documentation for the version you are running.

# A typical form combining the arguments covered in this post
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.92 \
  --tensor-parallel-size 1 \
  --max-num-seqs 128

gpu_memory_utilization — The First Value to Touch

The official documentation defines it this way: the fraction of GPU memory the model executor will use, a value between 0 and 1. The declared default confirmed in the documentation and in the CacheConfig source on the main branch, on 2026-08-12, was 0.92. Older posts may state a different number, so check it directly on the version you are running.

This value matters because of the structure covered in parts 1 and 6. vLLM reserves memory equal to this fraction, then uses everything left over after weights and overhead as KV cache. So raising this value immediately grows the KV cache, and the engine can then handle longer requests and more of them concurrently.

That does not mean pushing it close to 1 is the right move, though. This fraction is calculated against the entire GPU, so if another process is sharing the same GPU, the calculation goes wrong. This is especially true in a Kubernetes setup that shares a GPU. Also, actual usage tends to run a bit higher than the calculation because of fragmentation and transient activation tensors, so if you set that headroom to 0, things look fine most of the time and then blow up only on certain combinations of requests.

If raising this value does not increase throughput, that is a signal the limit lives somewhere other than memory. max_num_seqs or max_num_batched_tokens may be the one binding first.

Tensor Parallelism and Pipeline Parallelism

Start by clearing up the most common misconception here. Tensor parallelism is not a performance option. It is a capacity option.

The official documentation's criterion is clear. Use tensor parallelism when the model does not fit on one GPU but does fit across multiple GPUs on one node. Use pipeline parallelism alongside it when the model does not even fit on one node. The documentation also gives the setup directly: set tensor_parallel_size to the number of GPUs per node, and pipeline_parallel_size to the number of nodes. In the example the documentation gives, 2 nodes with 8 GPUs each becomes tensor parallelism 8 and pipeline parallelism 2.

The exception the documentation mentions is also worth knowing. When the GPUs within one node cannot be split evenly, you can set tensor parallelism to 1 and pipeline parallelism to the GPU count, letting the layers be split unevenly.

The default for tensor_parallel_size was confirmed as 1 in the documentation. In other words, if you give it nothing, the engine uses a single GPU — even if the server has several GPUs plugged in. If performance on a multi-GPU box falls short of expectations, check this value first.

What happens if you turn on tensor parallelism for a model that already fits on one GPU? Each GPU gets its own share of the KV cache, so total cache capacity grows — that part is a genuine benefit — but inter-GPU communication is added at every layer. So it cannot be called an unconditional win without actually measuring it. As seen in part 4, the reason the official documentation lists raising tensor parallelism among the countermeasures for preemption is cache space, not processing speed.

Choosing Quantization

Quantization reduces memory by representing weights in fewer bits. And whatever memory that frees up goes straight back into the KV cache. Recalling the structure from part 6 makes it clear why this benefit is large: on the same GPU, you get longer context and more concurrent requests.

The vLLM documentation covers several different approaches. AutoAWQ, BitsAndBytes, GPTQModel, Intel Neural Compressor, LLM Compressor, NVIDIA Model Optimizer, AMD Quark, and TorchAO are among those listed, and the LLM Compressor path covers combinations like FP8 W8A8, INT4 W4A16, and INT8 W8A8. The documentation points to LLM Compressor as the starting point.

What actually matters when choosing is not the name of the method — it comes down to two things.

Hardware support. The documentation provides a table showing that hardware platform compatibility differs by quantization implementation, and states explicitly that this compatibility table can keep changing. So do not pick by name alone — check the table for whether your GPU generation is actually supported. Pick wrong, and it either will not start at all, or it will start but run slower without getting any acceleration.

Whether the model is already quantized. The description of the --quantization argument is that it specifies the weight quantization method, and that if no value is given, it checks the quantization setting in the model's config file. In other words, if you are pulling an already-quantized checkpoint from the hub, you usually do not need to specify this separately.

Quality is also part of this, and it cannot be skipped. Quantization is not free — it affects accuracy. How much it affects accuracy depends on the model, the method, and the task. So this post will not make a generalization like "4-bit is fine" here. There is no substitute for measuring it yourself, on your own evaluation set.

KV Cache Data Type

Weights are not the only thing that can be shrunk. The data type of the KV cache itself is also a configuration item. The documentation describes --kv-cache-dtype as the data type to use for KV cache storage, and states that auto follows the model's data type. The default was confirmed as auto in both the documentation and the source. The source also notes that the fp8 family is supported on CUDA 11.8 and above.

What makes this knob appealing is that its effect lands exactly on the KV cache and nowhere else. Leave the weights alone and cut just the cache in half, and the same memory buys you more length or more concurrency. That said, this is also a precision loss, so do not turn it on without evaluating it first.

The OOM Diagnostic Order

Running out of memory is the single most common problem in operating vLLM. The first step in diagnosing it is always the same. First, work out whether it happened during startup or during operation.

If it failed during startup, the cause is one of two things.

The weights do not fit. It dies at the model-loading stage. The fixes are quantization, tensor parallelism, or a smaller model. Raising gpu_memory_utilization does not help much here, because the situation is already that the weights do not fit even though most of the memory is already being given to them.

The KV cache is too small. This is the same error seen in part 6. You get a message that the maximum sequence length is larger than the number of tokens the KV cache can hold, and the error itself states the fix: raise gpu_memory_utilization, or lower max_model_len. In practice, the latter comes first, because the length is usually left open wider than the actual workload needs.

If it happened during operation, the story is different. vLLM reserves the cache up front at startup, so under normal conditions, a spike in requests does not suddenly cause OOM. When requests pile up, what happens instead of OOM is the preemption covered in part 4. So an OOM during operation usually has a cause outside vLLM: another process landed on the same GPU, gpu_memory_utilization was set higher than the actual headroom, or an unusually large multimodal input came in that had never shown up before.

There is one more case that gets misdiagnosed often: a sudden slowdown that is not actually OOM. In this case, check the preemption warning logs before touching any memory argument. If preemption is happening repeatedly, that is a capacity problem, not a performance problem.

Five Common Pitfalls

Here is a collection of the pitfalls that came up repeatedly across the series.

The last row matters most. The first four get fixed by changing a setting. This one is a prompt-design problem, so no argument you touch makes it better.

One conclusion runs through all seven parts. In vLLM, performance mostly comes down to how carefully you conserve and reuse the KV cache. Splitting it into blocks, refilling it every step, sharing overlapping prefixes, and using length limits to bound the worst case — all of it is a different face of the same story.

Try It Yourself

• LLM GPU Memory (VRAM) Calculator — Try changing quantization and GPU count and calculate how the weights and KV cache change. You can rehearse this post's tuning order with real numbers.
• LLM API Cost Calculator — Once you have settled on a self-serving configuration, compare it against running the same workload through an API.
• K8s Practice Lab — If you are deploying a model server on Kubernetes, it helps to get hands-on practice with resource limits, rollouts, and failure diagnosis.
• Previous: Inside vLLM (6) — Context Window vs max_model_len vs max_tokens, Fully Explained
• Series start: Inside vLLM (1) — The Full Path From One Request to One Token

References

• vLLM Engine Arguments (docs.vllm.ai) — Where the descriptions and defaults for --gpu-memory-utilization, --tensor-parallel-size, --quantization, and --kv-cache-dtype were read.
• vLLM CacheConfig source (GitHub main) — Where the declared defaults for gpu_memory_utilization and the cache data type were confirmed.
• vLLM Parallelism and Scaling (docs.vllm.ai) — Source for when to use tensor parallelism versus pipeline parallelism, and how to configure them to match node and GPU counts.
• vLLM Quantization (docs.vllm.ai) — Source for the list of supported methods and the guidance on the hardware compatibility table.
• vLLM Optimization and Tuning (docs.vllm.ai) — Source for preemption countermeasures and the direction for adjusting the related arguments.
• vLLM V1 Guide (docs.vllm.ai) — Source for the statement that KV cache swapping between GPU and CPU was removed.