# NVIDIA GPU sunucusuna Docker ile vLLM kurulumu

> NVIDIA sürücüsü ile Container Toolkit kurun, vLLM'in OpenAI uyumlu API'sini Docker Compose ile çalıştırın, API anahtarı ve Caddy ile koruyup belleği ayarlayın.

Zorluk: İleri\
Denendiği sistemler: Ubuntu 24.04 LTS, Ubuntu 26.04 LTS, Debian 12, Debian 13

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.

## Ön koşullar

- Desteklenen bir NVIDIA GPU'ya sahip dedicated sunucu; [GPU sunucuları](/gpu-servers) sayfasına bakın. vLLM'in CUDA derlemeleri compute capability 7.5 veya üzerini ister.
- x86_64 üzerinde **Ubuntu 24.04 LTS**, **Ubuntu 26.04 LTS**, **Debian 12** veya **Debian 13**. NVIDIA'nın sürücü rehberi dört sürümü de kapsar.
- `sudo` yetkisi olan, root olmayan bir kullanıcı; [Yeni bir Linux sunucusunu güvenli hale getirin](/guides/secure-a-new-linux-server) ve [SSH anahtarlarını ayarlayın](/guides/ssh-keys) rehberlerine bakın.
- [Ubuntu'ya Docker kurulumu](/guides/install-docker-ubuntu) veya [Debian'a Docker kurulumu](/guides/install-docker-debian) rehberiyle kurulmuş, Compose eklentili Docker Engine.
- Erişimi kısıtlı modeller sunmak istiyorsanız bir Hugging Face hesabı ve erişim token'ı.
- Sunucuyu gösteren `llm.example.com` gibi bir alan adı ve [Caddy ile reverse proxy](/guides/caddy-reverse-proxy) rehberine göre kurulmuş Caddy.

| Kaynak | En düşük (resmi) | Önerilen başlangıç |
|---|---|---|
| GPU | NVIDIA, compute capability 7.5 veya üzeri | Model ağırlıkları ve KV önbelleği için yeterli VRAM |
| Sürücü ve CUDA | Varsayılan derlemeler CUDA 12.9 kullanır; CUDA 13 imajları R580 veya daha yeni sürücü ister | NVIDIA deposundan güncel sürücü |
| Python (pip yöntemi) | 3.11 ile 3.14 arası | Resmi uv örneğindeki gibi 3.12 |
| RAM | Yayınlanmamış | En az GPU belleği kadar sistem RAM'i |
| Disk | Yayınlanmamış | İmaj ve model ağırlıkları için 100 GB boş alan |

vLLM belgeleri RAM veya disk için en düşük değer yayınlamaz; önerilen değerler ölçüm sonucu değil, temkinli bir başlangıç noktasıdır. GPU seçmeden önce modelin ağırlık dosyalarının boyutunu Hugging Face sayfasından kontrol edin.

## 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):

**Ubuntu**

```bash
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
```
**Debian**

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```yaml
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
```

```bash
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.

> **İpucu**
>
> `latest` her yeni sürümü izler. Üretim ortamında GitHub'daki vLLM sürümler sayfasından `vllm/vllm-openai:vX.Y.Z` gibi bir sürüm etiketi sabitleyin ve güncellerken bilinçli olarak değiştirin.

## 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:

```bash
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:

| Seçenek | Varsayılan | Ne için kullanılır |
|---|---|---|
| `--gpu-memory-utilization` | `0.92` | Bu örneğin kullanabileceği GPU belleği oranını belirler; GPU'yu başka süreçler de kullanıyorsa düşürün |
| `--max-model-len` | Model yapılandırmasından | Bağlam uzunluğunu (istem artı çıktı) sınırlar; `auto` sığan en büyük uzunluğu seçer |
| `--max-num-seqs` | vLLM belirler | Yineleme başına işlenen dizi sayısını sınırlar, bellek kullanımını azaltır |
| `--tensor-parallel-size`, `-tp` | `1` | Bir modeli tek sunucudaki birden fazla GPU'ya böler |
| `--quantization`, `-q` | Model yapılandırmasından | Daha küçük ağırlıklar için bir nicemleme yöntemi seçer |
| `--enforce-eager` | kapalı | CUDA graph'ları kapatır; bir miktar GPU belleği kazandırır |

Ö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:

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

```bash
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.

> **Uyarı**
>
> 8000 portunu tüm adreslerde (`"8000:8000"`) yayınlamayın. Docker'ın yayınladığı portlar ufw'yi atlar ve kimlik doğrulaması olmayan uç noktalar internetten erişilebilir hale gelir.

## 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:

```bash
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:

```bash
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:

```ini
[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.

```bash
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:

```bash
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](/guides/open-webui-ollama) 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](/guides/llama-cpp-server) ve [Ollama](/guides/install-ollama).
- Donanımı [GPU sunucuları](/gpu-servers) ve [LLM API hosting](/llm-api-hosting) sayfalarında seçin.
- Tüm motor parametreleri için https://docs.vllm.ai adresindeki resmi belgeleri okuyun.

## Sık sorulan sorular

### vLLM hangi GPU'ları destekler?

vLLM'in CUDA derlemeleri compute capability 7.5 veya üzeri bir NVIDIA GPU ister; örneğin T4, RTX 20 serisi ve sonrası, A100, L4, H100 veya B200. Yalnızca Linux'ta çalışır; yerel Windows desteği yoktur.

### vLLM API anahtarı sunucuyu korumak için yeterli mi?

Hayır. vLLM belgelerine göre --api-key yalnızca /v1, /v2, /inference ve /cohere altındaki uç noktaları doğrular; aynı sunucudaki diğer uç noktalar açık kalır. vLLM'i 127.0.0.1 üzerinde tutun ve bu rehberde Caddy ile yapıldığı gibi yalnızca gereken yolları bir reverse proxy üzerinden açın.

### Bir model ne kadar GPU belleği ister?

Model ağırlıkları GPU belleğine sığmalıdır; vLLM kendi payının geri kalanını KV önbelleği için kullanır. Varsayılan olarak bir örnek her GPU belleğinin yüzde 92'sini kullanabilir (--gpu-memory-utilization 0.92). Daha büyük modeller nicemlenmiş ağırlıklar veya birden fazla GPU'ya tensor paralelliği gerektirir.

### Llama gibi erişimi kısıtlı bir modeli nasıl sunarım?

Modelin Hugging Face sayfasında hesabınızla erişim isteyin, bir erişim token'ı oluşturun ve bunu .env dosyasındaki HF_TOKEN değişkenine yazın. Erişim verildikten sonra vLLM ağırlıkları Hugging Face önbellek klasörüne indirir.

### vLLM'i Docker ile mi yoksa pip ile mi kurmalıyım?

Resmi vllm/vllm-openai imajı uyumlu bir CUDA ve PyTorch yığınıyla gelir ve sunucuyu çalıştırmanın en basit yoludur. Sanal ortamda pip veya uv kurulumu özel senaryolara uygundur; derlenmiş çekirdekler belirli CUDA ve PyTorch sürümlerine bağlı olduğundan belgeler temiz bir ortam önerir.

---

Kaynak: <https://hyperdc.com/tr/guides/tutorials/install-vllm>\
Son güncelleme: 2026-10-09