NIM LLM 빠른 시작

NIM LLM 빠른 시작

NIM 컨테이너 하나만 띄우면 명령 몇 줄로 LLM 추론을 시작할 수 있어요. 다만 그 전에 하드웨어·드라이버·런타임 같은 사전 조건을 만족하고, Docker에 로그인해서 이미지를 pull하고, 캐시 경로를 설정해 두어야 해요. 이 페이지에서는 모델 프로필 선택, 컨테이너 실행, API 호출까지의 흐름을 빠르게 훑어볼게요.

모델을 고르는 지점에서 NIM은 감지된 하드웨어(GPU 수나 아키텍처 같은 것)에 맞춰 가장 최적의 모델 프로필을 자동 선택해요. 직접 재정의하고 싶다면 NIM_MODEL_PROFILE 환경 변수로 지정하면 돼요.

출처: NVIDIA NIM for LLM — Quickstart

컨테이너 실행

시작에 앞서 prerequisites를 충족하고 installation·configuration 단계(API 키 설정, Docker 로그인, 이미지 pull, LOCAL_NIM_CACHE 설정)를 거쳤다고 가정할게요. 로컬 캐시 디렉토리를 마운트해 두면 이후 재시작 때 모델을 다시 내려받지 않아요.

이미지 태그는 컨테이너 타입과 백엔드에 따라 달라져요. ${NIM_LLM_IMAGE}와 ${NIM_LLM_MODEL_FREE_IMAGE}를 모델·GPU에 맞는 vLLM 또는 SGLang 이미지·태그로 설정하세요. 지원 매트릭스에서 정확한 이미지와 버전을 확인할 수 있어요.

모델 특화 NIM(모델 전용 컨테이너)은 다음처럼 실행해 모델을 내려받아요. NGC API 키를 만들지 않았다면 -e NGC_API_KEY=$NGC_API_KEY 줄은 빼도 돼요.

export NIM_LLM_IMAGE=nvcr.io/nim/meta/llama-3.1-8b-instruct:2.0.10
docker run --gpus all \
  -e NGC_API_KEY=$NGC_API_KEY \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE}

모델 무관 NIM은 Hugging Face 토큰으로 인증해 모델을 다운로드해요.

export NIM_LLM_MODEL_FREE_IMAGE=nvcr.io/nim/nvidia/model-free-nim:2.0.10
docker run --gpus all \
  -e NIM_MODEL_PATH=$NIM_MODEL_PATH \
  -e NIM_SERVED_MODEL_NAME="openai/gpt-oss-20b" \
  -e HF_TOKEN=$HF_TOKEN \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -p 8000:8000 \
  ${NIM_LLM_MODEL_FREE_IMAGE}

참고: NGC API 키는 Production Branch(PB) 모델이나 NIM LLM 2.0.10 이전에 릴리스된 NIM 다운로드에만 필요해요. PB 릴리스는 모델 이름에 -pb<버전> 접미사가 붙어요(예: llama-3.1-8b-instruct-pb6). 미리 내려받은 로컬 모델이나 프라이빗 클라우드 모델을 서빙하려면 Model Downloads 문서를 보세요.

API와 상호작용

주요 추론 엔드포인트는 세 가지예요.

  • Chat Completions: /v1/chat/completions
  • Text Completions: /v1/completions
  • Responses: /v1/responses

세 엔드포인트 모두 스트리밍을 지원해요.

모델 이름 찾기

아래 예시의 "model" 값은 NIM 컨테이너가 서빙하는 모델 이름으로 바꿔야 해요. 먼저 models 엔드포인트를 질의해서 찾아보세요.

curl -s http://localhost:8000/v1/models

응답의 id 필드가 요청에 쓸 모델 이름이에요. 모델 전용 NIM이면 모델 식별자(예: meta/llama-3.1-8b-instruct)와 일치하고, 모델 무관 NIM이면 NIM_SERVED_MODEL_NAME 환경 변수로 정한 이름을 써요(미설정 시 ga-model-free-nim).

채팅 완성 요청

서버가 실행 중이면 chat completion 엔드포인트로 요청을 보내요.

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/llama-3.1-8b-instruct",
    "messages": [{"role": "user", "content": "Hello! How are you?"}],
    "max_tokens": 100
  }'

health 엔드포인트 확인

컨테이너가 요청을 받을 준비가 됐는지 health 엔드포인트로 확인할 수 있어요. 기본 포트는 8000이고, NIM_HEALTH_PORT를 설정했다면 그 포트를 쓰세요.

# liveness - 서버 실행 여부
curl -v http://localhost:8000/v1/health/live

# readiness - 모델이 완전히 로드되어 추론 준비 완료 여부
curl -v http://localhost:8000/v1/health/ready

정상이면 각각 200 OK와 함께 "status": "live" / "status": "ready" 응답이 와요.

스트리밍

요청 본문에 "stream": true를 추가하면 생성되는 대로 점진적으로 응답을 받을 수 있어요. /v1/chat/completions, /v1/completions, /v1/responses 모두 지원해요.

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/llama-3.1-8b-instruct",
    "messages": [{"role": "user", "content": "Write a short poem about a robot."}],
    "max_tokens": 100,
    "stream": true
  }'

스트리밍을 켜면 API가 Server-Sent Events(SSE) 시퀀스를 반환해요. 각 청크는 data JSON 객체를 담고, 마지막엔 data: [DONE] 메시지로 끝나요.

더 알아보기