NIM LLM 환경 변수

NIM LLM 환경 변수

배포를 조정하다 보면 "이 동작은 어느 변수로 바꿀까"가 늘 따라다녀요. NIM LLM이 지원하는 환경 변수를 한자리에 정리해 두면, 모델 구성부터 서버 포트, LoRA 어댑터, 캐시 경로까지 한눈에 찾을 수 있어요. 변수는 컨테이너 실행 시 -e 플래그로 설정해요.

모델 경로는 hf://, ngc://, modelscope:// 같은 원격 저장소 접두사를 지원하고, 병렬 처리(텐서·파이프라인 병렬)나 서빙 모델 이름 등 추론 서빙과 직결된 값들을 다뤄요.

출처: NVIDIA NIM for LLM — Environment Variables

기본 실행 예시

docker run -d --rm --gpus all \
  -p 8000:8000 \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -e NIM_MODEL_PATH=hf://meta-llama/Llama-3.1-8B-Instruct \
  -e NIM_SERVER_PORT=8000 \
  -e NIM_LOG_LEVEL=INFO \
  -e NGC_API_KEY \
  -e HF_TOKEN \
  <image>

모델 구성

모델 선택과 로딩, 런타임 동작을 제어하는 변수들이에요.

  • NIM_MODEL_PROFILE (string, 기본 auto): 쓰려는 모델 프로필을 선택해요. 프로필은 주어진 GPU 구성에 대해 검증된 모델 변형·정밀도·병렬 설정 조합이에요. 컨테이너 안에서 list-model-profiles를 실행하면 사용 가능한 프로필과 ID를 볼 수 있어요.
  • NIM_MODEL_PATH (string, 기본 None): 모델 소스 URI 또는 로컬 파일시스템 경로. hf://, ngc://, modelscope:// 접두사나 로컬 디렉토리 경로를 받아요. 설정하면 내장 매니페스트 대신 이 URI로 런타임 매니페스트를 생성해요.
  • NIM_SERVED_MODEL_NAME (string, 기본 None): API 응답에서 반환되는 서빙 모델 이름을 재정의해요. 설정하면 /v1/models 엔드포인트와 응답 메타데이터가 기본 모델 식별자 대신 이 이름을 써요.
  • NIM_MAX_MODEL_LEN (양수 int, 기본 None): 모델의 최대 시퀀스 길이(컨텍스트 윈도우)를 재정의해요. 모델이 훈련된 최대치보다 큰 값은 오류를 일으킬 수 있어요.
  • NIM_TENSOR_PARALLEL_SIZE (양수 int, 기본 None): 텐서 병렬 처리 차수. 모델 레이어를 지정된 수의 GPU에 나눠 추론해요.
  • NIM_PIPELINE_PARALLEL_SIZE (양수 int, 기본 None): 파이프라인 병렬 처리 차수. 모델 스테이지를 지정된 수의 GPU에 분산해요.
  • NIM_NUM_COMPUTE_NODES (int, 기본 None): 멀티노드 추론의 총 컴퓨트 노드 수. 리더·워커 노드 모두에 총 노드 수(리더+워커)를 설정해요.
  • NIM_REPOSITORY_OVERRIDE (string, 기본 None): 모델 다운로드를 외부 저장소로 리다이렉트하면서 NIM 매니페스트 의미는 유지해요. 프로필 선택엔 내장 매니페스트를 쓰되, 모델 파일은 재정의된 소스에서 가져와요.
  • NIM_DISABLE_MODEL_DOWNLOAD (bool, 기본 False): 컨테이너 시작 시 모델 다운로드를 건너뛰어요. 사전 스테이징된 공유 파일시스템을 쓰는 멀티노드 배포에서 리더만 다운로드할 때 유용해요.
  • NIM_TRUST_CUSTOM_CODE (bool, 기본 False): 커스텀 모델 코드의 동적 모듈 로딩을 허용해요. 커스텀 토크나이저나 모델링 파일을 가진 모델에 필요해요.

서버

  • NIM_SERVER_PORT (int, 기본 None): 외부 노출 HTTP API 서버 포트.
  • NIM_HEALTH_PORT (int, 기본 None): 프록시 health 엔드포인트(/v1/health/live, /v1/health/ready) 포트. 미설정 시 NIM_SERVER_PORT를 따라가요.

LoRA·PEFT

  • NIM_PEFT_SOURCE (string, 기본 None): LoRA 어댑터 소스 URI(로컬 경로 또는 NGC URI). 미설정 시 LoRA 비활성.
  • NIM_PEFT_REFRESH_INTERVAL (양수 int, 기본 None): 동적 LoRA 워처의 폴링 간격(초). 설정하면 NIM이 PEFT 소스에 새 어댑터가 있는지 주기적으로 확인해요.
  • NIM_PEFT_API_TIMEOUT_SECS (양수 float, 기본 30.0): 동적 LoRA 어댑터 API 호출 타임아웃(초).

모델 캐시

  • NIM_CACHE_PATH (string, 기본 /opt/nim/.cache): NIM 컨테이너 안의 모델·아티팩트 캐시 디렉토리 경로.
  • NIM_CACHE_PROBE_TIMEOUT (int, 기본 60): 시작 시 아티팩트 캐시 도달 가능성 프로브의 데드라인(초). NIM_CACHE_PATH가 닿을 수 없는 NFS/CIFS/FUSE 마운트에 있으면 OS TCP 타임아웃까지 기다리지 않고 이 데드라인 안에 종료해요.

로깅

  • NIM_LOG_LEVEL (string, 기본 None): NIM 로그 출력의 상세도를 제어. 표준 Python 로깅 레벨(DEBUG, INFO, WARNING, ERROR, CRITICAL)을 받아요.
  • NIM_JSONL_LOGGING (bool, 기본 False): 구조화된 JSON Lines(JSONL) 로그 출력을 켜요.

쓰기 가능 경로 (Writable Paths)

기본적으로 컨테이너는 /opt/nim 아래에 씁니다. 이 변수들은 그 쓰기 위치를 옮겨서, /opt/nim을 읽기 전용으로 마운트할 수 있게 해 줘요(Kubernetes의 securityContext.readOnlyRootFilesystem: true 같은 불변 루트 정책에 대응).

  • NIM_WRITABLE_ROOT (string, 기본 /opt/nim): 런타임 쓰기의 총괄 루트 — nginx 상태, 스크래치(TMPDIR), $HOME 기반 GPU/라이브러리 캐시, 생성된 미들웨어 설정. 이 변수 하나로 모두 옮겨요. NIM_CACHE_PATH나 NIM_MANIFEST_PATH는 옮기지 않아요.
  • NIM_NGINX_DIR (string, 기본 ${NIM_WRITABLE_ROOT}/nginx): nginx 런타임 상태(생성된 nginx.conf, nginx.pid, *_temp 디렉토리, 스니펫 설정, access/error 로그)를 담는 디렉토리. nginx 상태만 tmpfs에 두고 캐시는 영구 볼륨에 두고 싶을 때 유용해요.
  • NIM_MIDDLEWARE_CONFIG_PATH (string, 기본 ${NIM_WRITABLE_ROOT}/generated_configs/middleware_config.json): 시작 시 생성되어 /v1/metadata 제공에 다시 읽히는 미들웨어 설정 파일 경로.

주의: readOnlyRootFilesystem: true는 /etc/passwd를 고정시켜서, SCC가 할당한 임의 UID를 그 안에 매핑하지 못해요. getpwuid()로 캐시 디렉토리를 풀어내는 라이브러리가 import 시 KeyError: 'getpwuid(): uid not found: <uid>'로 실패할 수 있어요. 임의 UID를 할당하는 플랫폼(OpenShift SCC)이라면 이미지 nim 사용자와 일치하는 runAsUser로 실행하거나, readOnlyRootFilesystem을 두지 말고 /opt/nim만 읽기 전용으로 마운트하는 걸 권장해요.

$HOME·$TMPDIR을 담는 볼륨은 exec로 마운트돼야 해요. Triton과 vLLM은 런타임에 커널을 컴파일하고 dlopen()으로 결과 공유 객체를 $HOME/.triton, $HOME/.cache/vllm에서 로드하고, TorchInductor는 $TMPDIR에서 객체를 빌드·로드해요. noexec 마운트에서는 mmap(PROT_EXEC)이 실패해 모델이 로드되지 않아요.

더 알아보기