vLLM Kurulumu: Yüksek Verimli Yerel Sunucu

vLLM, büyük dil modellerini GPU üzerinde mümkün olan en yüksek verimle sunmak için tasarlanmış açık kaynak bir çıkarım motorudur. Berkeley’de doğan proje, PagedAttention adlı bellek yönetim tekniğiyle çok kullanıcılı iş yüklerinde standart belirlemiştir ve günümüzde birçok üretim ortamının tercih ettiği sunucudur. Bu rehber, kurulumu, OpenAI uyumlu API’sini, donanım gereksinimlerini ve performans ayarlarını ansiklopedik biçimde ele alır.

vLLM Nedir ve PagedAttention Ne Sağlar

Geleneksel çıkarım motorlarında her istek için ayırılan bellek blokları, bağlam uzunlukları değiştikçe boşluklarla doludur; bu parçalanma, GPU belleğinin önemli kısmını boşa harcar. PagedAttention, işletim sistemlerinin sanal bellek sayfalama yaklaşımını anahtar-değer (KV) cache’ine uygular: bellek küçük sayfalara bölünür, istekler arası paylaşımlar etkinleşir ve boşa giden bellek minimuma iner. Sonuç, aynı donanımda belirgin biçimde daha yüksek eşzamanlı istek kapasitesi ve verimdir.

Tek kullanıcılı deneyimde fark az hissedilir; ancak çok sayıda eşzamanlı isteğin işlendiği senaryolarda, API servisleri ve iç araçlarda vLLM’in verim üstünlüğü belirgin olur. Sunucu, sürekli batchleme (continuous batching) ile yeni gelen istekleri çalışan gruba anında katarak GPU’nun boşta kalmasını engeller.

Ön Koşullar ve Donanım

vLLM’in ana hedef platformu, NVIDIA GPU’lu Linux sistemleridir. Güncel sürümler Python 3.10 ile 3.13 arasını destekler ve 3.12 önerilir. NVIDIA kartlarda CUDA 12.8 veya üzeri gerekir; Blackwell mimarili yeni kartlar (B200, GB200) özellikle CUDA 12.8+ ister. Bellek tarafında pratik eşik yüksektir: motor başlangıçta belleği geniş ölçüde ayırdığı için küçük modellerde bile 16 GB VRAM rahat bir başlangıç noktasıdır.

AMD GPU’lar ROCm aracılığıyla, Intel GPU’lar XPU arka ucuyla desteklenir; bu platformlarda kurulum pip yerine uv ile yapılması önerilen ayrı yollar izler. Apple Silicon için ayrı bir arka uç mevcuttur ancak ana geliştirme hattı NVIDIA odaklıdır. Windows’ta yerel destek sınırlıdır; pratik çözüm, WSL 2 içinde Linux ortamı kurmaktır. Ayrıca resmî Docker imajı, bağımlılık kurulumunu atlatmanın en güvenilir yoludur.

Kurulum Adımları

pip ile Kurulum

1. CUDA 12.8+ sürücüsünün kurulu ve nvidia-smi çıktısının çalıştığı doğrulanır.
2. Sanal ortam oluşturulur ve vLLM kurulur.

python -m venv .venv
source .venv/bin/activate
pip install vllm

3. Kurulum, PyTorch dahil tüm bağımlılıkları beraberinde getirir; bu yüzden indirme boyutu birkaç GB’dir.
4. Kurulum doğrulanır.

python -c "import vllm; print(vllm.__version__)"

Docker ile Kurulum

Bağımlılık sorunlarını tamamen ortadan kaldırmak isteyenler için resmî imaj önerilir:

docker run --gpus all -p 8000:8000 vllm/vllm-openai --model meta-llama/Llama-3.1-8B-Instruct

Konteyner, açılışta modeli indirir ve OpenAI uyumlu sunucuyu başlatır; model dizini bir volume’a bağlanarak yeniden indirmelerin önüne geçilir.

Sunucu Başlatma ve OpenAI Uyumlu API

Kurulumdan sonra sunucu tek komutla başlatılır:

vllm serve meta-llama/Llama-3.1-8B-Instruct

Sunucu varsayılan olarak 8000 numaralı bağlantı noktasında dinler ve OpenAI API’siyle birebir uyumlu uç noktalar sunar. OpenAI istemcileri yalnızca taban adresi değiştirilerek kullanılır:

curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "meta-llama/Llama-3.1-8B-Instruct", "messages": [{"role": "user", "content": "Merhaba"}]}'

Python tarafında OpenAI SDK’sı, base_url parametresi yerel sunucuya çevrilerek aynen kullanılır. Model adı olarak başlatmada verilen değer yazılır. Çok modelli düzenlerde her model için ayrı sunucu ve bağlantı noktası çalıştırılabilir; ayrıca sunucu, kullanılabilir modelleri listeleme uç noktası da sağlar.

Hugging Face dışından indirilmiş yerel model dizinleri de desteklenir; serve komutuna model adı yerine yerel klasör yolu verilerek GGUF olmayan saf PyTorch ağırlıkları barındıran dizinler kullanılabilir. Yerel dosya kullanımı, internet erişimi olmayan ortamlar için standart yöntemdir.

Performans Ayarları

vLLM’in en önemli ayarı, bellek kullanım oranını belirleyen gpu-memory-utilization değeridir; varsayılan yüksek bir orandır ve aynı GPU’da başka iş yükü varsa düşürülmesi gerekir:

vllm serve ornek-model --gpu-memory-utilization 0.85 --max-model-len 8192

max-model-len, desteklenecek en uzun bağlamı sınırlar; bilinçli sınırlandırma, bellek ayırımını küçültüp daha fazla eşzamanlı istek alanı açar. Eşzamanlılık tarafında sürekli batchleme otomatik çalışır; yük testi araçlarıyla sunucunun istek kapasitesi ölçülerek kapasite planlaması yapılır. Çoklu GPU düzenlerinde tensör paralelliği, tensor-parallel-size parametresiyle etkinleştirilir ve büyük modeller birden çok karta dağıtılır.

Ölçeklendirme ve Çoklu GPU Düzenleri

Tek kartın sınırını aşan modeller için vLLM, iki ana ölçekleme yolu sunar. Tensör paralelliği, modeli katman içinde birden çok GPU’ya böler; her kart hesaplamanın bir dilimini yürütür ve kartlar arasında düzenli iletişim yapılır. tensor-parallel-size parametresiyle etkinleştirilir ve kart sayısının ikinin katları olması yaygın bir tercihtir. Büyük yoğun modellerin ve MoE mimarilerinin tek karta sığmadığı düzenlerde bu yol, doğal çözümdür. İkinci yol, ayrık paralelliktir; modelin farklı katmanları sıralı biçimde farklı kartlara yerleşir ve iletişim yükü daha düşüktür ancak kartlardan bazıları bekleme durumunda kalabilir.

Ölçekleme kararında bellek hesabı belirleyicidir. Tensör paralelliği, model ağırlıklarını kartlara bölmesine rağmen bağlam önbelleğini ve aktivasyonları her kartta kopyalayabilir; bu yüzden beklenen bellek tasarrufu her zaman doğrusal olmaz. Çok kartlı düzenlerde kartların aynı modele ve sürücü sürümüne sahip olması, NVMe hızında bir depolama ile modelin hızlı yüklenmesi ve yüksek bant genişlikli kart arası bağlantı (NVLink bulunduğunda) performansı belirgin biçimde artırır. Sunucu tarafında ölçekleme kararı vermeden önce tek kartta daha küçük modelle yeterli kapasitenin elde edilip edilemeyeceği hesaplanmalıdır; operasyonel sadelik, çoğu senaryoda paha biçilmez bir değerdir.

Yük Testi ve Kapasite Planlama

vLLM’in verim üstünlüğü ancak yük altında ortaya çıkar; boşta çalışan sunucu, tek kullanıcıya hizmet veren motorla benzer performans verir. Kapasite planlaması bu yüzden yük testiyle başlar: gerçekçi istek uzunlukları, gerçekçi eşzamanlılık düzeyleri ve gerçekçi yanıt uzunluklarıyla simülasyon yapılır. Sistemin dört ölçütü izlenir: aktarılan token hızı, istek başına ilk token gecikmesi, istek başına tamamlanma süresi ve hata oranı. Eşzamanlılık arttıkça aktarılan token hızı önce yükselir, sonra doygunluğa ulaşır; gecikme ise doygunluk sonrasında hızla büyür. Kapasite eşiği, gecikmenin kabul edilebilir sınırı aştığı noktadır.

Bellek ayırım oranı ve maksimum bağlam uzunluğu, kapasite denkleminin iki ana kolu satar. Bağlam sınırını gerçek kullanıma göre kısmak, aynı kartta çok daha fazla eşzamanlı istek alanı açar; çoğu sohbet uygulaması 4-8 bin token bağlamla yeterliyken, her istek için 32 bin bağlam ayırmak kapasiteyi boşa harcar. Ayrıca istek sıralama politikaları, uzun isteklerin kısa istekleri kilitlemesini önleyen ayarlarla düzenlenebilir. Planlamanın son adımı büyüme payıdır: trafiğin artış eğrisine göre kapasiteye yüzde 20-30 pay bırakmak, ani yükselmelerde hizmet sürekliliğini korur.

Karşılaştırmalı Konum ve Seçim Rehberi

vLLM’in ekosistemdeki yerini netleştirmek, doğru araç seçimini kolaylaştırır. Ollama, bireysel kullanım ve kolaylık isteyen senaryoların en pratik çözümüdür; kurulumu dakikalar sürer ve geniş model kütüphanesine tek komutla erişilir. llama.cpp, donanım yelpazesinin genişliğinde ve ince ayar derinliğinde rakipsizdir; CPU ve kenar cihazlarında doğal tercihtir. vLLM ise GPU üzerinde yüksek eşzamanlılık ve maksimum verim gerektiren servislerin motorudur: çok kullanıcılı API’ler, iç platformlar ve yoğun toplu işler bu sınıfa girer.

Seçim, üç soruya dayanır. Eşzamanlı kullanıcı sayısı nedir? Tek-iki kullanıcı için Ollama yeterliyken, düzinelerce eşzamanlı istek vLLM’in tasarım amacıdır. Donanım nedir? GPU olmayan ortamlarda tartışma zaten kapalıdır. Yönetim kapasitesi nedir? vLLM, sürümler ve bellek ayarları konusunda daha titiz yönetim ister; buna karşılık verim karşılığını fazlasıyla öder. Üç araç birbirinin alternatifi değil, ölçek merdiveninin basamaklarıdır: prototip Ollama’da, ince ayar llama.cpp’de, üretim vLLM’de kurulabilir ve OpenAI uyumlu API ortak arayüz sayesinde uygulama kodu bu geçişlerden neredeyse hiç etkilenmez.

Yaygın Hatalar ve İpuçları

En sık görülen hata, VRAM yetersizliğidir; başlatma sırasında bellek ayırımı başarısız olursa gpu-memory-utilization düşürülür, max-model-len kısılır veya daha küçük bir model seçilir. CUDA sürüm uyumsuzluğu, ikinci yaygın sorundur; sürümün en az 12.8 olduğu doğrulanır. Windows’ta doğrudan kurulum başarısız olursa WSL 2 veya Docker yoluna geçilir. Hugging Face erişim kısıtlamaları, bazı modellerin indirilememesine yol açar; bu modeller için sağlayıcı sitesinde erişim talebi onaylanmalıdır.

Performans ipuçları arasında, model dosyalarının bir volume’ta saklanarak konteyner yeniden başlatmalarında korunması, yük profiline göre max-model-len’in gerçek kullanıma göre sınırlandırılması ve benzer modellerin aynı sunucuda çoğaltılmaması sayılabilir. Ölçüm için sunucunun kendi göstergeleri ve dış yük testi araçları birlikte kullanılmalıdır; verim (istek/saniye) ile gecikmenin (tokens/s) ayrı ayrı raporlanması, kapasite kararlarının doğru verilmesini sağlar. Son olarak vLLM hızla gelişen bir proje olduğu için sürüm yükseltmeleri her zaman sanal ortamda test edilip üretime taşınmalıdır.