NIM LLM 아키텍처
NIM LLM 아키텍처
NIM LLM을 컨테이너로 띄우면 내부에서 무슨 일이 벌어지는지 궁금할 때가 있어요. NIM LLM은 사실 vLLM을 위한 엔터프라이즈 오케스트레이션 레이어예요. vLLM을 프로덕션에 쓸 수 있는 컨테이너로 포장하고, 정돈된 모델 프로필과 검증된 설정, health 관리·관측성·보안 강화 같은 엔터프라이즈 기능을 더해 줘요.
컨테이너 안에서는 두 개의 프로세스가 돼요. 하나는 모델을 로드하고 GPU 추론을 실행하며 OpenAI 호환 API를 노출하는 vLLM 추론 백엔드, 다른 하나는 외부 포트에서 liveness, 모델 인지 readiness, 요청 라우팅, TLS 종료, CORS 처리를 맡는 얇은 프록시예요.
주요 설계 원칙
이 아키텍처는 몇 가지 원칙 위에 서 있어요.
- OpenAI 호환 API: 프록시가 스트리밍을 포함해 OpenAI 엔드포인트의 drop-in 대체재 역할을 해요. 기존 클라이언트 코드를 바꾸지 않고 그대로 쓸 수 있어요.
- 프로덕션 준비 health 프로브: liveness와 readiness를 분리해서, 오케스트레이터가 "컨테이너가 떠 있는 상태"와 "실제로 추론을 제공할 준비가 된 상태"를 구분해요. 기본적으로 이 health 엔드포인트는
NIM_SERVER_PORT를 쓰고,NIM_HEALTH_PORT를 설정하면 전용 리스너로 옮겨요. - 기본 보안: 명시적으로 설정한 엔드포인트만 노출되고, 나머지 경로는
404 NotFound를 반환해요. TLS 종료와 CORS는 프록시 레이어에서 설정할 수 있어요. - Fail-fast 감독: 두 프로세스를 모두 감시해서 둘 중 하나라도 종료되면 컨테이너가 깔끔하게 내려가고 오케스트레이터가 다시 스케줄링해요.
컨테이너 시작 순서
컨테이너가 시작되면 다음 순서로 진행돼요.
- 프록시 시작: 프록시가
NIM_SERVER_PORT(기본 8000)에서 듣기 시작해요. 기본적으로/v1/health/live와/v1/health/ready도 이 포트에서 제공돼요. - 모델 프로필 선택: NIM이 감지한 GPU 하드웨어에 맞는 모델 프로필을 고르는데, 필요하면
NIM_MODEL_PROFILE로 재정의할 수 있어요. - 모델 다운로드: 모델 파일을 로컬 캐시(
NIM_CACHE_PATH)로 가져와요. 이미 캐시돼 있으면 건너뛰어요. - vLLM 실행: 추론 백엔드가 포트 8001(루프백 전용이라 컨테이너 밖으로 노출 안 됨)에서 시작돼요. 설정은 프로필 기본값, 환경 변수, passthrough 인자를 합쳐 결정돼요.
- readiness 보고: 모델 로드 후 nginx가 백엔드
/health를 확인하고/v1/health/ready가200 OK를 반환하기 시작해요. 그러면 오케스트레이터가 트래픽을 라우팅해요.
SIGTERM(예: docker stop)이 오면 NIM은 먼저 vLLM을 우아하게 종료한 뒤 프록시를 내려요.
추론과 엔드포인트 라우팅
NIM은 vLLM의 OpenAI 호환 API를 프록시해요. 주요 엔드포인트는 다음과 같아요.
| 라우트 | 분류 | 설명 |
|---|---|---|
/v1/chat/completions |
추론 | 메시지 히스토리를 가진 다중 턴 채팅 완성 |
/v1/completions |
추론 | 단일 턴 텍스트 완성 |
/v1/embeddings |
추론 | 벡터 임베딩 생성 |
/v1/models |
관리 | 추론에 사용 가능한 모델 목록 |
/v1/health/live |
health | liveness 프로브, 기본 NIM_SERVER_PORT에서 서빙 |
/v1/health/ready |
health | readiness 프로브, 백엔드 /health 확인 기반 |
| 그 외 모든 경로 | – | 404 NotFound로 거부 |
전체 지원 엔드포인트와 요청·응답 스키마, 사용 예시는 API 레퍼런스에서 확인할 수 있어요.
포트 구성
NIM은 기본적으로 이중 포트 구조예요. 외부 포트(기본 8000)는 프록시가 추론·관리 트래픽을 받는 곳이고, vLLM 백엔드는 8001에서 네이티브 /health 엔드포인트를 제공해요. NIM_HEALTH_PORT를 설정하면 nginx가 /v1/health/live·/v1/health/ready를 추가 포트로 노출해요. 외부 포트가 8000과 충돌하면 NIM_SERVER_PORT로 바꿀 수 있어요.
관측성
NIM은 세 가지 관측 표면을 제공해요.
- Health 프로브:
/v1/health/live는 컨테이너가 떠 있는지(백엔드 무관),/v1/health/ready는 모델이 로드되어 추론을 제공할 준비가 됐는지 확인해요. - 메트릭:
/v1/metrics에서 Prometheus 호환 메트릭(요청 지연, 처리량, GPU 사용률)을 노출해요. - 로깅·트레이싱: 설정 가능한 로그 레벨, 구조화된 JSON Lines 출력,
X-Request-Id·Traceparent헤더 포워딩을 지원해요.
보안
프록시 레이어에서 TLS 종료(상호 TLS 포함)와 CORS 정책을 설정할 수 있어요. 상세 동작과 예시는 고급 설정에서, SSL/TLS·CORS 변수 전체는 환경 변수 페이지에서 확인할 수 있어요.