GPT OSS 120B는 vLLM과 함께 배포하기 위한 예시 모델로, GPU 선택부터 프로덕션 모니터링까지 다룹니다.

GPU 선택#

GPT OSS 120B는 NVIDIA H100에서 학습되었으며 H100 또는 이후 세대의 데이터센터 GPU에서 가장 잘 실행됩니다. 혼합 전문가(MoE) 아키텍처는 각 토큰에 대해 네트워크의 일부만 활성화하므로, 모델이 단일 H100 80 GB GPU에 적합합니다.

병렬화 전략 결정#

GPU의 연결 방식에 따라 다음 병렬화 전략이 결정됩니다:

• GPU가 NVLink(수백 GB/s)를 통해 연결되어 있다면, 단일 노드에서 텐서 병렬화를 사용하세요. 텐서 병렬화는 각 레이어를 GPU에 분산하며 높은 대역폭이 필요합니다.

• GPU의 대역폭이 낮고 PCIe(약 64 GB/s)를 통해 작동한다면, 파이프라인 병렬화를 사용하세요. 파이프라인 병렬화는 레이어를 GPU에 순차적으로 분산합니다.

텐서 병렬화의 최대 한계에 도달했지만 더 많은 모델 분산이 필요한 경우, 두 가지 병렬화 전략을 결합할 수 있습니다. 예를 들어, 노드 내에서 텐서 병렬화를, 노드 간에 파이프라인 병렬화를 사용할 수 있습니다.

VRAM 요구사항 계획#

필요한 VRAM은 컨텍스트 길이와 예상 동시 접속 수에 따라 달라집니다.

vLLM은 다음 용도로 VRAM을 할당합니다:

KV 캐시는 각 요청에서 처리된 토큰에 대한 사전 계산된 벡터의 저장소입니다. 각 토큰은 한 번만 계산되며, 모든 변동성이 여기에 존재합니다.

예시: 단일 H100 80 GB#

--gpu-memory-utilization 0.95를 사용하면 76 GB의 사용 가능한 VRAM을 얻을 수 있습니다:

76 GB usable
├── 61 GB  model weights          ← fixed
├──  2 GB  framework overhead     ← fixed
└──  13 GB  KV cache               ← fills as requests arrive

캐시된 토큰당 약 36 KB를 기준으로, 13 GB는 전체 어텐션 레이어에서 약 370K 토큰의 컨텍스트를 저장할 수 있습니다. 각 에이전틱 요청이 약 32K 토큰을 사용한다면 약 10개의 동시 요청을 처리할 수 있습니다.

vLLM을 시작하면 로그에서 정확한 수치를 확인할 수 있습니다:

Available KV cache memory: N GiB
GPU KV cache size: Y tokens
Maximum concurrency for Y tokens per request: Nx

설치#

환경에 맞는 옵션을 선택하세요:

• 설치 스크립트: CUDA 또는 GPU 드라이버가 설치되지 않은 새 Ubuntu 또는 Debian 머신.

• vLLM만 설치: CUDA와 드라이버가 이미 설치된 경우(GCP의 NVIDIA Deep Learning VM, AWS Deep Learning AMI, 또는 기존 GPU 머신).

• Docker: 호스트 수준의 모든 설정을 건너뜁니다.

다른 하드웨어를 사용하는 경우, 추가 구성은 GPT OSS - vLLM Recipes를 참조하세요.

옵션 1: 설치 스크립트 (처음부터)#

스택을 업데이트할 때 각 변수에 다음 버전을 사용하세요. 이 버전들은 GPT OSS 120B를 서빙하기 위한 최소 요구 버전입니다. 성능 개선, 버그 수정 및 확장된 하드웨어 지원이 포함된 최신 vLLM 릴리즈를 사용하는 것이 좋습니다.

#!/bin/bash
# vLLM + CUDA installation for gpt-oss-120b
# Target: Ubuntu 22.04 / Debian 12, x86_64

CUDA_VERSION="12-9"           # apt package suffix  →  cuda-toolkit-12-9
MIN_DRIVER_VERSION="575"      # minimum driver for CUDA 12.9
PYTHON_VERSION="3.12"
VLLM_VERSION="0.18.0"
VENV_DIR="${HOME}/vllm-env"

set -e

# ===========================================================================
# PART 1 — system prerequisites
# ===========================================================================
echo "--- Part 1: System prerequisites ---"

sudo apt-get update && sudo apt-get upgrade -y

sudo apt-get install -y \
    build-essential \
    dkms \
    linux-headers-$(uname -r) \
    wget curl gnupg2 \
    software-properties-common \
    python${PYTHON_VERSION} \
    python${PYTHON_VERSION}-venv \
    python${PYTHON_VERSION}-dev \
    python3-pip git

# Install uv — recommended by vLLM docs; gives extra index URLs higher
# priority than PyPI, which is required for the gpt-oss fork to resolve correctly.
curl --location --silent --show-error --fail "https://astral.sh/uv/install.sh" | sh
source "${HOME}/.local/bin/env"

# ===========================================================================
# PART 2 — NVIDIA drivers and CUDA toolkit
# Reboot required after this section before continuing to Part 3.
# ===========================================================================
echo "--- Part 2: NVIDIA drivers and CUDA ${CUDA_VERSION//-/.} ---"

# Add NVIDIA's package repository.
# For Debian 12, replace ubuntu2204 with debian12 in the URL.
# Current keyring URL: https://developer.nvidia.com/cuda-downloads
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update

# cuda-drivers (no version suffix) is a meta-package — apt resolves
# the latest driver compatible with the pinned toolkit automatically.
sudo apt-get install -y \
    cuda-drivers \
    cuda-toolkit-${CUDA_VERSION} \
    nvidia-gds-${CUDA_VERSION}

echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc

# Keep GPU initialised between jobs (reduces cold-start latency)
sudo systemctl enable nvidia-persistenced

echo "Rebooting to load NVIDIA kernel modules..."
echo "After reboot, run:  bash install.sh --post-reboot"

if [[ "${1:-}" != "--post-reboot" ]]; then
    sudo reboot
fi

# ===========================================================================
# PART 3 — Python environment and vLLM
# Start here after reboot, or if using a cloud managed image.
# ===========================================================================
echo "--- Part 3: Verify drivers ---"

nvidia-smi       # confirm driver >= ${MIN_DRIVER_VERSION} and GPUs visible
nvcc --version   # confirm CUDA ${CUDA_VERSION//-/.}

echo "--- Part 3: Python environment ---"

uv venv "$VENV_DIR" --python ${PYTHON_VERSION} --seed
source "$VENV_DIR/bin/activate"

python --version   # should show Python 3.12.x

echo "--- Part 3: PyTorch ---"

# --torch-backend=auto inspects your installed CUDA driver at runtime and
# selects the matching PyTorch index automatically. This replaces hardcoded
# --index-url flags and stays correct across CUDA version updates.
uv pip install torch torchvision torchaudio --torch-backend=auto

echo "--- Part 3: vLLM ---"

uv pip install "vllm==${VLLM_VERSION}" --torch-backend=auto

echo ""
echo "Installation complete."
echo "Activate environment:  source ${VENV_DIR}/bin/activate"
echo "Verify vLLM version:   python -c \"import vllm; print(vllm.__version__)\""

옵션 2: vLLM만 설치#

CUDA와 드라이버가 이미 설치된 경우(클라우드 관리형 이미지 및 기존 GPU 머신), 다음 명령어를 사용하여 vLLM을 설치하세요.

uv venv
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

옵션 3: Docker#

다음 명령어를 사용하여 GPT OSS 120B Docker 이미지를 설치하세요. vllm/vllm-openai:v0.18.0 이미지에는 CUDA, 드라이버, vLLM이 포함되어 있습니다.

docker run \
  --gpus all \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:v0.18.0 \
  --model openai/gpt-oss-120b

vLLM 구성#

vLLM 구성의 값은 트래픽 패턴에 따라 달라집니다. 아래의 권장 설정으로 시작한 다음 다음 레버를 조정하세요.

권장 설정#

다음 표는 각 하드웨어에 대한 권장 설정을 나열합니다. 하드웨어 및 예상 트래픽 패턴에 맞는 행을 선택한 다음 해당 구성을 사용하세요.

Approximate concurrent requests 칼럼은 나열된 컨텍스트 길이에서의 KV 캐시 제한 동시 처리 수의 근사값을 나타내며, --max-num-seqs 값이 아닙니다.

Single H100 80 GB#

이 설정에서 높은 --gpu-memory-utilization(기본값 0.90 대비 0.95)은 단일 H100에서 알려진 CUDA OOM 문제를 해결하기 위한 것입니다.

vllm serve openai/gpt-oss-120b \
  --gpu-memory-utilization 0.95 \
  --max-model-len 32768 \
  --max-num-seqs 16 \
  --max-num-batched-tokens 4096

2× H100 80 GB#

이 설정에서는 더 큰 결합된 KV 캐시 풀이 더 높은 컨텍스트 창과 더 많은 동시 요청을 지원합니다.

vllm serve openai/gpt-oss-120b \
  --tensor-parallel-size 2 \
  --max-model-len 65536 \
  --max-num-seqs 32 \
  --max-num-batched-tokens 8192

4× H100 80 GB#

이 설정은 전체 128K 컨텍스트 창을 제공합니다.

vllm serve openai/gpt-oss-120b \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.95 \
  --max-model-len 131072 \
  --max-num-seqs 64 \
  --max-num-batched-tokens 16384

2× A100 40 GB#

이 설정에서 단일 A100 40 GB는 61 GB 모델 가중치를 저장할 수 없습니다. 두 개의 GPU가 최소 요구 사항입니다.

vllm serve openai/gpt-oss-120b \
  --tensor-parallel-size 2 \
  --max-model-len 32768 \
  --max-num-seqs 24 \
  --max-num-batched-tokens 4096

4× A100 40 GB#

vllm serve openai/gpt-oss-120b \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --max-num-seqs 128 \
  --max-num-batched-tokens 16384

2× L40S 48GB 또는 RTX A6000 Ada 48 GB#

두 설정 모두 48 GB의 Ada Lovelace를 사용합니다.

vllm serve openai/gpt-oss-120b \
  --tensor-parallel-size 2 \
  --max-model-len 32768 \
  --max-num-seqs 16 \
  --max-num-batched-tokens 4096

추가적인 NVIDIA Blackwell 및 Hopper 최적화는 GPT OSS - vLLM Recipes: Recipe for NVIDIA Blackwell & Hopper Hardware를 참조하세요.

서버 확인#

vLLM을 시작한 후 다음 요청으로 올바르게 서빙되고 있는지 확인하세요:

curl "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 64
  }'

모델의 완성이 포함된 JSON 응답이 표시되어야 합니다. 서버가 아직 준비되지 않은 경우 연결 거부 오류가 발생합니다. vLLM은 첫 시작 시 모델 가중치를 로드하는 데 시간이 필요하며, 저장 속도에 따라 몇 분이 걸릴 수 있습니다.

모니터링#

vLLM은 Prometheus 호환 /metrics 엔드포인트를 노출합니다. 전체 목록은 Production Metrics - vLLM을 참조하세요.

vLLM을 모니터링하려면 사용자 대면 지연 시간과 용량 압박에 대한 메트릭을 확인하세요.

문제 해결#

클라이언트 타임아웃 또는 num_requests_waiting이 계속 증가하는 경우#

들어오는 요청이 KV 캐시 용량을 초과합니다. vLLM은 캐시 공간이 해제될 때까지 새 요청을 대기열에 넣으며, 대기열이 소진되지 않습니다.

이 문제를 해결하려면:

• kv_cache_usage_perc를 확인하세요. 0.85 이상의 지속적인 값은 메모리 제한 상태임을 확인해줍니다.

• --max-model-len을 줄여 요청당 KV 할당을 낮추면, 더 많은 동시 요청을 위한 슬롯이 확보됩니다.

• --max-num-seqs를 줄여 동시에 캐시를 경쟁하는 요청 수를 제한하세요.

• 단일 노드 튜닝이 소진된 경우 수평 확장을 고려하세요: GPU 또는 노드를 추가하고 여러 vLLM 인스턴스에 부하를 분산하세요.

서버가 CUDA OOM 오류로 충돌하는 경우#

서버가 부하가 높을 때 GPU 메모리가 부족합니다.

이 문제를 해결하려면 다음 순서로 조정하세요:

• --max-num-seqs를 줄여 동시 배치 크기를 제한하세요.

• --max-model-len을 줄여 요청당 KV 할당을 축소하세요.

• 시작 시 OOM이 발생하는 경우 --gpu-memory-utilization을 낮추세요.

토큰 생성이 예상보다 느린 경우#

time_per_output_token_seconds가 높고 전체 토큰/초가 낮습니다. GPU가 반복당 충분한 작업을 처리하지 못하고 있습니다.

이 문제를 해결하려면:

• --max-num-batched-tokens를 늘려 vLLM이 반복당 더 많은 토큰을 처리하도록 하세요.

• --max-num-seqs를 늘려 더 많은 요청이 함께 배치되도록 하면 GPU 활용도가 향상됩니다.