문제 해결

문제 해결 (Troubleshooting)

vLLM을 쓰다 보면 모델 다운로드가 멈추거나, OOM이 나거나, 생성 품질이 바뀌는 등 다양한 문제를 만나게 돼요. 이 문서는 vLLM 문서에서 제안하는 문제 해결 전략을 상황별로 정리해요. 버그를 발견했다고 생각되면 먼저 기존 이슈를 검색해 이미 보고됐는지 확인하고, 아니라면 관련 정보를 최대한 담아 새 이슈를 올리세요.

출처: vLLM 공식 문서 — troubleshooting

참고: 문제를 디버깅한 뒤에는 정의한 디버깅 환경 변수를 끄거나, 새 셸을 시작해 남아 있는 디버깅 설정의 영향을 피하세요. 디버깅 기능을 켜둔 채로 두면 시스템이 느려질 수 있어요.

모델 다운로드가 멈출 때 (Hangs downloading a model)

모델이 아직 디스크에 다운로드되지 않았다면 vLLM이 인터넷에서 다운로드하는데, 시간이 걸리고 인터넷 연결에 의존해요. huggingface-cli로 모델을 먼저 다운로드하고 로컬 경로를 vLLM에 넘기는 것을 권장합니다. 이렇게 하면 문제를 격리할 수 있어요.

디스크에서 모델 로딩이 멈출 때 (Hangs loading a model from disk)

모델이 크면 디스크에서 로딩하는 데 오래 걸릴 수 있어요. 모델을 어디에 저장하는지 주의하세요. 일부 클러스터는 노드 간 공유 파일시스템(분산 파일시스템이나 네트워크 파일시스템)을 쓰는데, 이것은 느릴 수 있어요. 모델은 로컬 디스크에 저장하는 게 좋아요. 추가로 CPU 메모리 사용량도 확인하세요. 모델이 너무 크면 CPU 메모리를 많이 차지해, 디스크와 메모리 사이를 자주 스왑해야 해서 운영체제가 느려질 수 있습니다.

참고: 모델 다운로드/로딩 문제를 격리하려면 --load-format dummy 인자로 모델 가중치 로딩을 건너뛸 수 있어요. 이렇게 하면 모델 다운로드/로딩이 병목인지 확인할 수 있습니다.

메모리 부족 (Out of memory)

모델이 단일 GPU에 들어가기 너무 크면 OOM 오류가 발생해요. 메모리 소비를 줄이기 위해 다음 옵션들을 고려하세요.

생성 품질이 바뀌었을 때 (Generation quality changed)

v0.8.0에서 기본 샘플링 파라미터의 출처가 Pull Request #12622에서 바뀌었어요. v0.8.0 이전에는 기본 샘플링 파라미터가 vLLM의 중립 기본값 집합에서 왔고, v0.8.0부터는 모델 제작자가 제공한 generation_config.json에서 옵니다.

대부분의 경우 이는 더 높은 품질의 응답으로 이어지는데, 모델 제작자가 자기 모델에 가장 좋은 샘플링 파라미터를 알 가능성이 크기 때문이에요. 하지만 일부 경우 모델 제작자의 기본값이 성능 저하를 일으킬 수 있습니다.

이런 일이 일어나는지 확인하려면 온라인에서 --generation-config vllm, 오프라인에서 generation_config="vllm"으로 이전 기본값을 시도해 보세요. 시도 후 생성 품질이 좋아지면 vLLM 기본값을 계속 쓰고, https://huggingface.co 의 모델 제작자에게 더 좋은 품질을 내도록 generation_config.json 기본값을 업데이트하도록 요청하는 걸 권장해요.

로깅 더 활성화하기 (Enable more logging)

다른 전략으로 문제가 해결되지 않으면 vLLM 인스턴스가 어딘가에 갇힌 것일 수 있어요. 다음 환경 변수들로 문제를 디버깅할 수 있습니다.

export VLLM_LOGGING_LEVEL=DEBUG      # to turn on more logging
export VLLM_LOG_STATS_INTERVAL=1.   # to get log statistics more frequently for tracking running queue, waiting queue and cache hit states
export CUDA_LAUNCH_BLOCKING=1       # to identify which CUDA kernel is causing the problem
export NCCL_DEBUG=TRACE             # to turn on more logging for NCCL
export VLLM_TRACE_FUNCTION=1        # to record all function calls for inspection in the log files to tell which function crashes or hangs.

(경고: VLLM_TRACE_FUNCTION=1은 토큰 생성을 100배 이상 느리게 만들 수 있어요. 꼭 필요할 때만 사용하세요.)

중단점 (Breakpoints)

vLLM의 코드베이스에서 서브프로세스로 실행되는 부분은 일반 pdb 중단점이 동작하지 않을 수 있어요. 다음과 같은 경험이 나올 거예요.

  File "/usr/local/uv/cpython-3.12.11-linux-x86_64-gnu/lib/python3.12/bdb.py", line 100, in trace_dispatch
    return self.dispatch_line(frame)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/uv/cpython-3.12.11-linux-x86_64-gnu/lib/python3.12/bdb.py", line 125, in dispatch_line
    if self.quitting: raise BdbQuit
                      ^^^^^^^^^^^^^
bdb.BdbQuit

한 가지 해결책은 forked-pdb를 쓰는 거예요. pip install fpdb로 설치하고 아래처럼 중단점을 설정하세요.

__import__('fpdb').ForkedPdb().set_trace()

또 다른 옵션은 VLLM_ENABLE_V1_MULTIPROCESSING 환경 변수로 멀티프로세싱을 완전히 비활성화하는 거예요. 이렇게 하면 스케줄러가 같은 프로세스에 유지되어 기본 pdb 중단점을 쓸 수 있습니다.

import os
os.environ["VLLM_ENABLE_V1_MULTIPROCESSING"] = "0"

잘못된 네트워크 설정 (Incorrect network setup)

복잡한 네트워크 구성에서는 vLLM 인스턴스가 올바른 IP 주소를 얻지 못할 수 있어요. DEBUG 06-10 21:32:17 parallel_state.py:88] world_size=8 rank=0 local_rank=0 distributed_init_method=tcp://xxx.xxx.xxx.xxx:54641 backend=nccl 같은 로그에서 IP 주소가 올바른지 확인하세요. 올바르지 않다면 export VLLM_HOST_IP=<your_ip_address> 환경 변수로 IP 주소를 오버라이드할 수 있어요.

또한 export NCCL_SOCKET_IFNAME=<your_network_interface>와 export GLOO_SOCKET_IFNAME=<your_network_interface>를 설정해 IP 주소의 네트워크 인터페이스를 지정해야 할 수도 있습니다.

self.graph.replay() 근처 오류

vLLM이 vllm/worker/model_runner.py의 self.graph.replay() 근처에서 충돌하고 에러 트레이스가 그곳을 잡는다면, CUDAGraph 안의 CUDA 오류예요. 오류를 일으키는 특정 CUDA 연산을 식별하려면 커맨드라인에 --enforce-eager를 추가하거나 LLM 클래스에 enforce_eager=True를 설정해 CUDAGraph 최적화를 비활성화해, 정확한 CUDA 연산을 격리하면 됩니다.

잘못된 하드웨어/드라이버 (Incorrect hardware/driver)

GPU/CPU 통신이 성립되지 않으면 다음 Python 스크립트로 GPU/CPU 통신이 올바르게 동작하는지 확인할 수 있어요.

단일 노드 테스트라면 --nproc-per-node를 사용할 GPU 수로 조정하세요.

NCCL_DEBUG=TRACE torchrun --nproc-per-node=<number-of-GPUs> test.py

멀티 노드 테스트라면 --nproc-per-node와 --nnodes를 설정에 맞게 조정하고 MASTER_ADDR를 모든 노드에서 닿을 수 있는 마스터 노드의 올바른 IP 주소와 포트(예: 10.0.0.1:29400)로 설정한 뒤 실행하세요.

NCCL_DEBUG=TRACE torchrun --nnodes 2 \
    --nproc-per-node=2 \
    --rdzv_backend=static \
    --rdzv_endpoint=$MASTER_ADDR \
    --node-rank $NODE_RANK test.py

마스터 노드에서는 NODE_RANK를 0으로, 워커에서는 1, 2, ...로 설정하세요. 참고: c10d 대신 --rdzv_backend=static을 쓰는데, c10d rendezvous 백엔드는 멀티 노드 설정에서 DNS 해석 오류로 실패할 수 있기 때문이에요. static 백엔드는 명시적 노드 랭크를 요구해 이를 피합니다.

스크립트가 성공하면 sanity check is successful! 메시지를 볼 수 있어요. 테스트 스크립트가 멈추거나 충돌하면 보통 하드웨어/드라이버가 어떤 의미에서 고장난 거예요. 시스템 관리자나 하드웨어 벤더에 연락하세요. 일반적인 임시 조치로 export NCCL_P2P_DISABLE=1 같은 일부 NCCL 환경 변수를 튜닝해볼 수 있습니다. 이 환경 변수들은 시스템 성능에 영향을 줄 수 있으므로 임시 조치로만 사용하고, 최선의 해결책은 테스트 스크립트가 성공적으로 실행되도록 하드웨어/드라이버를 고치는 것입니다.

Python multiprocessing

RuntimeError 예외

로그에서 이런 경고를 봤다면:

WARNING 12-11 14:50:37 multiproc_worker_utils.py:281] CUDA was previously
    initialized. We must use the `spawn` multiprocessing start method. Setting
    VLLM_WORKER_MULTIPROC_METHOD to 'spawn'. See
    https://docs.vllm.ai/en/latest/usage/troubleshooting.html#python-multiprocessing
    for more information.

vllm 사용을 if __name__ == '__main__': 블록 뒤로 가드하도록 Python 코드를 수정해야 해요. 예를 들어 다음 대신:

import vllm

llm = vllm.LLM(...)

이렇게 써보세요:

if __name__ == '__main__':
    import vllm

    llm = vllm.LLM(...)

torch.compile 오류

vLLM은 성능 향상을 위해 모델을 최적화하는 데 torch.compile에 크게 의존하며, torch.compile 기능과 triton 라이브러리에 대한 의존성을 도입해요. vLLM을 실행하기 전에 torch.compile이 예상대로 동작하는지 스크립트로 확인할 수 있어요. torch/_inductor 디렉터리에서 오류가 발생하면, 보통 사용 중인 PyTorch 버전과 호환되지 않는 커스텀 triton 라이브러리가 있다는 뜻이에요. 예: Issue #12219.

모델 검사 실패 (Model failed to be inspected)

이런 오류가 보이면:

  File "vllm/model_executor/models/registry.py", line xxx, in _raise_for_unsupported
    raise ValueError(
ValueError: Model architectures ['<arch>'] failed to be inspected. Please check the logs for more details.

vLLM이 모델 파일을 import 하는 데 실패했다는 뜻이에요. 보통 누락된 의존성이나 vLLM 빌드의 오래된 바이너리와 관련이 있어요. 로그를 주의 깊게 읽어 오류의 근본 원인을 파악하세요.

모델 미지원 (Model not supported)

이런 오류가 보이거나:

Traceback (most recent call last):
...
  File "vllm/model_executor/models/registry.py", line xxx, in inspect_model_cls
    for arch in architectures:
TypeError: 'NoneType' object is not iterable

이런 오류가 보이는데:

  File "vllm/model_executor/models/registry.py", line xxx, in _raise_for_unsupported
    raise ValueError(
ValueError: Model architectures ['<arch>'] are not supported for now. Supported architectures: [...]

모델이 지원 목록에 있다고 확신한다면, vLLM의 모델 해석(model resolution)에 문제가 있을 수 있어요. 그 경우 모델에 대한 vLLM 구현을 명시적으로 지정하는 단계를 따라야 합니다.

디바이스 타입 추론 실패 (Failed to infer device type)

RuntimeError: Failed to infer device type 같은 오류가 보이면 vLLM이 런타임 환경의 디바이스 타입을 추론하는 데 실패했다는 뜻이에요. vLLM이 디바이스 타입을 어떻게 추론하는지와 왜 예상대로 동작하지 않는지 코드로 확인할 수 있어요. VLLM_LOGGING_LEVEL=DEBUG 환경 변수를 설정하면 문제 디버깅에 도움이 되는 더 상세한 로그를 볼 수 있습니다.

NCCL 오류: ncclCommInitRank 중 unhandled system error

GPUDirect RDMA를 멀티 노드 분산 서빙에 쓰는데 NCCL_DEBUG=INFO를 설정해도 명확한 오류 메시지 없이 ncclCommInitRank 중 오류가 발생한다면, vLLM이 NCCL communicator 초기화에 실패한 것일 수 있어요. 원인은 누락된 IPC_LOCK Linux capability나 마운트되지 않은 /dev/shm일 가능성이 있어요. GPUDirect RDMA 활성화 문서를 참고해 적절히 구성하세요.

CUDA 오류: PTX가 지원되지 않는 툴체인으로 컴파일됨

RuntimeError: CUDA error: the provided PTX was compiled with an unsupported toolchain 같은 오류가 보이면 vLLM wheel의 CUDA PTX가 시스템이 지원하지 않는 툴체인으로 컴파일됐다는 뜻이에요. RuntimeError: The NVIDIA driver on your system is too old 오류도 여기 해당해요.

공개된 vLLM wheel은 특정 CUDA 툴킷 버전으로 컴파일되고, 컴파일된 코드는 더 낮은 CUDA 드라이버 버전에서 실행에 실패할 수 있어요. CUDA 호환성 문서에서 자세한 내용을 확인하세요.

공식 vLLM Docker 이미지를 쓴다면 docker run에 -e VLLM_ENABLE_CUDA_COMPATIBILITY=1을 추가해 해결할 수 있어요. 이렇게 하면 사전 설치된 CUDA 전방 호환 라이브러리가 활성화됩니다.

Docker 밖에서 실행한다면, CUDA 리포지토리를 활성화한 상태로 패키지 매니저에서 cuda-compat 패키지를 설치하면 돼요. 예를 들어 Ubuntu에서 sudo apt-get install cuda-compat-12-9를 실행한 뒤 export VLLM_ENABLE_CUDA_COMPATIBILITY=1과 export VLLM_CUDA_COMPATIBILITY_PATH="/usr/local/cuda-12.9/compat"를 설정하세요. Conda에서는 conda install -c conda-forge cuda-compat=12.9로 설치한 뒤 환경을 활성화하고 export VLLM_ENABLE_CUDA_COMPATIBILITY=1과 export VLLM_CUDA_COMPATIBILITY_PATH="${CONDA_PREFIX}/cuda-compat"를 설정하세요.

구성이 동작하는지 다음 최소 스크립트로 검증할 수 있어요.

export VLLM_ENABLE_CUDA_COMPATIBILITY=1
export VLLM_CUDA_COMPATIBILITY_PATH="/usr/local/cuda-12.9/compat"

python3 - << 'EOF'
import vllm
import torch

print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA device count: {torch.accelerator.device_count()}")
EOF

여기서 CUDA 12.9를 예시로 든 것이며, vLLM의 기본 CUDA 버전이 올라가면 더 높은 버전의 cuda-compat 패키지를 설치해야 할 수도 있어요.

ptxas fatal: Value 'sm_110a' is not defined for option 'gpu-name'

CUDA 13에서 triton 커널을 쓰면 이런 오류가 보일 수 있어요. 이것은 triton 번들의 ptxas가 디바이스와 호환되지 않는다는 뜻이에요. TRITON_PTXAS_PATH 환경 변수를 설정해 CUDA 툴킷의 ptxas를 수동으로 사용해야 합니다.

export CUDA_HOME=/usr/local/cuda
export TRITON_PTXAS_PATH="${CUDA_HOME}/bin/ptxas"
export PATH="${CUDA_HOME}/bin:$PATH"

알려진 이슈 (Known Issues)

  • v0.5.2, v0.5.3, v0.5.3.post1에는 zmq로 인한 버그가 있어서 머신 구성에 따라 vLLM이 간헐적으로 멈출 수 있어요. 최신 vllm 버전으로 업그레이드해 수정을 포함하면 됩니다.
  • NCCL 버전이 오래되어 발생하는 메모리 오버헤드 문제를 해결하기 위해 vLLM >= 0.4.3, <= 0.10.1.1은 NCCL_CUMEM_ENABLE=0 환경 변수를 설정했습니다. vLLM에 연결하는 외부 프로세스도 같은 변수를 설정해 멈춤이나 충돌을 방지해야 했어요. 기본 NCCL 버그가 NCCL 2.22.3에서 수정됐으므로, 최신 vLLM 버전에서는 NCCL 성능 최적화를 위해 이 오버라이드가 제거되었습니다.
  • NVLink가 없는 일부 PCIe 머신에서 transport/shm.cc:590 NCCL WARN Cuda failure 217 'peer access is not supported between these two devices' 같은 오류가 보이면 드라이버 버그 때문일 가능성이 커요. NCCL_CUMEM_HOST_ENABLE=0을 설정해 기능을 비활성화하거나 드라이버를 최신 버전으로 업그레이드할 수 있습니다.

더 알아보기 (Learn more)