환경 변수

환경 변수 (Environment Variables)

vLLM은 컴파일 시점과 실행 시점 모두에서 여러 시스템 설정을 환경 변수로 주고받아요. 환경 변수는 코드를 수정하지 않고도 동작을 바꿀 수 있는 유용한 도구예요. 특히 설치(빌드) 단계와 런타임 단계에서 어떤 변수가 어떻게 쓰이는지 알면, 난감한 문제를 빠르게 풀어낼 수 있답니다.

출처: vLLM 공식 문서 — env_vars

시작하기 전에 알아둘 것

환경 변수를 쓰기 전에 꼭 기억해야 할 두 가지가 있어요.

⚠️ 주의 1: VLLM_PORT와 VLLM_HOST_IP는 vLLM 내부용 포트와 IP를 설정하는 값이에요. API 서버의 포트나 IP가 아닙니다. 만약 --host $VLLM_HOST_IP --port $VLLM_PORT처럼 이 변수들로 API 서버를 띄우려 하면 제대로 동작하지 않아요.

⚠️ 주의 2: vLLM이 사용하는 모든 환경 변수는 VLLM_ 접두사를 가집니다. Kubernetes를 쓰는 분이라면 특별히 조심해야 하는데, 서비스 이름을 vllm로 짓지 마세요. 쿠버네티스는 각 서비스마다 서비스 이름을 대문자로 한 접두사를 붙여 환경 변수를 설정하기 때문에, 쿠버네티스가 만든 변수와 vLLM의 환경 변수가 충돌할 수 있어요.

환경 변수는 어떻게 정의되나요?

vLLM 내부적으로 환경 변수들은 딕셔너리 형태로 한곳에 모여 정의돼요. 각 항목은 변수 이름을 키로, 그 변수의 값을 읽어 반환하는 람다(함수)를 값으로 갖죠. 대략 다음과 같은 구조예요.

logger = logging.getLogger(__name__)

environment_variables: dict[str, Callable[[], Any]] = {
    # ================== Installation Time Env Vars ==================
    # Target device of vLLM, supporting [cuda (by default),
    # rocm, cpu]
    "VLLM_TARGET_DEVICE": lambda: os.getenv("VLLM_TARGET_DEVICE", "cuda").lower(),
    # Main CUDA version of vLLM. This follows PyTorch but can be overridden.
    "VLLM_MAIN_CUDA_VERSION": lambda: os.getenv("VLLM_MAIN_CUDA_VERSION", "").lower()
    or "12.9",
    # Controls PyTorch float32 matmul precision mode within vLLM workers.
    # Valid options mirror torch.set_float32_matmul_precision
    "VLLM_FLOAT32_MATMUL_PRECISION": env_with_choices(
        "VLLM_FLOAT32_MATMUL_PRECISION",
        "highest",
        ["highest", "high", "medium"],
        case_sensitive=False,
    ),
    # Maximum number of compilation jobs to run in parallel.
    # By default this is the number of CPUs
    "MAX_JOBS": lambda: os.getenv("MAX_JOBS", None),
    # Number of threads to use for nvcc
    # By default this is 1.
    # If set, `MAX_JOBS` will be reduced to avoid oversubscribing the CPU.
    "NVCC_THREADS": lambda: os.getenv("NVCC_THREADS", None),
    # If set, vllm will use precompiled binaries (*.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")),
    # If set, skip adding +precompiled suffix to version string
    "VLLM_SKIP_PRECOMPILED_VERSION_SUFFIX": lambda: bool(
        int(os.environ.get("VLLM_SKIP_PRECOMPILED_VERSION_SUFFIX", "0"))
    ),
    # Used to mark that setup.py is running in a Docker build context,
    # in order to force the use of precompiled binaries.
    "VLLM_DOCKER_BUILD_CONTEXT": lambda: os.environ.get("VLLM_DOCKER_BUILD_CONTEXT", "")
    .strip()
    .lower()
    in ("1", "true"),
    # CMake build type
    # If not set, defaults to "Debug" or "RelWithDebInfo"
    # Available options: "Debug", "Release", "RelWithDebInfo"
    "CMAKE_BUILD_TYPE": env_with_choices(
        "CMAKE_BUILD_TYPE", None, ["Debug", "Release", "RelWithDebInfo"]
    ),
    # If set, vllm will print verbose logs during installation
    ...
}

이 코드를 보면 환경 변수 목록이 설치(Installation Time)용과 실행용으로 나뉘어 관리되는 걸 알 수 있어요. 값에 기본값(default)이 있고, env_with_choices 같은 헬퍼로 허용된 선택지만 강제하는 변수들도 있죠.

설치 시점에 쓰이는 주요 변수들

앞선 코드에서 몇 가지 설치 관련 변수를 살펴볼 수 있어요.

이 외에도 빌드/실행 시점에 쓰이는 많은 변수가 VLLM_ 접두사 아래 정의되어 있어요. 공식 문서의 환경 변수 목록(docs/configuration/env_vars.rst)을 보면 전체 목록을 확인할 수 있습니다.

정리하면

• vLLM 환경 변수는 거의 모두 VLLM_ 접두사를 사용해요.
• 설치(빌드) 시점 변수와 런타임 변수가 구분되어 있지만, 코드 구조상 하나의 딕셔너리로 관리됩니다.
• VLLM_PORT, VLLM_HOST_IP는 내부용이므로 API 서버 설정과 혼동하지 마세요.
• Kubernetes에서는 서비스명을 vllm로 짓지 않도록 주의하세요.

더 알아보기 (Learn more)

• 엔진 인자 (Engine Arguments)
• 서브 인자 (Serve Arguments)
• 구성 옵션 (Configuration Options)
• 메모리 절약 (Conserving Memory)