NIM LLM 고급 설정

같은 설정 값이 CLI 인자와 환경 변수, 런타임 설정 파일, 모델 프로필 태그 등 여러 곳에 흩어져 있으면 어느 것이 이기는지 헷갈리기 쉬워요. NIM LLM은 이런 값들을 계층적으로 해석하는데, 명확한 우선순위와 출처 추적(provenance)까지 제공해요. 이 페이지에서는 구성 시스템의 우선순위와 고급 배포 시나리오에서의 활용법을 다뤄요.

기본적인 모델 경로·캐시·로깅 설정은 환경 변수 문서를, vLLM 전용 CLI 인자는 vLLM CLI 문서를 참고하세요. 여기서는 그보다 복잡한 구성이 필요한 상황을 중심으로 설명할게요.

출처: NVIDIA NIM for LLM — Advanced Configuration

구성 우선순위

구성 값은 여러 소스에서 해석되는데, 우선순위는 높은 순으로 이래요.

우선순위	소스	설명
1 (최고)	CLI 인자	`nim-serve` 뒤에 넘기는 인자. 예: `nim-serve --tensor-parallel-size 4`
2	Passthrough 인자	`NIM_PASSTHROUGH_ARGS` 환경 변수, CLI 스타일로 해석됨
3	환경 변수	vLLM 인자에 매핑되는 NIM 전용 `NIM_*` 변수
4	런타임 설정	모델 워크스페이스의 `runtime_config.json`
5	프로필 태그	nimlib 프로필 메타데이터의 값(예: `tp`, `pp`)
6 (최저)	NIM 기본값	다른 소스가 값을 설정하지 않을 때만 적용

우선순위가 높은 소스가 낮은 소스를 덮어써요. 같은 파라미터가 여러 소스에 있으면 가장 높은 우선순위 값이 이겨요. 예외는 JSON 객체 값인데, 이건 교체가 아니라 합성(compose) 돼요. 예를 들어 --compilation-config가 runtime_config.json과 명령줄 양쪽에 있으면 두 객체를 재귀적으로 합치고, 양쪽이 같은 키를 set하면 우선순위 높은 쪽 값이 이겨요. 엄격 모드에서는 양쪽이 다른 값을 set한 키가 치명적 충돌로 간주되고, 겹치지 않는 키 합성만 허용돼요.

구성 소스

각 소스를 하나씩 볼게요.

CLI 인자

nim-serve 뒤에 오는 명령줄 인자는 vLLM CLI 인자 형식을 써요.

docker run --gpus all \
  -e NIM_MODEL_PATH=hf://meta-llama/Llama-3.1-8B-Instruct \
  -p 8000:8000 \
  ${NIM_LLM_MODEL_FREE_IMAGE}:2.0.10 \
  nim-serve --tensor-parallel-size 4 --enable-prefix-caching --gpu-memory-utilization 0.9

vLLM은 불리언 플래그에 Python의 argparse.BooleanOptionalAction을 써요. --enable-prefix-caching은 True, --no-enable-prefix-caching은 False로 설정해요. NIM_PASSTHROUGH_ARGS와 직접 CLI 인자가 같은 파라미터를 set하면 직접 CLI 인자가 우선하고, 서로 모순된 인자(예: --enable-xyz 후 --no-enable-xyz)가 있으면 마지막 인자가 이겨요.

Passthrough 인자 (`NIM_PASSTHROUGH_ARGS`)

Kubernetes 같은 오케스트레이터에서 직접 CLI 인자를 넘기기 어려운 환경이라면, 환경 변수로 CLI 스타일 인자를 전달해요.

export NIM_PASSTHROUGH_ARGS="--tensor-parallel-size 4 --enable-prefix-caching --gpu-memory-utilization 0.9"

모든 vLLM CLI 인자, 불리언 플래그, shlex.split() 기반의 셸 스타일 따옴표를 지원해요. Kubernetes 예시를 보면:

env:
  - name: NIM_PASSTHROUGH_ARGS
    value: "--tensor-parallel-size 4 --enable-prefix-caching"

JSON 값을 넘길 때는 이런 형식을 써요.

export NIM_PASSTHROUGH_ARGS="--compilation-config '{\"pass_config\": {\"fuse_allreduce_rms\": false}}'"

NIM 환경 변수

NIM은 자주 쓰는 파라미터에 대응하는 작은 환경 변수 세트를 정의해요. 이 변수들은 안정적이고 NIM 전용인 인터페이스예요.

NIM 환경 변수	vLLM 인자	타입	기본값
`NIM_TENSOR_PARALLEL_SIZE`	`--tensor-parallel-size`	int	`1`
`NIM_PIPELINE_PARALLEL_SIZE`	`--pipeline-parallel-size`	int	`1`
`NIM_EXPERT_PARALLEL_SIZE`	값이 `1`보다 크면 `--enable-expert-parallel` 발생	int	`1`
`NIM_DATA_PARALLEL_SIZE`	`--data-parallel-size`	int	`1`
`NIM_MAX_MODEL_LEN`	`--max-model-len`	int	auto
`NIM_TRUST_CUSTOM_CODE`	`--trust-remote-code`	bool	`false`
`NIM_DISABLE_CUDA_GRAPH`	`--enforce-eager`	bool	`false`

전용 NIM 환경 변수가 없는 vLLM 인자는 NIM_PASSTHROUGH_ARGS를 쓰면 돼요. SGLang 백엔드를 쓸 때는 같은 변수가 SGLang의 CLI 플래그에 매핑돼요(예: NIM_TENSOR_PARALLEL_SIZE → --tp-size, NIM_PIPELINE_PARALLEL_SIZE → --pp-size).

런타임 설정 (runtime_config.json)

모델 워크스페이스에 runtime_config.json 파일을 두면 NIM이 자동으로 읽어요.

{
  "tensor_parallel_size": 2,
  "enable_prefix_caching": true,
  "max_model_len": 8192
}

알 수 없는 키는 vLLM에 그대로 전달돼요. 이 파일은 NIM_PASSTHROUGH_ARGS 키도 받는데, 환경 변수와 같은 규칙으로 해석돼요.

{
  "NIM_PASSTHROUGH_ARGS": "--max-model-len 8192 --enable-prefix-caching --no-enable-chunked-prefill"
}

파일 안에서 임베디드 문자열과 플랫 키가 만나면 두 규칙이 적용돼요. 명시적 플랫 키가 이기고, 파싱 방식의 엄격성은 폼에 따라 달라져요.

프로필 태그

모델 프로필은 병렬 처리를 구성하는 메타데이터 태그를 포함해요. 프로필 선택 시 자동으로 추출돼요.

프로필 태그	vLLM 파라미터
`tp`	`tensor_parallel_size`
`pp`	`pipeline_parallel_size`

예를 들어 vllm-fp8-tp2-pp1 프로필은 프로필 우선순위에서 tensor_parallel_size=2, pipeline_parallel_size=1로 설정돼요.

NIM 기본값

아래 기본값은 다른 소스가 설정하지 않을 때만 적용돼요.

파라미터	기본값
`tensor_parallel_size`	`1`
`pipeline_parallel_size`	`1`

재정의 경고와 엄격 모드

우선순위가 높은 소스가 낮은 소스의 값을 덮어쓰면 NIM이 경고를 로그해요.

WARNING: Config override: 'tensor_parallel_size' changed from 2 (RUNTIME) to 8 (CLI)

NIM_STRICT_ARG_PROCESSING=true로 설정하면 이런 재정의 경고를 오류로 취급해요. CI/CD 파이프라인에서 구성 충돌을 잡거나, 프로덕션에서 구성을 결정적으로 만들고 싶을 때 유용해요. 설정 후 비기본 소스 사이에서 구성 충돌이 생기면 컨테이너가 오류로 종료돼요.

--dry-run을 nim-serve와 함께 쓰면 서버를 시작하지 않고 완전히 해석된 구성과 결과 vLLM 인자를 출처와 함께 출력해요.

거부되는 인자

nginx 프록시나 시스템 컴포넌트가 관리하는 인자는 NIM 컨테이너에서 차단돼요. 넘기면 경고를 남기고 무시해요.

거부 인자	이유	NIM 대안
`--host`	네트워킹이 nginx가 관리	—
`--port`	포트가 nginx가 관리	`NIM_SERVER_PORT` (외부)
`--ssl-keyfile`	SSL/TLS가 nginx가 관리	`NIM_SSL_MODE`, `NIM_SSL_KEY_PATH`

TLS·CORS 구성

TLS는 nginx 프록시가 처리해요. NIM_SSL_MODE=TLS로 켜고 NIM_SSL_KEY_PATH/NIM_SSL_CERTS_PATH로 인증서 경로를 지정하면 됩니다.

docker run --gpus all \
  -e NIM_MODEL_PATH=hf://meta-llama/Llama-3.1-8B-Instruct \
  -e NIM_SSL_MODE=TLS \
  -e NIM_SSL_KEY_PATH=/certs/server.key \
  -e NIM_SSL_CERTS_PATH=/certs/server.crt \
  -v /path/to/certs:/certs:ro \
  -p 8000:8000 \
  ${NIM_LLM_MODEL_FREE_IMAGE}:2.0.10

CORS도 nginx 레이어에서 처리하고, NIM_CORS_ALLOW_ORIGINS(기본 *), NIM_CORS_ALLOW_METHODS, NIM_CORS_ALLOW_HEADERS, NIM_CORS_EXPOSE_HEADERS, NIM_CORS_MAX_AGE(기본 3600) 변수로 제어해요. vLLM의 --allowed-origins·--allowed-methods·--allowed-headers 인자는 CORS가 nginx 레이어에서 관리되므로 NIM에서 거부되니, NIM_CORS_* 변수를 쓰세요.

더 알아보기

변수 전체: 환경 변수
기본 실사용: 빠른 시작
vLLM CLI 상세: vLLM CLI 문서

NIM LLM 고급 설정