NIM LLM API 레퍼런스

NIM LLM API 레퍼런스

모델을 배포하고 나면 이제 어떤 엔드포인트로 어떻게 요청을 보내야 할지가 핵심이 돼요. NIM LLM은 vLLM이 제공하는 OpenAI 호환 추론 API를 그대로 노출하면서, 그 위에 NIM 전용 관리 엔드포인트를 더해 줘요. 덕분에 OpenAI API에 익숙한 클라이언트라면 코드를 크게 바꾸지 않고 연결할 수 있어요.

추론 엔드포인트는 vLLM 추론 백엔드가, 관리 엔드포인트는 NIM 미들웨어 레이어나 nginx 프록시가 처리해요. 전체 요청·응답 스키마와 파라미터는 vLLM OpenAI-Compatble Server 문서나 실행 중인 컨테이너의 /docs(OpenAPI 탐색기)에서 확인할 수 있어요.

출처: NVIDIA NIM for LLM — API Reference

추론 엔드포인트

핵심 추론 경로는 다음과 같아요.

엔드포인트 설명
POST /v1/chat/completions 메시지 히스토리를 가진 다중 턴 채팅 완성. 스트리밍·도구 호출 지원
POST /v1/completions 단일 턴 텍스트 완성
POST /v1/responses 모델 응답 생성 (OpenAI Responses API)
POST /v1/messages Anthropic 호환 messages 엔드포인트
GET /v1/models 현재 로드되어 추론에 사용 가능한 모델 목록
POST /tokenize 입력 텍스트를 토큰 ID로 변환
POST /detokenize 토큰 ID를 텍스트로 변환

Anthropic 호환 요청 문법은 Anthropic Messages API 문서를 참고하세요.

관리 엔드포인트

NIM 컨테이너 전용으로 제공되는 관리 경로예요.

엔드포인트 설명
GET /v1/health/live 컨테이너가 실행 중이면 200 OK
GET /v1/health/ready 모델이 로드되어 추론 요청을 받을 준비가 되면 200 OK
GET /v1/metrics Prometheus 호환 메트릭 (요청 지연, 처리량, 큐 깊이, GPU 사용률)
GET /v1/version NIM 릴리스 버전과 OpenAPI 스펙 버전
GET /v1/metadata 활성 모델 프로필 ID·이름을 포함한 배포 메타데이터
GET /v1/manifest 사용 가능한 프로필과 설정을 설명하는 전체 모델 매니페스트
GET /v1/license 실행 중인 NIM 컨테이너의 라이선스 정보

사용 예시

아래 예시는 ${MODEL_NAME} 셸 변수를 써요. 배포의 모델 ID를 찾으려면 models 엔드포인트를 질의하고, 이후 명령에 쓸 수 있게 export 하세요.

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

export MODEL_NAME="meta/llama-3.1-8b-instruct"

모델 ID는 NIM_SERVED_MODEL_NAME을 명시적으로 설정했을 때 그 값과 일치해요. 설정하지 않으면 NIM이 자동으로 이름을 유도해요.

Chat Completions

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"${MODEL_NAME}\", \"messages\": [{\"role\": \"user\", \"content\": \"What is GPU computing?\"}], \"max_tokens\": 256}"

스트리밍 응답을 받으려면 stream: true를 추가하면 돼요.

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"${MODEL_NAME}\", \"messages\": [{\"role\": \"user\", \"content\": \"Explain transformers briefly.\"}], \"max_tokens\": 256, \"stream\": true}"

Completions

curl -s http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"${MODEL_NAME}\", \"prompt\": \"Once upon a time\", \"max_tokens\": 64}"

Responses (OpenAI Responses API)

curl -s http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"${MODEL_NAME}\", \"input\": \"Explain the theory of relativity in one sentence.\"}"

토크나이즈·디토크나이즈

# 텍스트 → 토큰 ID
curl -s http://localhost:8000/tokenize \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"${MODEL_NAME}\", \"prompt\": \"Hello world\"}"

# 토큰 ID → 텍스트
curl -s http://localhost:8000/detokenize \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"${MODEL_NAME}\", \"tokens\": [9906, 1917]}"

Health·메타데이터 확인

# Liveness (컨테이너 실행)
curl -s http://localhost:8000/v1/health/live

# Readiness (모델 로드·추론 준비)
curl -s http://localhost:8000/v1/health/ready

# 배포 메타데이터·버전
curl -s http://localhost:8000/v1/metadata
curl -s http://localhost:8000/v1/version

더 알아보기