NVIDIA GPU sunucusuna Docker ile vLLM kurulumu

vLLM, büyük dil modelleri için yüksek kapasiteli bir çıkarım ve sunum motorudur. GPU üzerinde aynı anda çok sayıda isteği işler ve OpenAI uyumlu bir HTTP sunucusu sunar; bu da onu NVIDIA donanımında üretim LLM API'leri için yaygın bir seçenek yapar. Bu rehber bir GPU sunucusunu NVIDIA sürücüsü ve Container Toolkit ile hazırlar, resmi vllm/vllm-openai imajını Docker Compose ile 127.0.0.1:8000 üzerinde çalıştırır, onu bir API anahtarı ve yalnızca /v1 API'sini açan bir Caddy proxy'siyle korur, bellek ve çoklu GPU seçeneklerini açıklar ve uv ile systemd kullanan alternatif bir kurulum gösterir.

Adım 1 — NVIDIA sürücüsünü kurun

Sürücüyü NVIDIA'nın sürücü kurulum rehberinde anlatıldığı gibi NVIDIA'nın ağ deposundan kurun. Komutlar sürümünüze uygun cuda-keyring paketini ekler ve nvidia-open sürücüsünü kurar. Debian'da NVIDIA'nın rehberi ayrıca contrib bileşenini ister. Rehber bunu Debian 13'te artık bulunmayan add-apt-repository ile etkinleştirir; bu yüzden önce APT kaynaklarınızda main yanına contrib ekleyin (sisteminizin kullandığı dosyaya göre /etc/apt/sources.list.d/debian.sources içindeki Components: satırına veya /etc/apt/sources.list içindeki deb satırlarına):

sudo apt update
sudo apt install linux-headers-$(uname -r)
distro=ubuntu$(. /etc/os-release && echo "$VERSION_ID" | tr -d .)
wget https://developer.download.nvidia.com/compute/cuda/repos/$distro/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install nvidia-open
sudo reboot

sudo apt update
sudo apt install linux-headers-$(uname -r)
distro=debian$(. /etc/os-release && echo "$VERSION_ID")
wget https://developer.download.nvidia.com/compute/cuda/repos/$distro/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt -V install nvidia-open
sudo reboot

Yeniden başlatmadan sonra nvidia-smi çalıştırın. Komut tüm GPU'ları, sürücü sürümünü ve başlık satırında sürücünün desteklediği en yüksek CUDA sürümünü listeler. GPU'nuz daha eski bir sürücü dalı gerektiriyorsa NVIDIA'nın rehberi bir dalın nasıl sabitleneceğini açıklar. Secure Boot etkinse çekirdek modülünün yüklenebilmesi için önce donanım yazılımının güvendiği bir anahtarla imzalanması gerekir.

Adım 2 — NVIDIA Container Toolkit'i kurun

Container Toolkit, Docker konteynerlerinin GPU'yu kullanmasını sağlar. NVIDIA'nın kurulum rehberini izleyerek NVIDIA deposunu ekleyin, toolkit'i kurun ve Docker çalışma ortamını yapılandırın:

sudo apt install -y --no-install-recommends ca-certificates curl gnupg2
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

nvidia-ctk, Docker'ın NVIDIA Container Runtime'ı kullanabilmesi için /etc/docker/daemon.json dosyasını günceller. Konteynerlerin GPU'yu gördüğünü doğrulamak için NVIDIA'nın örnek iş yükünü çalıştırın:

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Sunucudakiyle aynı nvidia-smi tablosunu görmelisiniz.

Adım 3 — Proje klasörünü ve gizli anahtarları oluşturun

Compose dosyasını, gizli anahtarları ve Hugging Face önbelleğini /opt/vllm altında bir arada tutun:

sudo mkdir -p /opt/vllm/hf-cache && sudo chown -R $USER:$USER /opt/vllm
cd /opt/vllm
echo "VLLM_API_KEY=$(openssl rand -hex 32)" > .env
echo "HF_TOKEN=" >> .env
chmod 600 .env

VLLM_API_KEY değişkenini vLLM sunucusu API anahtarı olarak okur. Herkese açık modeller için HF_TOKEN değerini boş bırakın; erişimi kısıtlı modeller için = işaretinden sonra bir Hugging Face erişim token'ı yapıştırın. Bu modeller için ayrıca modelin Hugging Face sayfasında erişim isteyin.

Adım 4 — vLLM'i Docker Compose ile başlatın

/opt/vllm/compose.yaml dosyasını oluşturun. Servis, belgelerdeki docker run komutunu izler: tüm GPU'lar, host IPC alanı (PyTorch süreçler arasında bellek paylaşır; bunun için --ipc=host veya daha büyük bir --shm-size gerekir), konteynere bağlanan Hugging Face önbelleği ve yalnızca loopback adresinde yayınlanan 8000 portundaki API. Bu örnek, vLLM belgelerinde kullanılan küçük Qwen/Qwen3-0.6B modelini sunar:

services:
  vllm:
    image: vllm/vllm-openai:latest
    command: ["--model", "Qwen/Qwen3-0.6B", "--max-model-len", "8192"]
    environment:
      VLLM_API_KEY: "${VLLM_API_KEY}"
      HF_TOKEN: "${HF_TOKEN}"
    volumes:
      - ./hf-cache:/root/.cache/huggingface
    ports:
      - "127.0.0.1:8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

docker compose up -d
docker compose logs -f vllm

İlk açılışta büyük bir imaj çekilir, model ağırlıkları /opt/vllm/hf-cache içine indirilir ve GPU çekirdekleri hazırlanır; bu birkaç dakika sürebilir. Log, uygulamanın başladığını ve Uvicorn'un 8000 portunda hizmet verdiğini gösterdiğinde sunucu hazırdır.

Adım 5 — OpenAI uyumlu API'yi test edin

Anahtarı kabuğunuza yükleyin ve sunucuyu sorgulayın. /health anahtar istemez; /v1 uç noktaları ister:

cd /opt/vllm
export VLLM_API_KEY=$(grep VLLM_API_KEY .env | cut -d= -f2)
curl -i http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer $VLLM_API_KEY"
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -d '{"model": "Qwen/Qwen3-0.6B", "messages": [{"role": "user", "content": "Say hello in five words"}]}'

/health 200 OK döndürür, /v1/models Qwen/Qwen3-0.6B modelini listeler ve sohbet isteği bir yanıt döndürür. Başlıksız bir /v1/models isteği 401 döndürür. İstemciler farklı bir model adı bekliyorsa --served-model-name seçeneğini kullanın.

Adım 6 — Belleği ayarlayın ve birden fazla GPU kullanın

vLLM açılışta her GPU belleğinden bir pay ayırır, ağırlıkları buraya yükler ve kalan kısmı eşzamanlı istekler için KV önbelleği olarak kullanır. Bu seçenekleri compose.yaml içindeki command satırına ekleyin ve uygulamak için docker compose up -d çalıştırın:

Örneğin daha büyük bir modeli iki GPU'ya yaymak için command: ["--model", "org/model-name", "--tensor-parallel-size", "2"] kullanın. Belirli GPU'ları bir örneğe ayırmak için environment içinde CUDA_VISIBLE_DEVICES ayarlayın, örneğin CUDA_VISIBLE_DEVICES: "0,1". Çok düğümlü kurulumlar düğümler arasında yalıtılmış bir ağ gerektirir; çünkü vLLM'in iç iletişimi güvenli değildir.

Adım 7 — Caddy üzerinden yalnızca API'yi açın

vLLM güvenlik belgeleri yalnızca açmak istediğiniz uç noktalara izin veren bir reverse proxy önerir; çünkü --api-key /v1, /v2, /inference ve /cohere yollarını korur, ancak /tokenize, /pooling veya /health gibi uç noktaları korumaz. Bu Caddy site bloğu /v1/* isteklerini iletir ve geri kalan her şeye 404 ile yanıt verir:

llm.example.com {
    handle /v1/* {
        reverse_proxy 127.0.0.1:8000
    }
    handle {
        respond 404
    }
}

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

İstemciler artık temel adres olarak https://llm.example.com/v1, API anahtarı olarak da VLLM_API_KEY değerini kullanır. Akışlı yanıtlar Caddy'den ek ayar gerektirmeden geçer.

Alternatif: vLLM'i uv ile kurup systemd altında çalıştırma

Docker kullanamıyorsanız belgeler vLLM'i uv ile temiz bir sanal ortama kurmanızı önerir. uv aracını resmi kurulum betiğini inceledikten sonra kurun, ardından ortamı /opt/vllm içinde, servis kullanıcısının okuyabilmesi için proje klasöründe saklanan yönetilen bir Python 3.12 ile oluşturun:

sudo apt install build-essential
curl -LsSf https://astral.sh/uv/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.sh
source $HOME/.local/bin/env
sudo mkdir -p /opt/vllm && sudo chown $USER:$USER /opt/vllm
cd /opt/vllm
export UV_PYTHON_INSTALL_DIR=/opt/vllm/python
uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
python -c "import vllm; print(vllm.__version__)"

--torch-backend=auto, kurulu sürücünüze uygun PyTorch derlemesini seçer. Ardından bir servis kullanıcısı ve yalnızca root'un okuyabildiği bir ortam dosyası oluşturun:

sudo useradd --system --create-home --home-dir /var/lib/vllm --shell /usr/sbin/nologin vllm
echo "VLLM_API_KEY=$(openssl rand -hex 32)" | sudo tee /etc/vllm.env > /dev/null
echo "HF_HOME=/var/lib/vllm/huggingface" | sudo tee -a /etc/vllm.env > /dev/null
sudo chmod 600 /etc/vllm.env

/etc/systemd/system/vllm.service dosyasını oluşturun, ardından sudo systemctl daemon-reload ve sudo systemctl enable --now vllm çalıştırın:

[Unit]
Description=vLLM OpenAI-compatible server
After=network-online.target
Wants=network-online.target

[Service]
User=vllm
Group=vllm
EnvironmentFile=/etc/vllm.env
ExecStart=/opt/vllm/.venv/bin/vllm serve Qwen/Qwen3-0.6B --host 127.0.0.1 --port 8000 --max-model-len 8192
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

--host 127.0.0.1 seçeneği sunucuyu loopback adresinde tutar. Açılışı journalctl -u vllm -f ile izleyin, 5. adımdaki gibi test edin ve aynı Caddy bloğunu kullanın. Erişimi kısıtlı modeller için /etc/vllm.env dosyasına HF_TOKEN= satırını ekleyin.

Yedekleme ve geri yükleme

vLLM kullanıcı verisi tutmaz. Yapılandırmayı yedekleyin: compose.yaml ve .env (veya /etc/vllm.env ve unit dosyası). Hugging Face önbelleği yeniden indirilebilir; yalnızca indirmeler yavaşsa veya model özelse ekleyin.

sudo mkdir -p /opt/backups
sudo tar czf /opt/backups/vllm-config-$(date +%F).tar.gz /opt/vllm/compose.yaml /opt/vllm/.env

Geri yüklemek için bir sunucuyu 1. ve 2. adımlarla hazırlayın, arşivi sudo tar xzf /opt/backups/vllm-config-YYYY-MM-DD.tar.gz -C / ile açın, /opt/vllm klasörünün sahipliğini düzeltin ve docker compose up -d çalıştırın. Arşivi sunucunun dışına kopyalayın; API anahtarınızı içerir.

vLLM'i güncelleme

Önce vLLM sürümler sayfasındaki sürüm notlarını okuyun: seçenekler ve varsayılanlar sürümler arasında değişir. Docker kurulumunda sabitlenmiş etiketi değiştirin (veya latest ile devam edin), imajı çekin ve konteyneri yeniden oluşturun:

cd /opt/vllm
docker compose pull
docker compose up -d
docker image prune

uv kurulumunda belgeler, derlenmiş çekirdekler belirli CUDA ve PyTorch sürümlerine bağlı olduğu için yerinde yükseltme yerine temiz bir ortam önerir. Eskisinin yanında yeni bir sanal ortam oluşturun, vLLM'i oraya kurun, ExecStart satırını yeni yola yönlendirin ve servisi yeniden başlatın; yenisi çalışana kadar eski ortamı silmeyin. Sürücü güncellemeleri NVIDIA deposundan apt upgrade ile gelir ve yeniden başlatma gerektirir.

Sorun giderme

CUDA out of memory

Ağırlıklar ve KV önbelleği sığmıyor. --max-model-len veya --max-num-seqs değerini düşürün, modelin nicemlenmiş bir sürümünü kullanın, modeli --tensor-parallel-size ile bölün ya da nvidia-smi ile başka bir sürecin GPU belleğini tutmadığını kontrol edin. GPU'yu başka iş yükleri de kullanıyorsa --gpu-memory-utilization değerini düşürün. vLLM bellek rehberi CUDA graph belleğinden tasarruf için --enforce-eager seçeneğini de anlatır.

could not select device driver with capabilities gpu

Docker NVIDIA çalışma ortamını tanımıyor. 2. adımı, özellikle sudo nvidia-ctk runtime configure --runtime=docker komutunu ve Docker'ın yeniden başlatılmasını tekrarlayın, ardından örnek iş yüküyle test edin.

CUDA driver is too old veya PTX araç zinciri hatası

Sürücü, imajın veya wheel paketinin CUDA sürümünden eski. Sürücüyü NVIDIA deposundan güncelleyin ve sunucuyu yeniden başlatın. Bazı veri merkezi GPU'ları için vLLM belgeleri bir uyumluluk modu sunar: konteyner ortamına VLLM_ENABLE_CUDA_COMPATIBILITY: "1" ekleyin.

Erişimi kısıtlı bir model indirilirken 401 veya 403

HF_TOKEN eksik veya geçersiz ya da Hugging Face hesabınıza modele henüz erişim verilmemiş. .env içindeki token'ı düzeltin, modelin Hugging Face sayfasında erişim isteyin, erişim verilene kadar bekleyin ve docker compose up -d çalıştırın.

Sunucu indirme veya açılış sırasında takılıyor

Modeli Hugging Face'in hf komut satırı aracıyla önbellek klasörüne ayrıca indirin ve vLLM'i yeniden başlatın; bu, sorunun indirmede olup olmadığını gösterir. Daha fazla çıktı için ortama VLLM_LOGGING_LEVEL: "DEBUG" ekleyin ve işiniz bitince yeniden kaldırın.

Sonraki adımlar

• Open WebUI arayüzünü https://llm.example.com/v1 adresine bağlayarak bir sohbet ekranı ekleyin.
• CPU dostu çalışma ortamlarıyla karşılaştırın: llama.cpp sunucusu ve Ollama.
• Donanımı GPU sunucuları ve LLM API hosting sayfalarında seçin.
• Tüm motor parametreleri için https://docs.vllm.ai adresindeki resmi belgeleri okuyun.