> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokios.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel. > Use 'connector' for the local tokios-connector process. > Use 'deployment' for the public model name in the API model field. > Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend. > API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-. # vLLM für Durchsatz und Latenz optimieren > Optimieren Sie vLLM für maximalen Durchsatz oder minimale Latenz – KV-Cache-Tuning, Prefix-Caching, Chunked Prefill, LoRA-Serving, Quantisierungsoptionen und Änderungen an der V1-Architektur. vLLM ist die funktionsreichste Open-Source-Laufzeit für das Serving von großen Sprachmodellen auf GPUs. Sie wird mit einer breiten Palette von Konfigurationsoptionen ausgeliefert, die Durchsatz, Latenz und Speichernutzung direkt beeinflussen. Dieser Leitfaden behandelt die wichtigsten Stellschrauben und wie Sie sie für Ihre Workload setzen. > [!NOTE] > > Zuletzt überprüft: 2026-10-14 — vLLM v0.31.0. > [!NOTE] > > **V1 ist der Standard.** Die V1-Architektur ist jetzt der Standard in vLLM v0.31.0. Sie bringt einen neuen Scheduler, standardmäßig aktiviertes Chunked Prefill und verbessertes GPU-Speichermanagement. Wenn Sie Verhaltensunterschiede zu älteren Leitfäden sehen, ist V1 wahrscheinlich die Ursache. ## KV-Cache-Abstimmung Der KV-Cache speichert Key-Value-Tensoren für jedes Token in jeder aktiven Sequenz. Er ist normalerweise der größte Verbraucher von GPU-Speicher nach den Modellgewichten selbst, daher hat seine Abstimmung den größten Einfluss darauf, wie viele gleichzeitige Anfragen Sie bedienen können. ### Größenformel vLLM berechnet die KV-Cache-Größe automatisch, aber das Verständnis der Formel hilft Ihnen, Grenzen zu setzen: ``` KV memory per token = 2 × num_layers × num_kv_heads × head_dim × dtype_bytes ``` Der Faktor 2 berücksichtigt sowohl Keys als auch Values. Für ein 7B-Modell mit 32 Schichten, 32 KV-Heads, 128 Head-Dimension und `float16`: ``` 2 × 32 × 32 × 128 × 2 = 524,288 bytes ≈ 0.5 MB per token ``` Mit 24 GB KV-Cache-Speicher fasst das ungefähr 48,000 Token über alle Sequenzen hinweg. ### fp8-KV-Cache verwenden `--kv-cache-dtype fp8` reduziert den KV-Cache-Speicher um ungefähr 50% im Vergleich zum Standard `float16`. Das verdoppelt direkt die Anzahl der Token, die Sie cachen können, was mehr gleichzeitige Sequenzen oder längere Kontexte bedeutet. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --kv-cache-dtype fp8 ``` > [!WARNING] > > Der FP8-KV-Cache führt einen kleinen Genauigkeitsverlust ein. Für die meisten Chat- und Code-Generierungs-Workloads ist der Unterschied vernachlässigbar, aber wenn Sie Evaluierungen für Ihre spezifische Aufgabe durchführen, überprüfen Sie, ob die Ausgabequalität Ihren Schwellenwert erfüllt, bevor Sie es in der Produktion aktivieren. ### `--max-num-seqs` vs `--max-model-len` Diese 2 Flags konkurrieren um denselben KV-Cache-Pool: * `--max-model-len` begrenzt die Kontextlänge einer einzelnen Sequenz. Das Heruntersetzen setzt KV-Cache für mehr gleichzeitige Sequenzen frei. * `--max-num-seqs` begrenzt die Anzahl der Sequenzen, die in einem Batch verarbeitet werden. Das Heraufsetzen erhöht den Durchsatz auf Kosten des pro-Sequenz-Speichers. Wenn Ihre Workload kurze Prompts sendet (unter 2K Token), setzen Sie `--max-model-len` herunter und `--max-num-seqs` herauf, um die Parallelität zu maximieren. Wenn Sie Long-Context-Anfragen bedienen, machen Sie das Gegenteil. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Short prompts, high concurrency vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-model-len 4096 \ --max-num-seqs 256 # Long context, fewer concurrent sequences vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-model-len 32768 \ --max-num-seqs 32 ``` ## Prefix Caching Viele reale Workloads senden Anfragen, die sich ein gemeinsames Präfix teilen: ein System-Prompt, ein RAG-Retrievalblock oder frühere Runden in einem Multi-Turn-Gespräch. Ohne Prefix Caching berechnet vLLM den KV-Cache für dieses geteilte Präfix bei jeder Anfrage neu. `--enable-prefix-caching` speichert berechnete KV-Blöcke in einer hash-indizierten Tabelle. Wenn eine neue Anfrage mit einem Präfix eintrifft, das einem gecachten Block entspricht, verwendet vLLM die gecachten KV-Tensoren wieder, statt sie neu zu berechnen. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --enable-prefix-caching ``` > [!TIP] > > Prefix Caching ist besonders effektiv, wenn: > > * Jede Anfrage denselben System-Prompt enthält (häufig in Chat-Apps und Coding-Agenten). > * Sie RAG mit einem festen Retrievalblock verwenden, der jeder Anfrage vorangestellt wird. > * Multi-Turn-Gespräche frühere Runden als Kontext wiederverwenden. > > Es bietet keinen Vorteil, wenn jede Anfrage ein eindeutiges Präfix hat. Prefix Caching ist in V1 standardmäßig aktiviert. Sie benötigen das Flag nur explizit, wenn Sie im `V0`-Scheduler-Modus ausführen. ## Chunked Prefill Prefill — die Verarbeitung des Eingabe-Prompts — ist rechenintensiv. Ein langer Prompt (8K+ Token) kann die GPU für Hunderte von Millisekunden monopolisieren, Decode-Schritte für andere Sequenzen blockieren und Latenzspitzen verursachen. Chunked Prefill teilt das Prefill in kleinere Chunks auf, die mit Decode-Schritten verschachtelt werden. Die GPU verarbeitet einen Chunk des Prompts, führt dann einen Decode-Schritt für andere aktive Sequenzen aus und fährt dann mit dem nächsten Prefill-Chunk fort. Das hält die Decode-Latenz vorhersehbar. In V1 ist Chunked Prefill **standardmäßig aktiviert**. Sie können die Chunk-Größe steuern: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-num-batched-tokens 8192 ``` `--max-num-batched-tokens` setzt die maximale Anzahl der Token, die in einem einzigen Scheduler-Schritt verarbeitet werden. Niedrigere Werte reduzieren den Prefill-Einfluss auf die Decode-Latenz, erhöhen aber die Gesamt-Time-to-First-Token (TTFT). Höhere Werte verbessern den Prefill-Durchsatz auf Kosten gelegentlicher Decode-Jitter. > [!NOTE] > > Wenn Sie Chunked Prefill in einer älteren vLLM-Version deaktiviert haben und auf V1 upgraden, entfernen Sie das `--enable-chunked-prefill`-Flag — es ist in V1 immer eingeschaltet und das Flag wird ignoriert. ## LoRA-Serving vLLM kann mehrere LoRA-Adapter aus einem einzigen Prozess bereitstellen, ohne sie in das Basismodell zusammenzuführen. So können Sie ein Basismodell ausführen und Anfragen an verschiedene feinabgestimmte Varianten weiterleiten — zum Beispiel einen Coding-Adapter, einen Summarization-Adapter und einen General-Chat-Adapter — alle teilen sich dieselben Basisgewichte im GPU-Speicher. ### LoRA-Serving aktivieren ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B \ --enable-lora \ --lora-modules \ coder=./lora-adapter-coder \ summarizer=./lora-adapter-summarizer ``` Jeder Eintrag in `--lora-modules` bildet einen anfrageseitigen Namen auf einen lokalen Pfad ab. Clients wählen den Adapter im `model`-Feld: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "coder", "messages": [ { "role": "user", "content": "Write a Python function that sorts a list." } ] }' ``` ### Dynamisches Laden vLLM unterstützt dynamisches LoRA-Laden — Sie können Adapter zur Laufzeit über die API hinzufügen oder entfernen, ohne den Server neu zu starten. Das ist nützlich, wenn Sie viele Adapter haben, aber nur wenige gleichzeitig aktiv sind. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Load a new adapter at runtime curl http://localhost:8000/v1/load_lora_adapter \ -H "Content-Type: application/json" \ -d '{ "lora_name": "translator", "lora_path": "./lora-adapter-translator" }' ``` > [!TIP] > > Verwenden Sie `--max-lora-rank`, um den Rang der LoRA-Adapter zu begrenzen, die der Server akzeptiert. Niedrigrangigere Adapter verwenden weniger Speicher. Wenn alle Ihre Adapter denselben Rang teilen, setzen Sie dies auf diesen Rang, um eine Überzuweisung von Speicher für ungenutzte Kapazität zu vermeiden. ## Quantisierungsoptionen Quantisierung reduziert die Modellgewichts-Präzision unter 16-Bit und tauscht eine kleine Menge Genauigkeit gegen erhebliche Speicher- und Geschwindigkeitsgewinne. vLLM unterstützt mehrere Quantisierungsformate: | Format | Precision | Hardware | Best for | | - | - | - | - | | **AWQ** | 4-bit integer | Any GPU | General-purpose 4-bit quantization. Good accuracy retention. Pre-quantized models widely available on Hugging Face. | | **GPTQ** | 4-bit integer | Any GPU | Older format, similar to AWQ. Prefer AWQ for new quantizations — GPTQ remains for compatibility with existing models. | | **FP8** | 8-bit float | Ampere+ (A100, H100, L40, RTX 4090) | Near-FP16 accuracy with half the memory. Good default when your GPU supports it. | | **NVFP4** | 4-bit float | Blackwell (B200, GB200, RTX 5090) | Newest format. Maximum memory savings on Blackwell hardware. | ### Quantisierte Modelle verwenden Für vorquantisierte Modelle erkennt vLLM das Format automatisch aus der `config.json` des Modells: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # AWQ model — auto-detected vllm serve TheBloke/Llama-2-7B-Chat-AWQ # FP8 model — auto-detected on Ampere+ GPUs vllm serve neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8 ``` > [!WARNING] > > **FP8-Shorthand hat sich in v0.31 geändert.** Der FP8-Quantisierungs-Identifikator ist jetzt `fp8_per_tensor`. Wenn Sie `--quantization fp8` explizit in einem Skript oder einer CI-Pipeline übergeben, aktualisieren Sie ihn auf den neuen Identifikator. Modelle mit FP8 in ihrer `config.json` sind nicht betroffen — die automatische Erkennung funktioniert weiterhin. ### Online-Quantisierung Sie können ein Modell auch während des Ladens im laufenden Betrieb quantisieren, obwohl vorquantisierte Modelle für die Produktion bevorzugt werden: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-70B \ --quantization awq ``` ## Durchsatz vs Latenz Ihre Optimierungsstrategie hängt davon ab, ob Sie **Durchsatz** (Gesamt-Token pro Sekunde über alle Anfragen) oder **Latenz** (Time-to-First-Token und Inter-Token-Latenz für einzelne Anfragen) priorisieren. ### Durchsatz maximieren Erhöhen Sie die Batch-Größen, um mehr Arbeit pro GPU-Schritt zu packen: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-num-seqs 256 \ --max-num-batched-tokens 16384 \ --enable-prefix-caching \ --kv-cache-dtype fp8 ``` * `--max-num-seqs 256` erlaubt bis zu 256 gleichzeitige Sequenzen in einem Batch. * `--max-num-batched-tokens 16384` erlaubt mehr Token pro Scheduler-Schritt. * `--kv-cache-dtype fp8` setzt Speicher für mehr Sequenzen frei. ### Latenz minimieren Reduzieren Sie die Batch-Größen und deaktivieren Sie Optimierungen, die Latenz gegen Durchsatz tauschen: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --max-num-seqs 16 \ --max-num-batched-tokens 4096 \ --enforce-eager ``` * `--max-num-seqs 16` hält die Batches klein, sodass jede Anfrage schneller GPU-Zeit bekommt. * `--enforce-eager` deaktiviert CUDA-Graphen. CUDA-Graphen erfassen und spielen einen festen Berechnungsgraphen ab, was den Durchsatz verbessert, aber Latenz beim ersten Durchlauf jeder neuen Batch-Form hinzufügt. Verwenden Sie `--enforce-eager` zum Debuggen oder wenn jede Millisekunde TTFT zählt. > [!TIP] > > Für interaktive Anwendungen, bei denen Benutzer auf eine Antwort warten, zielen Sie auf TTFT unter 500ms. Starten Sie mit `--max-num-seqs 32` und `--max-num-batched-tokens 4096` und passen Sie dann basierend auf Ihrer gemessenen TTFT unter Last an. ## V1-Architekturänderungen V1 ist der Standard-Scheduler in vLLM v0.31.0. Wenn Sie vLLM zuvor verwendet haben, hier ist, was sich geändert hat: **Neuer Scheduler.** Der V1-Scheduler ersetzt den V0-Block-Manager durch einen einheitlichen Speicher-Manager, der KV-Cache, Prefix Caching und Chunked Prefill in einem einzigen Durchlauf verarbeitet. Das reduziert den Scheduling-Overhead und eliminiert mehrere Randfälle, bei denen V0 den GPU-Speicher fragmentieren konnte. **Chunked Prefill ist Standard.** Prefill und Decode werden automatisch verschachtelt. Sie benötigen `--enable-chunked-prefill` nicht mehr — es ist immer eingeschaltet. **Besseres Speichermanagement.** V1 verfolgt den GPU-Speicher mit einer feineren Granularität, was verschwendeten Platz durch Padding und Ausrichtung reduziert. Erwarten Sie 5-15% mehr nutzbaren KV-Cache auf derselben Hardware im Vergleich zu V0. **CUDA-Graph-Verbesserungen.** V1 erfasst CUDA-Graphen aggressiver über eine breitere Palette von Batch-Formen, was den Durchsatz ohne manuelle Abstimmung verbessert. > [!NOTE] > > Wenn Sie eine Regression mit V1 feststellen, können Sie auf V0 zurückfallen, indem Sie die Umgebungsvariable `VLLM_USE_V1=0` vor dem Starten des Servers setzen. Melden Sie das Problem dem vLLM-Team — V0 wird keine neuen Funktionen erhalten. ### Neu in v0.31: Persistenter Gewichts-Cache und Snapshots vLLM v0.31 führt 2 neue CLI-Befehle ein: * **`vllm preload`** startet einen persistenten Gewichts-Cache-Daemon, der Modellgewichte zwischen Server-Neustarts im GPU-Speicher hält. Statt bei jedem Neustart ein mehrere Gigabyte großes Modell von der Festplatte neu zu laden, verbindet sich der Server mit dem Daemon und verwendet die gecachten Gewichte wieder. Das reduziert die Kaltstartzeit von Minuten auf Sekunden. * **`vllm snapshot create`** erfasst den aktuellen Serverzustand (geladenes Modell, Adapter, Konfiguration) und **`vllm snapshot restore`** stellt ihn sofort wieder her. Nützlich zum Zurücksetzen nach einer fehlerhaften Konfigurationsänderung oder zum Replizieren eines bekannten guten Setups über Maschinen hinweg. ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} # Start the weight-cache daemon vllm preload meta-llama/Llama-3.1-8B-Instruct # Create a snapshot of the current state vllm snapshot create my-production-config # Restore it on another machine vllm snapshot restore my-production-config ``` ### Breaking Changes in v0.31 * **`--trust-request-mm-kwargs`** ist jetzt erforderlich, wenn Clients multimodale Eingaben (Bilder, Audio) über den Request-Body senden. Ohne dieses Flag weist vLLM multimodale kwargs aus Sicherheit ab. Fügen Sie es hinzu, wenn Ihre Anwendung Bilder oder andere Medien in API-Anfragen sendet. * **`--grpc`** aktiviert gRPC-Serving neben dem HTTP-Server. Wenn Sie gRPC-Clients verwenden, starten Sie vLLM mit diesem Flag, um den gRPC-Endpunkt freizugeben. ## Beispielkonfigurationen ### Hochdurchsatz-Batchverarbeitung Für Offline-Batch-Workloads, bei denen Gesamt-Token pro Sekunde wichtiger ist als die Latenz einzelner Anfragen: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-70B-Instruct \ --tensor-parallel-size 4 \ --kv-cache-dtype fp8 \ --enable-prefix-caching \ --max-num-seqs 512 \ --max-num-batched-tokens 32768 \ --max-model-len 8192 ``` Diese Konfiguration maximiert die Parallelität auf einem 4-GPU-Setup. Der 4-Bit-äquivalente KV-Cache und die hohen Batch-Grenzen treiben den Durchsatz auf Kosten einer längeren Latenz pro Anfrage. ### Latenzarmes interaktives Serving Für Chat-Anwendungen, bei denen Benutzer auf Antworten warten und TTFT unter 500ms liegen sollte: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B-Instruct \ --kv-cache-dtype fp8 \ --enable-prefix-caching \ --max-num-seqs 32 \ --max-num-batched-tokens 4096 \ --max-model-len 8192 ``` Kleine Batch-Größen und moderate Token-Limits halten die GPU reaktionsschnell. Prefix Caching beschleunigt wiederholte System-Prompts ohne Latenzzusätze. ### Multi-Adapter-LoRA-Serving Für das Serving mehrerer feinabgestimmter Varianten von einem Basismodell: ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}} vllm serve meta-llama/Llama-3.1-8B \ --enable-lora \ --lora-modules \ coder=./adapters/coder \ reviewer=./adapters/reviewer \ summarizer=./adapters/summarizer \ --max-lora-rank 64 \ --kv-cache-dtype fp8 \ --enable-prefix-caching \ --max-num-seqs 128 ``` Clients wählen den Adapter nach Namen im `model`-Feld. Alle 3 Adapter teilen sich dieselben Basismodell-Gewichte, daher ist der GPU-Speicherverbrauch nahe am Serving des Basismodells allein — jeder LoRA-Adapter fügt nur wenige Megabyte hinzu. > [!NOTE] > > Nach dem Ändern der vLLM-Konfiguration registrieren Sie Ihre Tokios-Deployment erneut, damit der Connector den neuen Upstream-Endpunkt übernimmt. Siehe [Register Model](/de/setup/register-model.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.