Serving

AI 모델을 NPU/GPU 기반 추론 서비스로 배포하고 관리하는 방법을 안내합니다.

Serving 목록

좌측 사이드바에서 Development > Serving을 클릭합니다.

Connect 버튼을 클릭하면 배포한 서비스의 엔드포인트가 새 탭으로 열립니다. 추론 엔드포인트 URL은 https://<deployment-name>-<project>.<base-domain> 형식의 서브도메인 기반이며, 이 URL에 추론 프레임워크의 API 경로(예: /v1/chat/completions)를 붙여 외부에서 모델 추론 요청을 보낼 수 있습니다.

예를 들어 tutorial-npu-serving Serving이 public-space 프로젝트에 있고 인증 없이 접근 가능한 환경이라면 다음 명령으로 바로 테스트할 수 있습니다.

curl -X POST 'https://tutorial-npu-serving-public-space.nufi.com/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -d '{"model": "model-name", "messages": [{"role": "user", "content": "안녕하세요"}]}'

상태

상태	설명	비정상 대응
Ready	모든 Pod이 Ready 상태. 서비스 정상 운영 중	—
Starting	Pod이 시작 중. 모델 로딩 등으로 아직 Ready가 아닌 상태	잠시 대기하세요. 오래 지속되면 로그를 확인하세요.
Degraded	일부 Pod만 Ready. 요청은 처리되지만 전체 성능이 저하됨	실패 Pod의 로그 및 이벤트를 확인하세요.
Error	하나 이상의 Pod이 CrashLoopBackOff 등 오류 상태	Status 컬럼 클릭 → popover에서 failureReason 및 로그 확인
Pending	Pod이 스케줄되지 않음. 리소스 부족 또는 이미지 Pull 실패	클러스터 리소스 현황 및 이미지 설정을 확인하세요.
Scaled Down	Replica가 0으로 축소된 상태	필요 시 Replicas를 1 이상으로 변경하세요.

Status 컬럼 hover 또는 클릭 시 Pod 상태 popover가 표시됩니다. popover에는 주 에러 reason, Ready 카운트, 실패 Pod 목록과 각 Pod의 View logs 링크(새 탭, Logs 탭으로 이동)가 포함됩니다.

---

Serving 생성

Create 버튼을 눌러 생성 페이지로 이동합니다. 생성은 3단계로 진행됩니다.

Step 1. 기본 정보

필드	설명	필수
서비스 이름	Serving 이름 (소문자, 숫자, 하이픈, 최대 63자)	✓
설명	Serving 설명	-
템플릿 선택	추론 프레임워크 템플릿 선택 (vLLM / 사용자 지정)	✓

서비스 이름 규칙

• 소문자 영문, 숫자, 하이픈(-) 사용 가능
• 하이픈으로 시작하거나 끝날 수 없음
• 최대 63자 (Kubernetes 제한)

예시: my-model-v1, llm-server-prod

Step 2. 상세 설정

공통 설정:

필드	설명	기본값 (사용자 지정)	기본값 (vLLM)
Image	컨테이너 이미지	-	vLLM 이미지
CPU	CPU 코어 수	0.5	4
Memory	메모리	1Gi	16Gi
Accelerator	가속기 유형	None	NVIDIA GPU
Accelerator Count	가속기 개수	1	1
Replicas	서비스 컨테이너 개수	1	1

Step 1에서 선택한 템플릿에 따라 공통 설정의 기본값이 자동으로 채워집니다.

지원 가속기

가속기	리소스 키	사용 가능 기능
NVIDIA GPU	nvidia.com/gpu	Lab, Serving
Furiosa RNGD	furiosa.ai/rngd	Lab, Serving

템플릿별 추가 설정:

vLLM

필드	설명	기본값
Model	모델 이름 또는 경로 (예: meta-llama/Llama-3.1-8B-Instruct)	-
Tensor Parallel Size	모델을 나눠 올릴 GPU 수	1
Data Type	모델 연산 숫자 표현 방식	Auto
Max Model Length	최대 처리 토큰 수 (입력+출력 합산)	-
Quantization	모델 정밀도 낮춰 메모리 절약	-
GPU 메모리 사용률	vLLM이 사용할 GPU 메모리 비율 (0.0~1.0)	0.9
Additional Arguments	vLLM 고급 설정 직접 입력	-

Additional Arguments에 입력할 수 있는 vLLM 옵션은 vLLM 공식 vllm serve CLI 인자에서 확인하세요.

사용자 지정

사용자 지정 템플릿은 공통 설정(Image, CPU, Memory, Accelerator, Replicas)과 고급 설정만 사용합니다. 컨테이너 이미지와 Command Override로 직접 제어합니다.

Data Volumes (선택):

Data Volumes는 기존 Volume(PVC)을 Serving 컨테이너에 마운트할 때 사용합니다. 하드코딩 볼륨(model-cache, dshm)은 시스템 기본 볼륨으로 읽기 전용으로 표시되며, 사용자가 생성한 PVC를 추가로 지정할 수 있습니다. Volume 생성과 관리 방법은 Volumes 문서를 참고하세요.

Volume 추가 버튼으로 사용자 PVC를 추가 마운트할 수 있습니다.

필드	설명
Volume	현재 프로젝트에 생성된 Volume을 선택합니다. 같은 Volume은 한 번만 선택할 수 있습니다.
Mount Path	컨테이너 안에서 Volume이 보일 경로입니다. 기본값은 /data/<volume-name>이며, 컨테이너 명령어와 모델 경로에서는 이 경로를 사용합니다.

고급 설정 (선택):

필드	설명	기본값
Inference Port	서비스 추론 포트	8000
Command Override	컨테이너 시작 명령어	-
Environment Variables	환경변수 (KEY=VALUE 또는 env file)	-
Transformer	전/후처리 사이드카 추가	-

Transformer는 전처리나 후처리가 필요할 때 사용합니다. Transformer를 켜면 같은 Pod 안에 사이드카 컨테이너가 추가되고, nufi-proxy가 해당 컨테이너의 /transform 엔드포인트를 호출합니다.

입력 항목	입력 내용	용도
Preprocessor	요청 전처리 컨테이너 이미지와 포트 (기본 8081)	클라이언트 요청을 추론 서버가 받는 형식으로 변환
Postprocessor	응답 후처리 컨테이너 이미지와 포트 (기본 8082)	추론 서버 응답을 클라이언트가 받는 형식으로 변환

Preprocessor나 Postprocessor가 필요할 때만 켜고, 실행할 컨테이너 이미지와 해당 컨테이너가 수신하는 포트를 입력합니다.

요청 흐름은 다음과 같습니다.

1. 클라이언트가 Serving 엔드포인트로 요청을 보냅니다.
2. nufi-proxy가 Preprocessor의 /transform으로 요청 정보를 전달합니다.
3. Preprocessor는 변환된 body를 반환하고, 추론 서버를 직접 호출하지 않습니다.
4. nufi-proxy가 변환된 body를 추론 서버로 전달합니다.
5. Postprocessor가 켜져 있으면 추론 서버 응답도 같은 방식으로 변환한 뒤 클라이언트에 반환합니다.

Step 3. 리뷰 & 배포

수정할 스펙이 있으면 Edit 버튼으로 수정합니다. 우측 하단 배포 버튼을 클릭하여 배포합니다.

---

Serving 상세 페이지

Serving 목록에서 항목을 클릭하면 상세 페이지로 이동합니다. Overview 탭 우측 상단의 Edit 버튼을 클릭하면 편집 모드로 전환되며, 변경 후 화면 하단의 Floating Save Bar에서 Save Changes 버튼을 클릭하여 적용합니다. Pod 재시작이 필요한 변경(이미지, 포트, 리소스, 볼륨 등)이 포함된 경우 확인 다이얼로그가 표시됩니다.

Overview

카드 구성

Overview 탭은 현재 Serving이 정상적으로 요청을 받을 수 있는지 확인하고, 생성 시 입력한 배포 스펙을 다시 보거나 수정하는 화면입니다.

카드	설명
Status	Serving 전체 상태 요약
Pods	Pod별 상태 테이블 — 실패 Pod 우선 정렬
Basic Information	Serving 이름과 설명
Container	추론 서버 컨테이너 이미지와 포트
Resources	CPU, Memory, Accelerator, Replicas
Command & Arguments	컨테이너 시작 명령어와 실행 인자
Environment Variables	컨테이너 환경변수
Volumes	PVC 마운트와 마운트 경로
Transformer	전/후처리 사이드카 설정

Status

Status는 Serving의 현재 운영 상태를 가장 먼저 확인하는 영역입니다. Ready Replicas는 준비된 Pod 수와 목표 Pod 수를 ready / desired 형식으로 보여주며, 두 값이 같으면 모든 복제본이 요청을 받을 준비가 된 상태입니다. Health는 Ready, Starting, Degraded, Error, Pending, Scaled Down 같은 상태를 요약해 표시합니다.

Auto Scaling이 켜져 있으면 최소/최대 Replica 범위도 함께 표시됩니다. 이 값은 현재 실행 중인 Pod 수가 자동으로 늘거나 줄 수 있음을 의미하므로, 실제 확장 정책은 Settings 탭의 스케일링 설정과 함께 확인합니다. Created At은 Serving이 생성된 시각입니다.

Pods

Serving은 하나 이상의 Kubernetes Pod으로 실행됩니다. Pods 섹션은 각 Pod이 어느 노드에서 실행 중인지, 준비 상태인지, 재시작이 반복되는지 확인하는 영역입니다. Status가 Starting, Degraded, Error, Pending처럼 정상 Ready가 아닐 때는 이 섹션에서 어느 Pod이 문제인지 먼저 확인합니다.

실패 Pod은 테이블 상단에 우선 정렬됩니다. Reason에는 Ready=false 또는 오류 상태의 원인이 표시되고, View logs 링크를 클릭하면 해당 Pod의 Logs 탭으로 이동해 추론 서버 로그를 확인할 수 있습니다.

컬럼	설명
Status	Pod의 현재 상태 (Running / Pending / CrashLoopBackOff 등)
Node	Pod이 스케줄된 노드 이름
Restarts	컨테이너 재시작 횟수
Age	Pod 생성 후 경과 시간
Reason	Ready=false 또는 오류 시 실패 원인 메시지
View logs	Ready=false이거나 restartCount > 0인 Pod에 표시되는 로그 링크. 클릭 시 새 탭에서 해당 Pod의 Logs 탭으로 이동

Basic Information

Basic Information은 Serving 이름과 설명을 표시합니다. Name은 생성 후 수정할 수 없고, Description은 Edit 모드에서 수정할 수 있습니다.

Container

Container는 실제 추론 서버를 실행하는 컨테이너 설정입니다. Image에는 vLLM 또는 Custom 서버 이미지가 표시되고, Inference Port에는 컨테이너 내부에서 추론 서버가 listen 하는 포트가 표시됩니다.

Connect 버튼으로 접근하는 외부 엔드포인트는 이 Serving으로 라우팅되며, 컨테이너 내부에서는 Inference Port로 요청이 전달됩니다. 이미지나 포트를 바꾸고 저장하면 Pod를 재시작합니다.

Resources

Resources는 Serving Pod 하나가 요청하는 컴퓨팅 자원과 실행 개수를 표시합니다. CPU와 Memory는 컨테이너에 할당할 기본 자원이고, Accelerator와 Accelerator Count는 GPU/NPU 같은 가속기 종류와 개수입니다. Replicas는 같은 Serving Pod을 몇 개 실행할지 나타냅니다.

리소스 값이 클러스터에 남아 있는 자원보다 크면 Pod이 Pending 상태가 될 수 있습니다. 처리량을 늘리려면 Replicas를 늘릴 수 있지만, 그만큼 CPU, Memory, Accelerator도 추가로 필요합니다.

Command & Arguments

Command & Arguments는 컨테이너가 시작될 때 실행되는 명령어와 인자를 표시합니다. vLLM 템플릿으로 생성한 Serving은 선택한 모델, dtype, tensor parallel size, additional arguments 같은 값이 실행 인자에 반영됩니다. Custom 템플릿은 사용자가 지정한 Command Override와 Arguments가 그대로 사용됩니다.

모델 경로, 포트, 런타임 옵션이 잘못되면 Pod은 실행되더라도 추론 서버가 정상 기동하지 않을 수 있습니다. Status나 Pods에서 오류가 보이면 이 섹션의 실행 인자와 로그를 함께 확인합니다.

Environment Variables

Environment Variables는 컨테이너에 주입되는 KEY=VALUE 설정입니다. 이미지에 고정하지 않는 API 주소, 토큰, 모델 서버 옵션, 프레임워크 설정을 환경변수로 전달할 때 사용합니다.

Edit 모드에서는 환경변수를 추가, 수정, 삭제할 수 있습니다. 값을 바꾸기 전에는 실제 컨테이너 명령어나 애플리케이션이 해당 환경변수를 참조하는지 확인합니다.

Volumes

Volumes는 Serving Pod에 마운트된 PVC와 마운트 경로를 표시합니다. NuFi가 기본으로 붙이는 시스템 볼륨(model-cache, dshm)과 사용자가 추가한 Data Volume을 구분해서 확인할 수 있습니다.

모델 파일, LoRA 어댑터, 설정 파일, 데이터 파일을 PVC에 두고 컨테이너에서 읽어야 한다면 이 섹션의 마운트 경로가 Command & Arguments 또는 환경변수에서 참조하는 경로와 일치해야 합니다. 볼륨 구성을 바꾸면 Pod 재시작이 필요할 수 있습니다.

Transformer

Transformer는 추론 요청 전처리 또는 응답 후처리를 담당하는 사이드카 설정입니다. Preprocessor를 켜면 요청이 추론 서버로 들어가기 전에 별도 컨테이너를 거칠 수 있고, Postprocessor를 켜면 추론 서버 응답이 외부로 나가기 전에 별도 컨테이너를 거칠 수 있습니다.

Transformer가 비활성화되어 있으면 추론 요청은 기본 추론 서버 컨테이너로 바로 전달됩니다. 활성화된 경우에는 사이드카 이미지, 포트, 환경변수도 Serving 동작에 영향을 주므로 Container 설정과 함께 확인합니다.

Metrics

우측 상단 시간 범위 버튼(1h / 6h / 24h)으로 그래프 기간을 조절할 수 있습니다.

카드	정보
Total Requests	전체 요청 횟수
Latency (P50 / P95 / P99)	현재 요청 응답 시간
RPS 그래프	초당 요청 개수 시계열
Latency 그래프	P50/P95/P99 응답 시간 시계열

Logs

추론 서버 컨테이너의 실행 로그를 출력합니다. Logs 탭은 현재 Serving의 App과 Instance를 기본 조회 대상으로 선택합니다.

항목	설명
String Match	로그 본문에 포함된 문자열로 결과를 좁힙니다. 비워 두면 문자열 필터 없이 전체 로그를 표시합니다.
시간 범위 / 새로고침	우측 상단의 시간 범위와 refresh 설정으로 조회 기간과 자동 갱신 주기를 조정합니다.

Async Queue

Settings에서 Async Queue를 활성화하면 비동기 요청 목록과 처리 결과를 조회합니다.

항목	설명
상태 필터	All / Pending / Processing / Completed / Failed
Queue Depth	현재 Queue에 쌓인 Task 수
Processing	현재 진행 중인 Task 수

특정 Task를 클릭하면 Request / Response 상세 정보를 확인할 수 있습니다.

비동기 요청 방법 — HTTP 요청 시 X-Async: true 헤더를 추가합니다.

curl -X POST 'https://<deployment-endpoint>/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Async: true' \
  -d '{"model": "모델명", "messages": [{"role": "user", "content": "안녕하세요"}]}'

Settings

추론 서버 스케일링, 헬스 체크, 트래픽 분배, 비동기 큐 등 Serving 운영에 필요한 설정을 변경합니다. 항목별 상세 설명은 아래 배포 고급 설정을 참고하세요.

배포 고급 설정

Serving 상세 페이지의 Settings 탭에서 추론 서버, 트래픽, Transformer를 설정합니다.

Inference Server

Inference Server 탭은 Serving Pod 수와 헬스 체크 엔드포인트를 조정하는 영역입니다.

Auto Scaling은 요청 부하에 따라 Pod 수를 자동으로 늘리거나 줄이는 기능입니다. 트래픽이 불규칙하거나 예측하기 어려운 서비스에 적합합니다. 고정된 수의 Pod를 항상 유지하려면 비활성화하고 Replicas만 조정하세요.

설정	설명	기본값
Replicas	레플리카 수 조정	1
Auto Scaling	트래픽 부하에 따라 Pod 수 자동 조절	Off
Readiness Endpoint	Pod가 트래픽 받을 준비 여부 확인 엔드포인트 (예: /health, /v1/models)	-
Liveness Endpoint	Pod 정상 동작 여부 확인. 반복 실패 시 자동 재시작 (예: /health, /healthz)	-

Auto Scaling 활성화 시 추가 설정:

설정	설명	기본값
Min Replicas	항상 유지할 최소 Pod 수. 최소값은 1이며 0(scale-to-zero)은 지원하지 않습니다.	1
Scale-in Delay (s)	트래픽 감소 후 Pod 축소까지 대기 시간 (flapping 방지)	60
Max Replicas	최대 Pod 수 (클러스터 가속기 여유분 고려 필요)	10
Target Response Time (ms)	자동 확장 기준 P95 응답 시간 목표값. 초과 시 Pod 증가	5000

Traffic Management

Traffic Management는 여러 Pod로의 요청 분산 방식, 온도 기반 트래픽 보호, 비동기 처리를 제어하는 기능 모음입니다. 단일 Pod로 운영 중이면 Load Balancing과 Temperature Policy는 비활성화 상태로 두어도 무방합니다. Async Queue는 응답 대기 없이 요청을 제출하고 나중에 결과를 조회하는 비동기 워크플로우에 사용합니다.

기능	설명	기본값
Load Balancing	여러 Pod로 요청 분산. Replicas가 2 이상인 경우 활성화를 권장합니다.	Off
Temperature Policy	GPU/NPU 온도 임계값 초과 시 해당 Pod 트래픽 자동 차단, 회복 시 재개. 장시간 고부하 추론 시 하드웨어 보호를 위해 활성화를 권장합니다.	Off
Async Queue	Redis 기반 비동기 요청 큐 활성화. 클라이언트가 요청 제출 후 즉각 응답을 기다리지 않아도 되는 배치 추론 또는 장시간 소요 작업에 적합합니다.	Off

Load Balancing 활성화 시 Policy 드롭다운이 나타납니다:

옵션	설명
LEAST_REQUEST (Recommended)	활성 요청 수가 가장 적은 Pod로 라우팅 (기본값)
ROUND_ROBIN	Pod들을 순서대로 돌아가며 라우팅
RANDOM	무작위로 Pod를 선택하여 라우팅

Temperature Policy 활성화 시 임계값 설정이 나타납니다:

설정	설명	기본값
Critical Threshold (°C)	트래픽 차단 온도 기준	85
Recovery Threshold (°C)	트래픽 재개 온도 기준	70

---