vllm serve: Die wichtigsten Flags mit sinnvollen Startwerten

vLLM ist eine der ersten Adressen, wenn es um das Bereitstellen großer Sprachmodelle geht, vor allem wegen des Durchsatzes und der Art, wie PagedAttention den Speicher verwaltet. Gesteuert wird es meist über die Kommandozeile, entweder mit vllm serve oder mit der älteren Form python -m vllm.entrypoints.openai.api_server. Hier ist ein konkreter Befehl und danach ein Rundgang durch die Flags, die Sie am häufigsten anfassen werden, jeweils mit einem sinnvollen Startwert.

Ein Startbefehl

Dieser Befehl stellt ein mittelgroßes Modell auf einer Maschine mit mehreren GPUs bereit. Er ist für PowerShell geschrieben, deshalb sind die Zeilenfortsetzungen Backticks:

vllm serve meta-llama/Llama-3.1-8B-Instruct `
  --host 0.0.0.0 `
  --port 8000 `
  --tensor-parallel-size 2 `
  --gpu-memory-utilization 0.90 `
  --max-model-len 8192 `
  --max-num-seqs 256 `
  --dtype bfloat16 `
  --served-model-name llama3-8b `
  --api-key $env:VLLM_API_KEY

Jedes Flag darin wird unten erklärt, zusammen mit ein paar weiteren, die eine Erwähnung verdienen.

Modell und Genauigkeit wählen

model ist das Positionsargument: eine Hugging-Face-Modell-ID oder ein lokaler Pfad zu den Gewichten. Das ist das Einzige, was Sie zwingend angeben müssen. Die übrigen Optionen haben Standardwerte, die aber selten das sind, was man in Produktion möchte.

dtype legt die numerische Genauigkeit für Gewichte und Aktivierungen fest. Die üblichen Optionen sind auto, float16, bfloat16 und float32. Auf GPUs der Ampere-Klasse oder neuer nehmen Sie bfloat16. Es ist numerisch stabiler als float16, kostet praktisch keinen Durchsatz und umgeht die Überlaufprobleme, auf die manche Architekturen in float16 stoßen.

trust-remote-code erlaubt vLLM, eigenen Modellcode aus dem Hugging-Face-Repository des Modells auszuführen. Einige Architekturen brauchen das, um überhaupt zu laden. Lassen Sie es aus, sofern die Model Card nichts anderes sagt, denn mit dem Einschalten führen Sie beliebigen Code aus diesem Repository aus.

quantization wählt ein Kompressionsverfahren wie awq, gptq oder fp8 und senkt den Speicherbedarf auf Kosten etwas Qualität. Setzen Sie es nur, wenn Sie bereits quantisierte Gewichte laden oder der GPU-Speicher keine andere Wahl lässt. Mit genug Reserve ist bfloat16 oder volle Genauigkeit die bessere Wahl.

GPU-Speicher und Kontext einteilen

gpu-memory-utilization ist der Anteil des GPU-Speichers, den vLLM für Gewichte, Aktivierungen und den KV-Cache beanspruchen darf. Er beeinflusst Stabilität und Durchsatz stärker als fast jede andere Einstellung. Starten Sie mit 0.90. Gehen Sie deutlich höher, können andere Prozesse auf der Karte Out-of-Memory-Fehler auslösen. Gehen Sie tiefer, verschenken Sie Platz im KV-Cache, und das begrenzt, wie viele Anfragen Sie gleichzeitig bedienen können.

max-model-len begrenzt Prompt plus generierte Tokens pro Anfrage. Die Obergrenze ist die Kontextlänge, mit der das Modell trainiert wurde, Sie können den Wert aber niedriger setzen, um Cache-Speicher zu sparen. Richten Sie ihn danach aus, was Ihre App wirklich braucht. Unterstützt ein Modell 128K Tokens und Sie haben nur kurze Chat-Wechsel, lohnt es sich nicht, all das zu reservieren. Ein kleinerer Wert schafft Platz für mehr gleichzeitige Sequenzen.

max-num-seqs begrenzt, wie viele Anfragen zusammen gebatcht werden, und steuert damit die Parallelität. 256 passt für viele Workloads. Erhöhen Sie den Wert bei freiem GPU-Speicher und viel Traffic, und senken Sie ihn, wenn lange Kontexte den Speicher unter Druck setzen.

block-size ist die Anzahl der Tokens pro Block im KV-Cache von PagedAttention. Größere Blöcke bedeuten weniger Verwaltungsaufwand, aber mehr verschwendeten Platz bei kurzen Sequenzen. Der Standardwert 16 passt für die meisten Setups, und Sie werden ihn selten ändern müssen.

swap-space reserviert CPU-RAM, in Gigabyte pro GPU, in dem KV-Cache-Blöcke bei Speicherdruck abgelegt werden können, statt Anfragen abzuweisen. Beginnen Sie mit 4. Wenn Traffic-Spitzen zu Fehlern statt zu geordnetem Anstehen führen, erhöhen Sie den Wert.

Das Modell auf mehrere GPUs verteilen

tensor-parallel-size gibt an, auf wie viele GPUs jede Schicht aufgeteilt wird. Das ist die Lösung, wenn ein Modell nicht auf eine Karte passt, und auf Hosts mit mehreren GPUs auch eine Möglichkeit, etwas Latenz gegen Durchsatz zu tauschen. Setzen Sie den Wert auf die Zahl der GPUs im Knoten und bevorzugen Sie Zweierpotenzen (1, 2, 4, 8), da sich die Zahl der Attention-Heads meist glatt durch sie teilen lässt.

pipeline-parallel-size legt die Zahl der Pipeline-Stufen fest, meist kombiniert mit Tensor-Parallelität, wenn ein Modell über mehrere Knoten verteilt werden muss. Lassen Sie den Wert auf 1, sofern das Modell nicht zu groß für reine Tensor-Parallelität innerhalb eines Knotens ist.

Den Server erreichbar machen

host und port bestimmen, wo der API-Server lauscht. Nehmen Sie 0.0.0.0, wenn andere Maschinen ihn erreichen sollen, oder 127.0.0.1 für rein lokalen Zugriff. 8000 ist der übliche Port.

served-model-name ist der Name, den Clients in API-Anfragen angeben, und er kann von der Hugging-Face-ID abweichen. Das ist praktisch, um einem Deployment ein sauberes, versioniertes Label zu geben. Wählen Sie etwas Kurzes und Stabiles, damit nachgelagerte Anwendungen nicht an einen bestimmten Pfad zu den Gewichten gebunden sind.

api-key zwingt Clients, ein Bearer-Token mitzuschicken. Ohne ihn kann jeder, der den Port erreicht, Anfragen senden. Setzen Sie ihn für alles, was über lokale Experimente hinausgeht, und lesen Sie ihn aus einer Umgebungsvariable, statt ihn in Skripte zu schreiben oder in der Shell-Historie liegen zu lassen.

enforce-eager schaltet das Erfassen von CUDA-Graphen ab und lässt PyTorch im Eager-Modus laufen. Sie verzichten auf etwas Durchsatz und bekommen dafür einen schnelleren Start und einfacheres Debugging. In Produktion lassen Sie es aus, denn CUDA-Graphen bringen meist einen deutlichen Geschwindigkeitsgewinn. Schalten Sie es vorübergehend ein, wenn Sie einem Absturz nachgehen, weil der Eager-Modus klarere Stacktraces liefert.

So gehen Sie beim Tuning vor

Die meiste Arbeit ist ein Dreiklang, abgewogen gegen den verfügbaren GPU-Speicher: Kontextlänge über max-model-len, Parallelität über max-num-seqs und Genauigkeit über dtype und quantization. Beginnen Sie vorsichtig mit gpu-memory-utilization, messen Sie realen Durchsatz und reale Latenz unter realistischer Last und justieren Sie von dort aus nach, statt Zahlen im Voraus zu raten.