vLLM Quickstart: wydajne serwowanie modeli LLM – w 2026 roku

vLLM to silnik inferencji i serwowania o wysokiej przepustowości i wydajnym zarządzaniu pamięcią dla dużych modeli językowych (LLM), opracowany przez Sky Computing Lab na UC Berkeley.

Algorytm PagedAttention traktuje bufor KV jak wirtualne strony pamięci systemu operacyjnego i łączy go z ciągłym grupowaniem (continuous batching) — to połączenie sprawiło, że vLLM stał się domyślnym silnikiem do serwowania LLM w środowiskach produkcyjnych. Aby zobaczyć, jak vLLM porównuje się z Ollama, Docker Model Runner, LocalAI i dostawcami chmurowymi — w tym w kontekście kosztów i kompromisów infrastrukturalnych — zobacz Hosting LLM: Porównanie infrastruktury lokalnej, self-hosted i chmurowej.

Ten poradnik jest aktualny dla wersji vLLM v0.31.0 (październik 2026). Jeśli przychodzisz z starszych samouczków, dwie rzeczy ostatnio się zmieniły: polecenie python -m vllm.entrypoints.openai.api_server jest przestarzałe i wyświetla ostrzeżenie — standardowym CLI jest teraz vllm serve — a gotowe koła (wheels) domyślnie celują w CUDA 12.9, a nie 11.8.

Czym jest vLLM?

vLLM (virtual LLM) to biblioteka open source do szybkiej inferencji i serwowania LLM, która szybko stała się standardem branżowym dla wdrożeń produkcyjnych. Wydany w 2023 roku, wprowadził PagedAttention, przełomową technikę zarządzania pamięcią, która radykalnie zwiększa wydajność serwowania.

Główne cechy

Wysoka przepustowość: Benchmarki z czasów premiery vLLM raportowały 14–24-krotnie wyższą przepustowość niż HuggingFace Transformers na tym samym sprzęcie, a silnik utrzymuje tę przewagę dzięki ciągłemu grupowaniu, zoptymalizowanym jądrze CUDA oraz algorytmowi PagedAttention, który eliminuje fragmentację pamięci.

Kompatybilność z API OpenAI: vLLM zawiera wbudowany serwer API w pełni kompatybilny z formatem OpenAI. Umożliwia to płynną migrację z OpenAI na infrastrukturę self-hosted bez zmiany kodu aplikacji. Wystarczy skierować klienta API do punktu końcowego vLLM i zadziała to transparentnie.

Algorytm PagedAttention: Kluczową innowacją za wydajnością vLLM jest PagedAttention, który stosuje koncepcję stronicowania pamięci wirtualnej do mechanizmów uwagi. Zamiast alokować ciągłe bloki pamięci dla buforów KV (co prowadzi do fragmentacji), PagedAttention dzieli pamięć na bloki o stałym rozmiarze, które mogą być alokowane na żądanie. To zmniejsza marnotrawstwo pamięci nawet o 4 razy i umożliwia znacznie większe rozmiary partii (batch).

Ciągłe grupowanie (Continuous Batching): W przeciwieństwie do statycznego grupowania, gdzie czekasz na ukończenie wszystkich sekwencji, vLLM używa ciągłego (przewijającego się) grupowania. W momencie, gdy jedna sekwencja kończy się, nowa może zostać dodana do partii. To maksymalizuje wykorzystanie GPU i minimalizuje opóźnienia dla przychodzących żądań.

Wsparcie dla wielu GPU: vLLM obsługuje równoległość tensorową i równoległość liniową (pipeline parallelism) do rozkładania dużych modeli na wielu GPU. Może efektywnie serwować modele, które nie mieszczą się w pamięci pojedynczego GPU, wspierając konfiguracje od 2 do 8+ GPU.

Szerokie wsparcie dla modeli: Kompatybilny z popularnymi architekturami modeli, w tym LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma i wieloma innymi. Obsługuje zarówno modele wytrenowane na polecenia (instruction-tuned), jak i modele bazowe z HuggingFace Hub.

Kiedy używać vLLM

vLLM wyróżnia się w specyficznych scenariuszach, gdzie jego mocne strony błyszczą:

Produkcyjne usługi API: Gdy musisz serwować LLM wielu użytkownikom równoległym przez API, wysoka przepustowość i efektywne grupowanie vLLM czynią go najlepszym wyborem. Firmy uruchamiające czaty boty, asystentów kodu lub usługi generowania treści korzystają z jego zdolności do obsługi setek żądań na sekundę.

Obciążenia o wysokiej współbieżności: Jeśli Twoja aplikacja ma wielu jednoczesnych użytkowników wysyłających żądania, ciągłe grupowanie i PagedAttention w vLLM pozwalają serwować więcej użytkowników na tym samym sprzęcie w porównaniu z alternatywami.

Optymalizacja kosztów: Gdy koszty GPU są istotne, wyższa przepustowość vLLM oznacza, że możesz serwować taki sam ruch z mniejszą liczbą GPU, bezpośrednio obniżając koszty infrastruktury. 4-krotna efektywność pamięci z PagedAttention pozwala również na używanie mniejszych, tańszych instancji GPU.

Wdrożenia na Kubernetes: Bezstanowy (stateless) design i architektura przyjazna kontenerom sprawiają, że vLLM jest idealny dla klastrów Kubernetes. Jego spójna wydajność pod obciążeniem i proste zarządzanie zasobami dobrze integrują się z infrastrukturą chmuroznawczą.

Kiedy NIE używać vLLM: Do rozwoju lokalnego, eksperymentów lub scenariuszy jednoużytkownikowych, narzędzia takie jak Ollama lub llama.cpp zapewniają lepsze doświadczenie użytkownika z prostszą konfiguracją. Złożoność vLLM jest uzasadniona, gdy potrzebujesz jego zalet wydajnościowych dla obciążeń produkcyjnych.

Jak zainstalować vLLM

Wymagania wstępne

Przed instalacją vLLM upewnij się, że Twój system spełnia te wymagania:

• System operacyjny: Linux z glibc 2.35 lub nowszym (Ubuntu 22.04+, Debian 12+, RHEL 9+)
• GPU: NVIDIA GPU o możliwości obliczeniowej 7.5 lub wyższej (T4, A10, A100, L4, H100, B200, serie RTX 20/30/40/50). Starsze karty generacji 7.0, takie jak V100, nie są już na liście wspieranych. GPU AMD są wspierane przez osobne koła ROCm — zobacz ROCm vs Vulkan dla lokalnego hostingu LLM na AMD po szczegóły dotyczące obrazów, flag urządzeń i zastrzeżeń dotyczących pokrycia kerneli dla AMD.
• CUDA: Domyślne koła pip są skompilowane dla CUDA 12.9; warianty 12.8 i 13.0 są publikowane obok nich. GPU Blackwell (B200, GB200) wymagają CUDA 12.8+. Sterownik NVIDIA musi być nowszy lub równy wersji wymaganej przez zainstalowaną wersję CUDA.
• Python: 3.10 do 3.13 — wersja 3.12 jest zalecana (koła ROCm są dostępne tylko dla 3.12)
• VRAM: Minimum 16GB dla modeli 7B, 24GB+ dla 13B, 40GB+ dla większych modeli

Instalacja za pomocą pip

Zalecana instalacja używa uv do utworzenia środowiska Python 3.12 i automatycznego wyboru odpowiedniego backendu CUDA dla PyTorch (--torch-backend=auto inspekcjonuje zainstalowany sterownik). Aby zgłębić szczegóły dotyczące samego uv, zobacz uv: Nowy menedżer pakietów, projektów i środowisk Pythona:

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

# Zweryfikuj instalację
python -c "import vllm; print(vllm.__version__)"

Zwykły pip również zadziała:

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

Domyślne koła są skompilowane dla CUDA 12.9. Jeśli potrzebujesz innej wersji CUDA, pobierz odpowiedni indeks koła PyTorch — na przykład, dla CUDA 12.8:

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

Stare, przypięte koła, takie jak vllm==0.4.2+cu121, już nie istnieją w tej formie. Mieszanie vLLM w istniejącym środowisku z innym buildem PyTorch to częsta przyczyna awarii instalacji; projekt zaleca świeże środowisko, a build ze źródła, gdy potrzebujesz niestandardowego celu CUDA.

Instalacja z Docker

Docker zapewnia najpewniejszą metodę wdrożenia, szczególnie w produkcji. Przypnij obraz do wersji release zamiast latest, aby aktualizacje były celowe, i zauważ, że istnieją obrazy wariantowe dla CUDA 12.9 (sufiks tagu -cu129), AMD ROCm (vllm-openai-rocm), CPU (vllm-openai-cpu) i Intel XPU (vllm-openai-xpu):

# Pobierz oficjalny obraz vLLM
docker pull vllm/vllm-openai:v0.31.0

# Uruchom vLLM z obsługą GPU
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

Flaga --ipc=host jest ważna dla konfiguracji wielo-GPU, ponieważ umożliwia prawidłową komunikację międzyprocesową.

Budowanie ze źródła

Dla najnowszych funkcji lub niestandardowych modyfikacji, zbuduj ze źródła:

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

Szybki start z vLLM

Uruchamianie pierwszego modelu

Uruchom vLLM z modelem za pomocą interfejsu wiersza poleceń:

# Pobierz i serwuj model z API kompatybilnym z OpenAI
vllm serve Qwen/Qwen3-8B \
    --port 8000

vllm serve jest bieżącym CLI dla serwera kompatybilnego z OpenAI. Starsze wywołanie python -m vllm.entrypoints.openai.api_server nadal działa, ale wyświetla ostrzeżenie o przestarzałości i może zostać usunięte w przyszłej wersji, więc zaktualizuj skrypty lub manifesty Kubernetes, które go wciąż używają.

vLLM automatycznie pobierze model z HuggingFace Hub (jeśli nie jest w cache) i uruchomi serwer. Zobaczysz wyjście wskazujące, że serwer jest gotowy:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Wysyłanie żądań API

Po uruchomieniu serwera możesz wysyłać żądania używając klienta Python OpenAI lub curl:

Użycie curl:

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

Użycie klienta Python OpenAI:

from openai import OpenAI

# Skieruj do swojego serwera vLLM
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM ignoruje to, chyba że uruchomisz serwer z --api-key
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

API Chat Completions:

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

Zaawansowana konfiguracja

vLLM oferuje wiele parametrów do optymalizacji wydajności:

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # Użyj 95% pamięci GPU
    --max-model-len 32k \            # Maksymalna długość sekwencji (8192 i 32k działają)
    --tensor-parallel-size 2 \       # Użyj 2 GPU z równoległością tensorową
    --dtype float16 \                # Użyj precyzji FP16
    --max-num-seqs 256               # Maksymalny rozmiar partii

Wyjaśnienie kluczowych parametrów:

• --gpu-memory-utilization: Ułamek pamięci GPU dla wykonawcy modelu (domyślnie 0.92). Wyższe wartości pozwalają na większe partie, ale pozostawiają mniej marginesu na szczyty pamięci.
• --max-model-len: Maksymalna długość kontekstu. Akceptuje liczbę tokenów lub czytelne wartości jak 32k. Zmniejszenie tego oszczędza pamięć na większe partie.
• --tensor-parallel-size: Liczba GPU, na które ma zostać podzielony model.
• --dtype: Typ danych dla wag (auto, float16, bfloat16, float32). auto podąża za typem danych checkpointu, co zwykle jest tym, czego potrzebujesz.
• --max-num-seqs: Maksymalna liczba sekwencji w partii.
• --max-num-active-seqs: Ogranicza dopuszczenie sekwencji w stanie RUNNING niezależnie od max_num_seqs (nowe w v0.31.0) — przydatne do ograniczania opóźnień bez zmniejszania okna partii harmonizatora.

vLLM vs Ollama

vLLM jest zaprojektowany do produkcyjnego serwowania o wysokiej przepustowości i dla wielu użytkowników, z ciągłym grupowaniem, PagedAttention i wsparciem dla wielu GPU. Ollama optymalizuje się dla szybkiej konfiguracji lokalnej, wygody jednoużytkownikowej i prostego zarządzania modelami.

Aby uzyskać szczegółowy przewodnik decyzyjny obejmujący sygnały migracji, kroki planowania, konfigurację Docker Compose i praktyczną listę kontrolną, zobacz Ollama do vLLM: Kiedy migrować swój lokalny serwer LLM.

vLLM vs Docker Model Runner

Model Runner od Docker to ich oficjalne rozwiązanie do lokalnego wdrażania modeli AI. Jak porównuje się z vLLM?

Filozofia architektury

Docker Model Runner dąży do bycia „Dockerem dla AI” – prostym, znormalizowanym sposobem uruchamiania modeli AI lokalnie z tą samą łatwością, co uruchamianie kontenerów. Abstrahuje złożoność i zapewnia spójny interfejs w różnych modelach i ramach.

vLLM to specjalistyczny silnik inferencji skoncentrowany wyłącznie na serwowaniu LLM z maksymalną wydajnością. To narzędzie niższego poziomu, które konteneryzujesz w Dockerze, a nie kompletna platforma.

Konfiguracja i rozpoczęcie pracy

Instalacja Docker Model Runner jest prosta dla użytkowników Docker:

docker model pull llama3:8b
docker model run llama3:8b

Ta podobieństwo do workflow obrazów Docker sprawia, że jest natychmiastowa znajoma dla developerów już używających kontenerów; pełny zestaw poleceń znajduje się w ściągawce Docker Model Runner.

vLLM wymaga więcej początkowej konfiguracji (Python, CUDA, zależności) lub używania gotowych obrazów Docker:

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <nazwa-modelu>

Cechy wydajnościowe

vLLM zapewnia wyższą przepustowość dla scenariuszy wielu użytkowników dzięki PagedAttention i ciągłemu grupowaniu. Dla produkcyjnych usług API obsługujących setki żądań na sekundę, optymalizacje vLLM zapewniają o 2–5 razy lepszą przepustowość niż ogólne podejścia do serwowania.

Docker Model Runner koncentruje się na łatwości użycia, a nie na maksymalnej wydajności. Jest odpowiedni dla rozwoju lokalnego, testów i umiarkowanych obciążeń, ale nie wdraża zaawansowanych optymalizacji, które sprawiają, że vLLM wyróżnia się przy skali.

Wsparcie dla modeli

Docker Model Runner zapewnia starannie dobraną bibliotekę modeli z dostępem w jednym poleceniu do popularnych modeli. Obsługuje wiele frameworków (nie tylko LLM), w tym Stable Diffusion, Whisper i inne modele AI, czyniąc go bardziej wszechstronnym dla różnych obciążeń AI.

vLLM specjalizuje się w inferencji LLM z głębokim wsparciem dla modeli językowych opartych na transformerach. Obsługuje każdy kompatybilny z HuggingFace LLM, ale nie rozszerza się na inne typy modeli AI, takie jak generowanie obrazów lub rozpoznawanie mowy.

Wdrożenie produkcyjne

vLLM jest sprawdzony w produkcji w firmach takich jak Anthropic, Replicate i wielu innych, serwujących miliardy tokenów dziennie. Jego cechy wydajności i stabilność pod ciężkim obciążeniem czynią go de facto standardem dla produkcyjnego serwowania LLM.

Docker Model Runner jest nowszy i pozycjonuje się bardziej dla scenariuszy rozwoju i testów lokalnych. Chociaż mógłby serwować ruch produkcyjny, brakuje mu sprawdzonego track recordu i optymalizacji wydajności wymaganych przez wdrożenia produkcyjne.

Ekosystem integracji

vLLM integruje się z narzędziami infrastruktury produkcyjnej: operatorami Kubernetes, metrykami Prometheus, Ray do rozproszonych wdrożeń oraz rozległą kompatybilnością z API OpenAI dla istniejących aplikacji.

Docker Model Runner integruje się naturalnie z ekosystemem Docker i Docker Desktop. Dla zespołów już znormalizowanych na Dockerze, ta integracja zapewnia spójne doświadczenie, ale mniej specjalistycznych funkcji serwowania LLM.

Kiedy używać każdego

Używaj vLLM do:

• Produkcyjnych usług API LLM
• Wdrożeń o wysokiej przepustowości i wielu użytkowników
• Kosztowo wrażliwych wdrożeń chmurowych wymagających maksymalnej efektywności
• Środowisk Kubernetes i chmuroznawczych
• Gdy potrzebujesz sprawdzonej skalowalności i wydajności

Używaj Docker Model Runner do:

• Rozwoju i testów lokalnych
• Uruchamiania różnych typów modeli AI (nie tylko LLM)
• Zespołów mocno zainwestowanych w ekosystem Docker
• Szybkich eksperymentów bez konfiguracji infrastruktury
• Celów edukacyjnych i naukowych

Podejście hybrydowe: Wielu zespołów rozwija lokalnie z Docker Model Runner dla wygody, a następnie wdraża z vLLM w produkcji dla wydajności. Obrazy Docker Model Runner można również użyć do uruchamiania kontenerów vLLM, łącząc oba podejścia.

Najlepsze praktyki w wdrożeniach produkcyjnych

Wdrożenie Docker

Utwórz produkcyjnie gotową konfigurację Docker Compose:

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Wdrożenie na Kubernetes

Wdrażaj vLLM na Kubernetes dla produkcyjnej skali:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Monitorowanie i obserwowalność

Serwer kompatybilny z OpenAI wystawia metryki Prometheus w /metrics domyślnie — nie są potrzebne dodatkowe flagi:

curl -s http://localhost:8000/metrics | grep '^vllm:'

Kluczowe metryki do monitorowania:

• vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — żądania w stanach RUNNING, WAITING i SWAPPED harmonizatora
• vllm:kv_cache_usage_perc — ułamek użytych bloków bufora KV (0–1)
• vllm:time_to_first_token_seconds — histogram TTFT (czas do pierwszego tokena)
• vllm:time_per_output_token_seconds — prędkość generacji na token
• vllm:num_preemptions_total — kumulacyjne preempcje; rosnący licznik oznacza, że bufor KV jest przepełniony i żądania są przeliczane

Aby zobaczyć przykłady PromQL, progi alarmowe i dashboardy wokół serwowania LLM, zobacz Monitorowanie inferencji LLM w produkcji (2026): Prometheus i Grafana dla vLLM, TGI, llama.cpp.

Optymalizacja wydajności

Optymalizuj wykorzystanie pamięci GPU: Domyślna wartość to 0.92; dostosuj na podstawie obserwowanego zachowania. Wyższe wartości pozwalają na większe partie, ale ryzykują błędy OOM (Out of Memory) podczas szczytów ruchu.

Dostosuj maksymalną długość sekwencji: Jeśli Twój przypadek użycia nie wymaga pełnej długości kontekstu, zmniejsz --max-model-len. To zwalnia pamięć na większe partie. Na przykład, jeśli potrzebujesz tylko kontekstu 4K, ustaw --max-model-len 4096 zamiast używać maksimum modelu (często 8K–32K).

Wybierz odpowiednią kwantyzację: Dla modeli, które to wspierają, użyj wersji skwantyzowanych (8-bit, 4-bit), aby zmniejszyć pamięć i zwiększyć przepustowość:

--quantization awq  # Dla modeli skwantyzowanych AWQ
--quantization gptq # Dla modeli skwantyzowanych GPTQ

Cache prefiksów (Prefix Caching): Cache prefiksów jest domyślnie włączone w bieżącym silniku, więc żądania dzielące prefiks promptu (stały systemowy prompt, szablon kontekstu RAG) ponownie wykorzystują jego bufor KV bez żadnej flagi. Wyłącz go z --no-enable-prefix-caching dla obciążeń z wieloma unikalnymi długimi promptami, gdzie prowadzenie ewidencji cache nic nie daje.

Rozwiązywanie typowych problemów

Błędy braku pamięci (Out of Memory)

Objawy: Serwer crashuje z błędami CUDA out of memory.

Rozwiązania:

• Zmniejsz --gpu-memory-utilization do 0.85 lub 0.80
• Zmniejsz --max-model-len, jeśli Twój przypadek użycia na to pozwala
• Obniż --max-num-seqs, aby zmniejszyć rozmiar partii
• Użyj skwantyzowanej wersji modelu
• Włącz równoległość tensorową, aby rozłożyć na więcej GPU

Dwa odrębne kształty błędów OOM wymagają różnych napraw. OOM przy starcie zdarza się przed jakimkolwiek żądaniem: vLLM profiluje pamięć i nie udaje się alokować nawet minimalnego bufora KV, więc obniżenie --max-num-seqs nie pomaga — zmniejsz --max-model-len lub podwyższ --gpu-memory-utilization, jeśli masz zapas. OOM podczas działania pod obciążeniem może pochodzić z pamięci na przechwytywanie grafów CUDA (CUDA-graph capture), która skaluje się z --max-num-seqs, ale znajduje się poza rozliczaniem bufora KV; uruchom raz z --enforce-eager, aby sprawdzić, czy to grafy CUDA są brakującą pamięcią, i przetestuj dokładnie tę samą konfigurację, zanim winowajcą zostanie cache. Jeśli uruchomienia na identycznym sprzęcie nadal się udają z tą samą alokacją, przekaż wartość --kv-cache-memory-bytes, którą vLLM loguje przy starcie, aby pominąć fazę profilowania przy kolejnych uruchomieniach.

Na pojedynczej karcie 16 GB większość tych błędów OMM śledzi się do budżetu bufora KV, a nie samych wag — Bufor KV na GPU 16 GB pokazuje dokładny wzór, typ danych KV-cache FP8 i kompromisy cache prefiksów za --max-model-len i --max-num-seqs, zanim sięgniesz po mniejszy model.

Wolny start

Objawy: Serwer zajmuje minuty od uruchomienia do „Application startup complete”.

Rozwiązania:

• Ładowanie wag, kompilacja i przechwytywanie grafów CUDA dominują czas uruchamiania — --enforce-eager pomija zarówno kompilację, jak i przechwytywanie, i mówi Ci, ile z bootu one kosztują, za ceną szybkości dekodowania w stanie ustalonym
• Ponownie użyj zalogowanej wartości --kv-cache-memory-bytes, aby pominąć fazy profilowania pamięci i szacowania grafów CUDA przy powtarzanych uruchomieniach
• W v0.30.0+, polecenie vllm preload uruchamia trwały daemon cache wag, który trzyma skwantyzowane wagi rezydentne w pamięci GPU, więc restarty silnika mapują wagi przez CUDA IPC zamiast ponownego ładowania z dysku (--load-format ipc_cache)
• Dla checkpointów NVFP4, które kończą się OOM podczas kompilacji przy starcie, ograniczanie wątków budowania z MAX_JOBS=4 i NVCC_THREADS=4 to powszechnie stosowana poprawka — spowalnia build JIT, ale zatrzymuje OOM

Niska przepustowość

Objawy: Serwer obsługuje mniej żądań, niż się spodziewano.

Rozwiązania:

• Zwiększ --max-num-seqs, aby dozwolić na większe partie
• Podnieś --gpu-memory-utilization, jeśli masz zapas
• Sprawdź, czy CPU nie jest wąskim gardłem z htop – rozważ szybsze CPU
• Zweryfikuj wykorzystanie GPU z nvidia-smi – powinno wynosić 95%+
• Włącz FP16, jeśli używasz FP32: --dtype float16

Długi czas do pierwszego tokena

Objawy: Wysokie opóźnienia przed rozpoczęciem generacji.

Rozwiązania:

• Używaj mniejszych modeli dla aplikacji wrażliwych na opóźnienia
• Cache prefiksów jest domyślnie włączone – zweryfikuj, czy jest aktywny, zamiast ponownie dodawać flagi
• Zmniejsz --max-num-seqs, aby priorytetyzować opóźnienia nad przepustowością
• Rozważ spekulatywne dekodowanie dla wspieranych modeli
• Zoptymalizuj konfigurację równoległości tensorowej

Awarie ładowania modelu

Objawy: Serwer nie może się uruchomić, nie może załadować modelu.

Rozwiązania:

• Zweryfikuj, czy nazwa modelu dokładnie pasuje do formatu HuggingFace
• Sprawdź połączenie sieciowe z HuggingFace Hub
• Upewnij się, że jest wystarczająca ilość miejsca na dysku w ~/.cache/huggingface
• Dla modeli z bramą (gated models), ustaw zmienną środowiskową HF_TOKEN
• Spróbuj pobrać ręcznie z hf download <model> (lub huggingface-cli download <model> na starszych instalacjach)

Zaawansowane funkcje

Spekulatywne dekodowanie

vLLM wspiera spekulatywne dekodowanie, gdzie mniejszy model szkicujący (draft) proponuje tokeny, które większy model docelowy weryfikuje. Może to przyspieszyć generowanie o 1,5–2 razy. Aby uzyskać kompleksowy przewodnik po metodach spekulatywnego dekodowania — modele szkicujące, EAGLE-3, P-EAGLE i n-gram — zobacz Spekulatywne dekodowanie: Szybsza inferencja bez utraty jakości.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

Stare flagi --speculative-model i --num-speculative-tokens zniknęły — konfiguracja przeszła do pojedynczego argumentu JSON --speculative-config, który również wybiera metodę (draft_model, ngram, rodzina EAGLE lub MTP dla modeli z natywnymi głowami predykcji wielotokenowej).

Adaptery LoRA

Serwuj wiele adapterów LoRA na bazie modelu bez ładowania wielu pełnych modeli:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/sciezka/do/sql-adapter \
                   code-lora=/sciezka/do/code-adapter

Następnie określ, który adapter ma być użyty dla każdego żądania, umieszczając jego nazwę w polu model — ten sam mechanizm skaluje się do dziesiątków adapterów specyficznych dla zadań (specyficznych dla klienta lub wariantów domenowych), z tylko modelem bazowym rezydentnym w pamięci:

response = client.completions.create(
    model="sql-lora",  # Użyj adaptera SQL
    prompt="Convert this to SQL: Show me all users created this month"
)

Cache prefiksów

Cache prefiksów unika ponownego obliczania bufora KV dla wspólnych prefiksów promptu i jest domyślnie włączone w bieżącym silniku.

Najbardziej się opłaca dla:

• Botów czatowych ze stałymi promptami systemowymi
• Aplikacji RAG ze spójnymi szablonami kontekstu
• Promptów few-shot powtarzanych między żądaniami

Dla żądań dzielących prefiks, czas do pierwszego tokena znacząco spada, ponieważ prefill dla wspólnej części jest pomijany.

Przykłady integracji

Integracja z LangChain

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

Aplikacja FastAPI

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

Benchmarki wydajności

Dane o wydajności ze świata realnego pomagają zilustrować zalety vLLM. Poniższe liczby pochodzą z dokumentacji z czasów premiery projektu i wczesnych pomiarów społeczności — traktuj je jako wskazówki rzędu wielkości efektu architektury, a nie jako bieżące wyniki dla dzisiejszej generacji modeli:

Porównanie przepustowości (Mistral-7B na GPU A100):

• vLLM: ~3500 tokenów/sekundę przy 64 równoległych użytkownikach
• HuggingFace Transformers: ~250 tokenów/sekundę przy tym samym poziomie współbieżności
• Ollama: ~1200 tokenów/sekundę przy tym samym poziomie współbieżności
• Wynik: vLLM zapewnia 14-krotną poprawę w porównaniu z podstawowymi implementacjami

Efektywność pamięci (LLaMA-2-13B):

• Standardowa implementacja: 24GB VRAM, 32 równoległe sekwencje
• vLLM z PagedAttention: 24GB VRAM, 128 równoległych sekwencji
• Wynik: 4 razy więcej równoległych żądań przy tej samej pamięci

Opóźnienia pod obciążeniem (Mixtral-8x7B na 2xA100):

• vLLM: P50 opóźnienie 180ms, P99 opóźnienie 420ms przy 100 żądaniach/s
• Standardowe serwowanie: P50 opóźnienie 650ms, P99 opóźnienie 3200ms przy 100 żądaniach/s
• Wynik: vLLM utrzymuje spójne opóźnienia pod wysokim obciążeniem

Analiza kosztów

Rozumienie implikacji kosztowych wyboru vLLM:

Scenariusz: Serwowanie 1M żądań/dzień

Z standardowym serwowaniem:

• Wymagane: 8x GPU A100 (80GB)
• Koszt AWS: ~$32/godzinę × 24 × 30 = $23 040/miesiąc
• Koszt za 1M tokenów: ~$0,75

Z vLLM:

• Wymagane: 2x GPU A100 (80GB)
• Koszt AWS: ~$8/godzinę × 24 × 30 = $5 760/miesiąc
• Koszt za 1M tokenów: ~$0,19
• Oszczędności: $17 280/miesiąc (75% redukcja)

Ta przewaga kosztowa rośnie ze skalą. Organizacje serwujące miliardy tokenów miesięcznie oszczędzają setki tysięcy dolarów, używając zoptymalizowanego serwowania vLLM zamiast naiwnych implementacji.

Zagadnienia bezpieczeństwa

Autoryzacja

vLLM dostarcza wbudowaną flagę --api-key, ale zgodnie z oficjalną dokumentacją uwierzytelnia tylko punkty końcowe pod prefiksami ścieżek /v1, /v2 i /inference — inne punkty końcowe na tym samym serwerze pozostają bez autoryzacji. Traktuj to jako jedną warstwę, a nie całe rozwiązanie; dla pełnego pokrycia, implementuj uwierzytelnianie na poziomie proxy odwrotnego:

# Konfiguracja Nginx
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

Albo użyj bram API, takich jak Kong, Traefik lub AWS API Gateway, dla uwierzytelniania i limitowania tempa żądań na poziomie korporacyjnym.

Izolacja sieciowa

Uruchamiaj vLLM w sieciach prywatnych, nie bezpośrednio wystawianym na internet:

# Przykład NetworkPolicy w Kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

Limitowanie tempa żądań (Rate Limiting)

Implementuj limitowanie tempa żądań, aby zapobiec nadużyciom:

# Przykład używający Redis do limitowania tempa żądań
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # Okno 60 sekund
    
    if requests > 60:  # 60 żądań na minutę
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

Kontrola dostępu do modeli

Dla wdrożeń wielodzierżcowych (multi-tenant), kontroluj, którzy użytkownicy mogą uzyskać dostęp do których modeli:

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # Wszystkie modele
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

Przewodnik migracyjny

Z OpenAI na vLLM

Migracja z OpenAI na self-hosted vLLM jest prosta dzięki kompatybilności API:

Przed (OpenAI):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

Po (vLLM):

from openai import OpenAI

client = OpenAI(
    base_url="https://twoj-serwer-vllm.com/v1",
    api_key="twoj-wewnetrzny-key"  # Jeśli dodałeś uwierzytelnianie
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

Wymagane są tylko dwie zmiany: aktualizacja base_url i nazwy model. Wszystkie inne pozostają identyczne.

Z Ollama na vLLM

Ollama używa innego formatu API. Podstawowa zmiana po stronie klienta to przełączenie z punktu REST Ollama na API kompatybilne z OpenAI w vLLM:

API Ollama:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

Ekwivalent vLLM:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

API Ollama to prosty REST z własnym kształtem żądania, podczas gdy vLLM posługuje się protokołem OpenAI — ta różnica w formacie API jest główną zmianą po stronie klienta, a etapowe podejście (uruchamianie obu serwerów, przenoszenie ruchu punkt po punkcie) jest omówione w przewodniku migracyjnym powiązanym wcześniej w tym artykule.

Z HuggingFace Transformers na vLLM

Bezpośrednia migracja użycia Python:

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM:

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

API Python vLLM jest prostsze i znacznie szybsze do inferencji partiami.

Ostatnie wydania: Co zmieniło się w 2026

Trzy wydania we wrześniu–październiku 2026 (v0.29.0, v0.30.0, v0.31.0) pokazują, w którą stronę idzie rozwój:

Szybkie restarty: vllm preload uruchamia trwały, per-GPU daemon cache wag, który trzyma skwantyzowane, TP-podzielone wagi rezydentne w pamięci GPU, więc zrestartowane silniki mapują je przez CUDA IPC (--load-format ipc_cache) zamiast ponownego ładowania z dysku. Eksperymentalne vllm snapshot create/restore tworzy snapshoty w pełni zainicjalizowanego silnika z CRIU.

Spekulatywne dekodowanie na Model Runner V2: Spekulatywne dekodowanie modelu szkicującego, niestandardowe procesory logitów i adaptacyjna weryfikacja przeszły na nowy model runner, z dodanym szkicownikiem LiLiCorr i asynchronicznym harmonizowaniem dla szkicownika DFlash.

Serwowanie dużych modeli MoE: Nowe zbalansowane backendy all2all dla równoległości eksperckiej (--all2all-backend moonep), DeepEPv2 z równoległością sekwencyjną, EPLB z nakładaniem wspólnych ekspertów i równoległość kontekstu prefill połączona z równoległością danych.

Kontrola harmonizowania: --max-num-active-seqs ogranicza dopuszczenie sekwencji RUNNING niezależnie od max_num_seqs, a kolejka oczekujących teraz harmonizuje najpierw żądania, które już trzymają bloki KV.

Elementy drogi rozwoju z starszych poradników vLLM dawno już się pojawiły — wsparcie GGUF, serwowanie multimodalne, rozdzielony prefill/decode i inferencja wielosерwerowa są częścią bieżących wydań, więc traktuj każdy samouczek, który wymienia je jako „wkrótce”, jako przestarzały. Notatki o wydaniach dla każdej wersji znajdują się na stronie wydań vLLM.

Przydatne linki

Powiązane artykuły na tej stronie

• Ściągawka Ollama - Kompletny referencja i ściągawka poleceń Ollama obejmująca instalację, zarządzanie modelami, użycie API i najlepsze praktyki dla lokalnego wdrożenia LLM. Niezbędne dla developerów używających Ollama obok lub zamiast vLLM.

• Docker Model Runner vs Ollama: Którego wybrać? - Szczegółowe porównanie Docker Model Runner i Ollama dla lokalnego wdrożenia LLM, analizujące wydajność, wsparcie GPU, kompatybilność API i przypadki użycia. Pomaga zrozumieć krajobraz konkurencyjny, w którym działa vLLM.

Zewnętrzne zasoby i dokumentacja

• Repozytorium vLLM GitHub - Oficjalne repozytorium vLLM z kodem źródłowym, kompleksową dokumentacją, przewodnikami instalacji i aktywnymi dyskusjami społeczności. Niezbędny zasób do bycia na bieżąco z najnowszymi funkcjami i rozwiązywaniem problemów.

• Dokumentacja vLLM - Oficjalna dokumentacja obejmująca wszystkie aspekty vLLM od podstawowej konfiguracji zaawansowanego strojenia. Zawiera referencje API, poradniki optymalizacji wydajności i najlepsze praktyki wdrożeniowe.

• Artykuł PagedAttention - Artykuł akademicki wprowadzający algorytm PagedAttention, który napędza efektywność vLLM. Niezbędna lektura do zrozumienia innowacji technologicznych stojących za zaletami wydajności vLLM.

• Blog vLLM - Oficjalny blog vLLM prezentujący ogłoszenia wydań, benchmarki wydajności, techniczne analizy i studia przypadków społeczności z wdrożeń produkcyjnych.

• Hub modeli HuggingFace - Kompleksowe repozytorium open-source LLM działających z vLLM. Szukaj modeli według rozmiaru, zadania, licencji i cech wydajności, aby znaleźć odpowiedni model dla swojego przypadku użycia.

• Dokumentacja Ray Serve - Dokumentacja frameworka Ray Serve do budowy skalowalnych, rozproszonych wdrożeń vLLM. Ray zapewnia zaawansowane funkcje, takie jak autoscaling, serwowanie wielu modeli i zarządzanie zasobami dla systemów produkcyjnych.

• NVIDIA TensorRT-LLM - NVIDIA TensorRT-LLM do silnie zoptymalizowanej inferencji na GPU NVIDIA. Alternatywa dla vLLM z innymi strategiami optymalizacji, przydatna do porównania i zrozumienia krajobrazu optymalizacji inferencji.

• Referencja API OpenAI - Oficjalna dokumentacja API OpenAI, z którą API vLLM jest kompatybilne. Odwołuj się do niej przy budowaniu aplikacji, które muszą działać zarówno z OpenAI, jak i self-hosted punktami końcowymi vLLM zamiennie.