환경 변수

환경 변수 (Environment Variables)

vLLM은 시스템을 구성하기 위해 다음과 같은 환경 변수들을 사용합니다. 모든 vLLM 환경 변수는 VLLM_ 접두사를 가집니다.

출처: 문서

본문

경고: VLLM_PORT와 VLLM_HOST_IP는 vLLM 내부 사용을 위한 포트와 IP를 설정합니다. API 서버의 포트/IP가 아닙니다. --host $VLLM_HOST_IP와 --port $VLLM_PORT로 API 서버를 시작하면 동작하지 않습니다.

쿠버네티스 사용자는 각별히 주의하세요. 서비스 이름을 vllm으로 짓지 마세요. 쿠버네티스는 각 서비스마다 대문자 서비스명을 접두사로 하는 환경 변수를 설정하는데, 이게 vLLM의 환경 변수와 충돌할 수 있기 때문입니다.

vLLM 환경 변수는 내부적으로 다음과 같은 딕셔너리로 정의됩니다.

environment_variables: dict[str, Callable[[], Any]] = {
    # ================== 설치 시점 환경 변수 ==================
    # vLLM의 대상 디바이스, [cuda (기본), rocm, cpu] 지원
    "VLLM_TARGET_DEVICE": lambda: os.getenv("VLLM_TARGET_DEVICE", "cuda").lower(),
    # vLLM의 주 CUDA 버전, [12.6, 12.8, 12.9] 지원, 12.8 기본.
    # PyTorch를 따르지만 오버라이드 가능
    "VLLM_MAIN_CUDA_VERSION": lambda: os.getenv("VLLM_MAIN_CUDA_VERSION", "").lower()
    or "12.8",
    # 병렬로 실행할 최대 컴파일 작업 수. 기본은 CPU 수
    "MAX_JOBS": lambda: os.getenv("MAX_JOBS", None),
    # nvcc에 사용할 스레드 수 (기본 1).
    # 설정하면 CPU 오버서브스크립션을 피하기 위해 MAX_JOBS 가 줄어듦
    "NVCC_THREADS": lambda: os.getenv("NVCC_THREADS", None),
    # 설정하면 vllm 이 미리 컴파일된 바이너리 (*.so) 를 사용
    "VLLM_USE_PRECOMPILED": lambda: os.environ.get("VLLM_USE_PRECOMPILED", "")
    .strip()
    .lower()
    in ("1", "true")
    or bool(os.environ.get("VLLM_PRECOMPILED_WHEEL_LOCATION")),
}

환경 변수는 크게 다음과 같은 범주로 나뉩니다.

  • 설치 시점 변수: VLLM_TARGET_DEVICE, VLLM_MAIN_CUDA_VERSION, MAX_JOBS, NVCC_THREADS, VLLM_USE_PRECOMPILED, CMAKE_BUILD_TYPE 등
  • 런타임 변수: 로깅(VLLM_LOGGING_LEVEL), 캐시(VLLM_CPU_KVCACHE_SPACE), 미디어 로딩 스레드 수(VLLM_MEDIA_LOADING_THREAD_COUNT), Torch 프로파일러 디렉터리(VLLM_TORCH_PROFILER_DIR) 등

대표적인 런타임 변수:

환경 변수 용도
VLLM_LOGGING_LEVEL 최소 로그 레벨 설정
VLLM_CPU_KVCACHE_SPACE CPU 백엔드의 KV 캐시 크기(기본 4 GiB)
VLLM_MEDIA_LOADING_THREAD_COUNT API 서버에서 미디어 로드에 쓰는 CPU 스레드 수
VLLM_TORCH_PROFILER_DIR Torch Profiler 활성화 디렉터리
VLLM_PORT / VLLM_HOST_IP vLLM 내부용 포트/IP(API 서버용 아님)
VLLM_USE_PRECOMPILED 사전 컴파일된 바이너리 사용 여부
VLLM_TARGET_DEVICE 대상 디바이스(cuda/rocm/cpu)

더 알아보기 (Learn more)