gpustack

개요
GPUStack은 AI 모델 서빙 및 GPU 인스턴스 프로비저닝을 위한 오픈소스 GPU 클러스터 관리자입니다. vLLM, SGLang, TensorRT-LLM 또는 사용자 정의 추론 엔진을 구성하고 오케스트레이션하며, SSH로 접속 가능한 GPU 인스턴스를 필요할 때 실행할 수 있습니다. 핵심 기능은 다음과 같습니다:

멀티 클러스터 GPU 관리. 온프레미스 서버, Kubernetes 클러스터, 클라우드 제공자 전반의 GPU 클러스터를 관리합니다. 모델 배포 및 GPU 인스턴스에 대한 GPU 슬라이싱을 지원하며, VRAM과 컴퓨트 할당을 구성할 수 있습니다.
플러그형 추론 엔진. vLLM, SGLang, TensorRT-LLM과 같은 고성능 추론 엔진을 자동으로 구성합니다. 필요에 따라 사용자 정의 추론 엔진을 추가할 수도 있습니다.
Day 0 모델 지원. GPUStack의 플러그형 엔진 아키텍처를 통해 새 모델이 출시되는 당일 배포할 수 있습니다.
성능 최적화 구성. 저지연 또는 고처리량을 위한 사전 튜닝된 모드를 제공합니다. 각 단계에 대해 독립적으로 구성 가능한 레플리카와 리소스를 갖춘 prefill/decode 분리를 지원합니다. 플랫폼이 관리하는 공유 KV 캐시를 통해 호환되는 배포와 레플리카가 캐시된 프리픽스를 재사용할 수 있으며, L2 스토리지가 용량을 확장하고 노드 간 재사용을 가능하게 합니다. 또한 EAGLE3, MTP, N-grams와 같은 추측 디코딩(speculative decoding) 방식에 대한 기본 지원을 포함합니다.
내장 벤치마킹. Auto Tune은 동시성 또는 요청 속도를 자동으로 탐색하여 최대 처리량 또는 서비스 수준 목표(SLO)를 충족하는 최고 동시성을 찾습니다.
GPU 인스턴스. 개발, 파인튜닝, 대화형 워크로드를 위해 SSH로 접속 가능한 GPU 인스턴스를 필요할 때 실행합니다.
엔터프라이즈급 운영. 자동 장애 복구, 로드 밸런싱, 모니터링, 인증, 접근 제어를 지원합니다.

아키텍처
GPUStack은 개발 팀, IT 조직, 서비스 제공자가 규모에 맞게 Model-as-a-Service를 제공할 수 있도록 합니다. LLM, 음성, 이미지, 비디오 모델을 위한 업계 표준 API를 지원합니다. 플랫폼에는 기본 제공되는 사용자 인증 및 접근 제어, GPU 성능과 활용률의 실시간 모니터링, 토큰 사용량과 API 요청 속도의 상세한 계량 기능이 포함됩니다.

아래 그림은 단일 GPUStack 서버가 온프레미스와 클라우드 환경 전반의 여러 GPU 클러스터를 어떻게 관리할 수 있는지 보여줍니다. GPUStack 스케줄러는 리소스 활용률을 극대화하도록 GPU를 할당하고 최적의 성능을 위해 적절한 추론 엔진을 선택합니다. 또한 관리자는 통합된 Grafana 및 Prometheus 대시보드를 통해 시스템 상태와 메트릭을 완전히 파악할 수 있습니다.

한눈에 보는 클러스터 가시성
GPUStack Enterprise의 GPU 클러스터 토폴로지 뷰는 전체 플릿에 대한 실시간 조감도를 제공합니다. 모든 워커, GPU, 모델 배포를 한 곳에서 확인할 수 있으며, 실시간 활용률, 할당, 상태를 보여줍니다.

최적화된 추론 성능
GPUStack의 자동 엔진 선택과 파라미터 최적화는 기본적으로 뛰어난 추론 성능을 제공합니다. 다음 그림은 기본 vLLM 구성 대비 처리량 개선을 보여줍니다:

자세한 벤치마킹 방법과 결과는 Inference Performance Lab 을 참조하십시오.

GPUStack의 내장 벤치마킹으로 배포가 처리할 수 있는 범위를 확인하십시오. Auto Tune은 부하를 적응적으로 조정하여 최대 처리량을 밝혀내거나 서비스 수준 목표(SLO)를 충족하는 최고 동시성을 찾으며, 상세한 처리량 및 지연 차트로 용량 계획을 안내합니다.

지원 가속기
GPUStack은 AI 추론을 위한 다양한 가속기를 지원합니다:

NVIDIA GPU
AMD GPU
Ascend NPU
Hygon DCU
MThreads GPU
Iluvatar GPU
MetaX GPU
Cambricon MLU
T-Head PPU

자세한 요구 사항과 설정 지침은 Installation Requirements 문서를 참조하십시오.

빠른 시작
사전 요구 사항

최소 하나의 NVIDIA GPU가 있는 노드. 다른 GPU 유형의 경우 워커 추가 시 GPUStack UI의 안내를 확인하거나 자세한 내용은 Installation 문서를 참조하십시오.
워커 노드에 NVIDIA 드라이버, Docker, NVIDIA Container Toolkit이 설치되어 있는지 확인하십시오.
(선택 사항) GPUStack 서버를 호스팅할 CPU 노드. GPUStack 서버는 GPU가 필요하지 않으며 CPU 전용 머신에서 실행할 수 있습니다. Docker가 설치되어 있어야 합니다. Docker Desktop(Windows 및 macOS용)도 지원됩니다. 전용 CPU 노드가 없는 경우 GPUStack 서버를 GPU 워커 노드와 동일한 머신에 설치할 수 있습니다.
GPUStack 워커 노드는 Linux만 지원됩니다. Windows를 사용하는 경우 WSL2 사용을 고려하고 Docker Desktop 사용은 피하십시오. macOS는 GPUStack 워커 노드로 지원되지 않습니다.

GPUStack 설치
다음 명령을 실행하여 Docker로 GPUStack 서버를 설치하고 시작하십시오:

sudo docker run -d --name gpustack \
--restart unless-stopped \
-p 80:80 \
--volume gpustack-data:/var/lib/gpustack \
gpustack/gpustack

대안: Quay Container Registry 미러 사용
Docker Hub에서 이미지를 가져올 수 없거나 다운로드가 매우 느린 경우, 레지스트리를 quay.io 로 지정하여 Quay.io 미러를 사용할 수 있습니다:

sudo docker run -d --name gpustack \
--restart unless-stopped \
-p 80:80 \
--volume gpustack-data:/var/lib/gpustack \
quay.io/gpustack/gpustack \
--system-default-container-registry quay.io

GPUStack 시작 로그를 확인하십시오:

sudo docker logs -f gpustack
GPUStack이 시작된 후 다음 명령을 실행하여 기본 admin 비밀번호를 확인하십시오:

sudo docker exec gpustack cat /var/lib/gpustack/initial_admin_password
브라우저를 열고 http://your_host_ip 로 이동하여 GPUStack UI에 접속하십시오. 기본 사용자 이름 admin 과 위에서 확인한 비밀번호를 사용하여 로그인하십시오.

GPU 클러스터 설정

GPUStack UI에서 Clusters 페이지로 이동하십시오.

Add Cluster 버튼을 클릭하십시오.

클러스터 제공자로 Docker 를 선택하십시오.

새 클러스터의 Name 과 Description 필드를 입력한 후 Save 버튼을 클릭하십시오.

UI 안내에 따라 새 워커 노드를 구성하십시오. 워커 노드에서 Docker 명령을 실행하여 GPUStack 서버에 연결해야 합니다. 명령은 다음과 유사합니다:

sudo docker run -d --name gpustack-worker \
--restart=unless-stopped \
--privileged \
--network=host \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume gpustack-data:/var/lib/gpustack \
--runtime nvidia \
gpustack/gpustack \
--server-url http://your_gpustack_server_url \
--token your_worker_token \
--advertise-address 192.168.1.2

워커 노드에서 명령을 실행하여 GPUStack 서버에 연결하십시오.

워커 노드가 성공적으로 연결되면 GPUStack UI의 Workers 페이지에 나타납니다.

모델 배포

GPUStack UI에서 Catalog 페이지로 이동하십시오.

사용 가능한 모델 목록에서 Qwen3.5-0.8B 모델을 선택하십시오.

배포 호환성 검사가 통과되면 Save 버튼을 클릭하여 모델을 배포하십시오.

GPUStack이 모델 파일 다운로드를 시작하고 모델을 배포합니다. 배포 상태가 Running 으로 표시되면 모델이 성공적으로 배포된 것입니다.

탐색 메뉴에서 Playground - Chat 을 클릭하고, 오른쪽 상단 Model 드롭다운에서 qwen3.5-0.8b 모델이 선택되어 있는지 확인하십시오. 이제 UI 플레이그라운드에서 모델과 대화할 수 있습니다.

API를 통해 모델 사용

Access Control > API Keys 페이지로 이동한 후 New API Key 버튼을 클릭하십시오.

Name 을 입력하고 Save 버튼을 클릭하십시오.

생성된 API 키를 복사하여 안전한 곳에 저장하십시오. 생성 시 한 번만 확인할 수 있습니다.

이제 API 키를 사용하여 GPUStack이 제공하는 OpenAI 호환 API 엔드포인트에 접근할 수 있습니다. 예를 들어 다음과 같이 curl을 사용하십시오:

# Replace `your_api_key` and `your_gpustack_server_url`
# with your actual API key and GPUStack server URL.
export GPUSTACK_API_KEY=your_api_key
curl http://your_gpustack_server_url/v1/chat/completions \
-H " Content-Type: application/json " \
-H " Authorization: Bearer $GPUSTACK_API_KEY " \
-d ' {
"model": "qwen3.5-0.8b",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Tell me a joke."
}
],
"stream": true
} '
문서
전체 문서는 공식 문서 사이트를 참조하십시오.

빌드

Docker 를 설치하십시오.

make package 를 실행하십시오.

커뮤니티 참여
문제가 있거나 제안 사항이 있으면 언제든지 Community 에 참여하여 지원을 받으십시오.

기여
GPUStack에 기여하는 데 관심이 있으시면 Contributing Guide 를 읽어 주십시오.

모든 기여자분들께 감사드립니다!

라이선스
Copyright (c) 2024-2026 The GPUStack authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at LICENSE file for details.

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.