vLLM-Omni-Modal-Unterstützung: Ausführen multimodaler Modelle mit vLLM

vLLM omni ist kein separates Produkt. Es ist eine Kurzform dafür, vLLM – die Hochdurchsatz-LLM-Inferenz-Engine – zum Bereitstellen von omni-modalen Modellen einzusetzen, also Modellen, die innerhalb einer einzigen Konversation Text, Bilder, Audio und Video akzeptieren. In der Praxis bedeutet dies fast immer Alibabas Qwen2.5-Omni -Reihe, obwohl vLLMs multimodaler Stack auch rein visuelle und rein auditive Modelle über dieselbe API verarbeitet.

Dieser Leitfaden erläutert, was „omni“ im Kontext von vLLM bedeutet, welche Modelle unterstützt werden, wie sie installiert und bereitgestellt werden, wie das Anfrageformat aussieht und wo die aktuellen Einschränkungen liegen.

Was „Omni“ im vLLM-Kontext bedeutet

vLLMs multimodales Subsystem gruppiert Modelle nach den Modalitäten, die sie auf der Eingabeseite akzeptieren. Die relevanten Kategorien sind:

Omni-modale Modelle teilen sich eine gemeinsame Sprach-Backbone-Architektur mit separaten Encodern für jede Modality (z. B. ein ViT für Bilder und Videoframes, ein Audioencoder basierend auf Whisper-artigen Architekturen usw.). vLLMs Aufgabe besteht darin, diese Encoder zu planen, ihre Ausgaben zwischenzuspeichern und sie mit dem Text-Token-Strom im KV-Cache so zu verzahnen, dass der Durchsatz hoch bleibt.

Die Ausgabe-Seite der Generierung in vLLM liefert ausschließlich Text. Falls Sie die native Audio-Ausgabe-Funktion benötigen, die Qwen2.5-Omni nativ unterstützt (Sprachsynthese), müssen Sie derzeit die Referenzimplementierung der Modellautoren verwenden – vLLM liefert Ihnen lediglich die Texttranskription, nicht die Audio-Wellenform. Dies ist das wichtigste Verständnis, das Sie vor der Entscheidung für vLLM bei einer Omni-Workload haben sollten.

Unterstützte omni-modale Modelle

Die maßgebliche Liste finden Sie in der vLLM-Dokumentation unter Unterstützte Modelle → Multimodale Sprachmodelle. Als stabiler Referenzpunkt wird folgenden Familien seit geraumer Zeit offizielle Unterstützung geboten:

• Qwen2.5-Omni (3B, 7B) – das kanonische „omni“-Modell mit Text + Bild + Audio + Video als Eingabe und Text als Ausgabe.
• MiniCPM-o 2.6 – ein 8B-klassiges Omni-Modell von OpenBMB.
• Qwen2-VL / Qwen2.5-VL – ausschließlich Vision und Video, wird aber oft in „omni“-Workflows mitverwendet.
• Qwen2-Audio – ausschließlich audiofähiger Begleiter.

Da die Modellunterstützung pro Version hinzugefügt wird, prüfen Sie stets die aktuelle Dokumentation sowie die Modellkarte auf die erforderliche Mindestversion von vLLM. Der Versuch, ein neues Omni-Modell auf einer alten vLLM-Version auszuführen, ist der häufigste Fehlergrund. Durchsuchen Sie einen aktuell gehaltenen Modelldatenbank falls Sie noch in der Auswahlphase sind.

Hardware-Anforderungen

Omni-modale Modelle sind schwerer als ihre rein textbasierten Pendants mit derselben Parameteranzahl, da sie zusätzliche Encoder enthalten und weil Vision-/Audio-Eingaben nach der Tokenisierung viele Tokens verbrauchen. Ein einzelnes Bild in Originalauflösung kann sich auf 1.000–4.000 Tokens ausdehnen; eine Minute Audio auf mehrere hundert.

Dies sind praktische Bereiche, keine Mindestangaben aus den technischen Spezifikationen. Für einen exakten Wert bei Ihrer Kontextlänge und Batchgröße geben Sie das Modell in den VRAM-Rechner oder konsultieren Sie die Referenz zu VRAM-AnforderungenFalls Sie die Hardware noch nicht ausgewählt haben, behandelt der beste GPUs für lokale LLMs Leitfaden die Kompromisse auf den Stufen mit 24 GB, 48 GB und Multi-GPU-Konfigurationen.

Installation

vLLM ist Linux-zentriert. Windows wird offiziell nicht unterstützt; verwenden Sie stattdessen WSL2 oder einen Linux-Container. macOS bietet nur eine CPU-only-Version, die zwar kleinere Modelle technisch laden kann, aber für den produktiven Einsatz multimodaler Inferenz ungeeignet ist.

Linux (empfohlen)

Voraussetzungen: Eine CUDA-fähige GPU (Compute Capability 7.0+), CUDA-12.x-Treiber und Python 3.9–3.12.

# Erstellen einer isolierten Umgebung
python -m venv vllm-env
source vllm-env/bin/activate

# Installieren von vLLM (dabei wird automatisch eine kompatible PyTorch-Version heruntergeladen)
pip install vllm

# Zusätzliche Abhängigkeiten, die häufig für Omni-Modelle benötigt werden
pip install librosa soundfile decord

vllm --version

Der librosa, soundfile, und decord Diese Pakete übernehmen die Audio-Dekodierung und die Extraktion von Videobildern. Einige Omni-Modelle laden sie automatisch über trust_remote_code; die vorherige Installation vermeidet Fehler beim ersten Aufruf.

Windows (über WSL2)

Installieren Sie WSL2 mit einer Ubuntu-22.04- oder Ubuntu-24.04-Distribution, installieren Sie den NVIDIA-Treiber unter Windows (die WSL-Seite nutzt den Windows-Treiber direkt) und führen Sie dann die Linux-Schritte innerhalb von WSL aus. Installieren Sie keinen separaten Linux-NVIDIA-Treiber innerhalb von WSL – dies würde CUDA beschädigen.

macOS

macOS bietet keine CUDA-Unterstützung, und vLLM richtet sich nicht an Metal. Für lokale multimodale Inferenz auf Apple Silicon verwenden Sie stattdessen LM Studio oder MLX-basierte Laufzeitumgebungen. vLLM ist hierfür nicht geeignet.

Bereitstellung eines Omni-Modells

Starten eines OpenAI-kompatiblen Servers:

vllm serve Qwen/Qwen2.5-Omni-7B 
  --trust-remote-code 
  --dtype bfloat16 
  --max-model-len 32768 
  --limit-mm-per-prompt image=4,audio=2,video=1 
  --port 8000

Wichtige Parameter:

• --trust-remote-code ist erforderlich, da Omni-Modelle benutzerdefinierten Vorverarbeitungscode in ihren Hugging Face-Repositories enthalten.
• --limit-mm-per-prompt begrenzt die Anzahl jedes Modalitätstyps pro Anfrage. Höhere Werte erhöhen das Budget für multimodale Eingaben, belasten aber auch den VRAM stärker.
• --max-model-len sollte explizit festgelegt werden. Visuelle und auditive Token zählen hierzu dazu.
• --tensor-parallel-size N wird auf N GPUs verteilt, falls eine einzelne Karte zu klein ist.

Senden multimodaler Anfragen

vLLM stellt die OpenAI Chat Completions API bereit. Multimodale Teile folgen der OpenAI-content-Array-Konvention:

curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{
    "model": "Qwen/Qwen2.5-Omni-7B",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Beschreiben Sie, was Sie sehen und hören."},
        {"type": "image_url", "image_url": {"url": "https://example.com/scene.jpg"}},
        {"type": "audio_url", "audio_url": {"url": "https://example.com/clip.wav"}}
      ]
    }]
  }'

Der Python-Client ist identisch mit dem von OpenAI:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

resp = client.chat.completions.create(
    model="Qwen/Qwen2.5-Omni-7B",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Transkribieren und zusammenfassen."},
        {"type": "audio_url", "audio_url": {"url": "file:///data/meeting.wav"}},
    ]}],
)
print(resp.choices[0].message.content)

Data-URLs (data:image/png;base64,...) und lokale file:// Pfade funktionieren beide; die genaue Liste unterstützter Schemata wurde mit jeder Version erweitert, daher sollten Sie bei Problemen mit einem bestimmten Schema die Dokumentation der jeweiligen Version konsultieren.

Leistungs-Hinweise

• Prefill dominiert. Die Kodierung eines einminütigen Audio-Clips oder eines 720p-Bildes ist rechenintensiv sowohl für CPU als auch GPU und erfolgt vor dem ersten generierten Token. Das Batching verbessert den Durchsatz, jedoch nicht die Latenz pro Anfrage.
• KV-Cache-Belastung. Ein einzelnes Bild kann Tausende von Tokens im Cache hinzufügen. Reduzieren Sie --max-model-len oder senken Sie --limit-mm-per-prompt , falls es bei hoher Last zu einem OOM-Fehler kommt.
• Quantisierung. AWQ- und GPTQ-4-Bit-Varianten von Qwen2.5-Omni-7B passen auf eine 16-GB-Karte und verlieren bei Aufgaben zur visuellen und akustischen Verständnis relativ wenig Qualität. Die Verfügbarkeit hängt von Community-Uploads auf Hugging Face ab.
• Chunked Prefill (in neueren Versionen standardmäßig aktiviert) glättet die Latenz bei gemischten Anfragen aus multimodalen und rein textbasierten Inhalten.

Wann vLLM Omni statt alternativer Lösungen verwenden

Falls Sie noch unsicher sind, ob Sie das Modell überhaupt selbst hosten möchten, berechnen Sie die Kosten mithilfe des Selbsthosting- versus-API-Kosten-Grenzwert-Rechner. Omni-modale Workloads verschieben die Entscheidung zugunsten der Selbsthosting-Lösung, da die Anzahl der Tokens pro Anfrage deutlich höher ist als bei rein textbasierten Modellen – dadurch wird die nutzungsbasierte API-Preisgestaltung pro Sitzung teurer.

Häufig gestellte Fragen

Unterstützt vLLM die Sprachausgabe von Qwen2.5-Omni?

Nein. vLLM verarbeitet ausschließlich die Textgenerierung durch das sprachliche Grundmodell. Der optionale Audio-Decodier-Kopf, der im Referenzmodell Qwen2.5-Omni gesprochene Antworten erzeugt, ist in vLLM nicht integriert. Sie erhalten lediglich die Textantwort des Modells; um Sprache zu synthetisieren, benötigen Sie entweder einen separaten TTS-Schritt oder den ursprünglichen Inferenzcode.

Kann ich vLLM-Omni-Modelle auf einer 24-GB-Karte wie einer RTX 4090 ausführen?

Ja, für die Varianten mit 3 Milliarden und 7 Milliarden Parametern – insbesondere im bf16-Format bei moderater Kontextlänge oder komfortabel mit AWQ-/GPTQ-Quantisierung bei längeren Kontexten. Sie müssen jedoch --max-model-len und --limit-mm-per-prompt anpassen, um unter der Speichergrenze zu bleiben. Überprüfen Sie dies anhand des VRAM-Rechner bevor Sie sich verpflichten.

Warum schlägt meine Anfrage mit einem „trust_remote_code“-Fehler fehl?

Omni-modale Modelle enthalten benutzerdefinierte Python-Preprozessoren in ihren Hugging-Face-Repositories. vLLM führt diesen Code nicht aus, es sei denn, Sie übergeben beim Serverstart --trust-remote-code . Aktivieren Sie diese Option nur für Repositorys, denen Sie vertrauen.

Wie sende ich ein Video an einen vLLM-Omni-Endpunkt?

Verwenden Sie einen Inhaltsabschnitt mit "type": "video_url" , der auf eine zugängliche URL oder eine lokale Datei verweist. vLLM extrahiert Frames mithilfe von decord; die genaue Anzahl der Frames sowie die Sampling-Strategie sind modellspezifisch und auf der Modellkarte dokumentiert. Videos verbrauchen Tokens sehr schnell – halten Sie daher die Clips kurz und setzen Sie --limit-mm-per-prompt video=1 , sofern Sie nicht über ausreichend VRAM verfügen.

Gibt es ein Docker-Image für vLLM Omni?

Das offizielle vllm/vllm-openai -Image auf Docker Hub unterstützt multimodale Modelle ab Werk – und zwar für diejenige vLLM-Version, mit der das Image getaggt ist. Verwenden Sie stattdessen eines der spezifischen Tags, nicht neueste , damit die für Ihr Omni-Modell erforderliche vLLM-Version nicht unerwartet aktualisiert wird.

Kann Ollama diese Omni-Modelle stattdessen ausführen?

Ollama unterstützt einige Vision-Sprache-Modelle, doch seine Abdeckung omni-modaler Funktionen hinkt der von vLLM hinterher; Audio- und Video-Eingaben sind bei den meisten Modellen eingeschränkt oder gar nicht verfügbar. Für Desktop-Workflows prüfen Sie am besten die beste lokale Modelle für Ollama und das Ollama-Modellliste , um zu sehen, was derzeit verfügbar ist; für volle Omni-Funktionen auf einem Server empfehlen wir nach wie vor vLLM.