Supporto omni-modale di vLLM: esecuzione di modelli multimodali con vLLM

vLLM omni non è un prodotto separato. È una forma abbreviata per indicare l'utilizzo di vLLM — il motore di inferenza LLM ad alto throughput — per servire modelli omni-modali modelli omni-modali, ovvero modelli che accettano testo, immagini, audio e video all'interno di un'unica conversazione. Nella pratica questo significa quasi sempre la famiglia di modelli di Alibaba Qwen2.5-Omni , anche se lo stack multimodale di vLLM gestisce anche modelli basati esclusivamente su visione o su audio attraverso la stessa API.

Questa guida spiega cosa significhi «omni» nel contesto di vLLM, quali modelli sono supportati, come installarli ed eseguirli, quale sia il formato delle richieste e quali siano le attuali limitazioni.

Cosa significa «Omni» nel contesto di vLLM

Il sottosistema multimodale di vLLM raggruppa i modelli in base alle modalità che accettano in input. Le categorie rilevanti sono:

I modelli omni-modali condividono un unico backbone linguistico, con encoder dedicati per ciascuna modalità (un ViT per immagini e frame video, un encoder audio derivato da architetture ispirate a Whisper, ecc.). Il compito di vLLM consiste nello schedulare tali encoder, memorizzarne gli output nella cache e intercalarli al flusso di token testuali nella cache KV, mantenendo così elevate le prestazioni.

La generazione dell'output in vLLM produce esclusivamente testo. Se si desidera sfruttare la funzionalità nativa di sintesi vocale (speech synthesis) supportata da Qwen2.5-Omni, è attualmente necessario utilizzare l'implementazione di riferimento fornita dagli autori del modello: vLLM restituirà la trascrizione testuale, non l'onda sonora. Questo è l'aspetto più importante da comprendere prima di scegliere vLLM per un carico di lavoro omni.

Modelli omni-modali supportati

L'elenco ufficiale è disponibile nella documentazione di vLLM alla voce Modelli supportati → Modelli linguistici multimodali. Come punto di riferimento stabile, queste famiglie godono già da tempo di supporto upstream:

• Qwen2.5-Omni (3B, 7B) — il modello «omni» canonico, con input testo + immagine + audio + video e output testuale.
• MiniCPM-o 2.6 — modello omni da circa 8 miliardi di parametri sviluppato da OpenBMB.
• Qwen2-VL / Qwen2.5-VL — supporto esclusivo per visione e video, ma spesso incluso nei flussi di lavoro «omni».
• Qwen2-Audio — modello complementare dedicato esclusivamente all'audio.

Poiché il supporto per nuovi modelli viene aggiunto con ogni rilascio, verificare sempre la documentazione corrente e la scheda del modello per conoscere la versione minima di vLLM richiesta. Tentare di eseguire un nuovo modello omni su una versione obsoleta di vLLM è il motivo più comune di errore. Database di modelli se si sta ancora valutando l'opzione.

Requisiti hardware

I modelli omni-modali sono più pesanti dei corrispondenti modelli testuali con lo stesso numero di parametri, poiché includono encoder aggiuntivi e poiché gli input visivi/audio richiedono molti token dopo la tokenizzazione. Una singola immagine a risoluzione nativa può espandersi in 1.000–4.000 token; un minuto di audio in diverse centinaia.

Si tratta di intervalli pratici, non dei valori minimi indicati nelle specifiche tecniche. Per un valore esatto in base alla lunghezza del contesto e alla dimensione del batch, inserisci il modello nel Calcolatore VRAM o consulta la Riferimento sui requisiti di VRAM. Se non hai ancora scelto l’hardware, la le migliori GPU per LLM locali guida illustra i compromessi relativi alle fasce da 24 GB, 48 GB e multi-GPU.

Installazione

vLLM è progettato principalmente per Linux. Windows non è ufficialmente supportato; utilizza WSL2 o un contenitore Linux. macOS dispone di una build dedicata alla sola CPU che caricherà tecnicamente modelli piccoli, ma non è adatta per il servizio multimodale in produzione.

Linux (consigliato)

Requisiti: GPU compatibile con CUDA (compute capability 7.0 o superiore), driver CUDA 12.x, Python 3.9–3.12.

# Crea un ambiente isolato
python -m venv vllm-env
source vllm-env/bin/activate

# Installa vLLM (questo comando scarica automaticamente una versione compatibile di PyTorch)
pip install vllm

# Dipendenze aggiuntive comunemente necessarie per i modelli omni
pip install librosa soundfile decord

vllm --version

Il librosa, soundfile, e decord gestiscono rispettivamente il decoding audio e l’estrazione dei frame video. Alcuni modelli omni li richiamano automaticamente tramite trust_remote_code; installarli preventivamente evita errori alla prima richiesta.

Windows (tramite WSL2)

Installa WSL2 con una distribuzione Ubuntu 22.04 o 24.04, installa il driver NVIDIA su Windows (il lato WSL utilizza direttamente il driver Windows), quindi segui i passaggi per Linux all’interno di WSL. Non installare un driver NVIDIA Linux separato all’interno di WSL: ciò causerebbe un malfunzionamento di CUDA.

macOS

Non esiste supporto CUDA su macOS e vLLM non supporta Metal. Per l’inferenza multimodale locale su Apple Silicon, utilizza invece LM Studio o runtime basati su MLX. In questo caso vLLM non è lo strumento adatto.

Esecuzione di un modello omni

Avvia un server compatibile con l’API OpenAI:

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

Principali flag:

• --trust-remote-code è obbligatorio perché i modelli omni includono codice personalizzato per il preprocessing nei loro repository su Hugging Face.
• --limit-mm-per-prompt limita il numero di elementi per ciascuna modalità per richiesta. Aumentare questi valori incrementa il budget di input multimodale, ma anche la pressione sulla VRAM.
• --max-model-len deve essere impostato esplicitamente. I token visivi e audio contribuiscono al suo conteggio.
• --tensor-parallel-size N viene distribuito su N GPU qualora una singola scheda non sia sufficiente.

Invio di richieste multimodali

vLLM espone l’API OpenAI Chat Completions. Le parti multimodali seguono la convenzione dell’array content di OpenAI:

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": "Descrivi ciò che vedi e senti."},
        {"type": "image_url", "image_url": {"url": "https://example.com/scene.jpg"}},
        {"type": "audio_url", "audio_url": {"url": "https://example.com/clip.wav"}}
      ]
    }]
  }'

Il client Python è identico a quello di 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": "Trascrivi e riassumi."},
        {"type": "audio_url", "audio_url": {"url": "file:///data/meeting.wav"}},
    ]}],
)
print(resp.choices[0].message.content)

URL dati (data:image/png;base64,...) e percorsi locali file:// sono entrambi supportati; l’insieme esatto degli schemi accettati si è ampliato nelle versioni successive, quindi consulta la documentazione della versione in uso se uno schema non funziona.

Note sulle prestazioni

• La fase di prefill domina. Codificare un clip audio di 1 minuto o un’immagine a 720p richiede molte risorse CPU/GPU ed avviene prima della generazione del primo token. Il batching migliora il throughput, ma non la latenza per singola richiesta.
• Pressione sulla cache KV. Una singola immagine può aggiungere migliaia di token alla cache. Riduci --max-model-len o abbassa --limit-mm-per-prompt se incontri errori di memoria esaurita (OOM) sotto carico.
• Quantizzazione. Le varianti AWQ e GPTQ a 4 bit di Qwen2.5-Omni-7B possono essere eseguite su una scheda da 16 GB e subiscono una perdita relativamente modesta di qualità nei compiti di comprensione visiva e audio. La disponibilità dipende dagli upload della comunità su Hugging Face.
• Prefill suddiviso in blocchi (attivato per impostazione predefinita nelle versioni più recenti) attenua la latenza quando si mescolano richieste multimodali e richieste testuali pure.

Quando utilizzare vLLM omni rispetto ad alternative

Se stai ancora decidendo se eseguire il modello in autonomia, calcola i costi con il Calcolatore del punto di pareggio tra auto-hosting e utilizzo di APII carichi di lavoro omni-modalità influenzano la scelta, poiché il numero di token per richiesta è molto più elevato rispetto ai modelli testuali puri, rendendo i prezzi basati sull’uso più costosi per ogni sessione.

Domande frequenti

vLLM supporta l’output vocale di Qwen2.5-Omni?

No. vLLM gestisce la generazione di testo partendo dal nucleo linguistico. La testa opzionale per la decodifica audio, che genera le risposte vocali nell’implementazione di riferimento di Qwen2.5-Omni, non è integrata in vLLM. Otterrai quindi solo la risposta testuale del modello e dovrai aggiungere un passaggio separato di sintesi vocale (TTS) o utilizzare il codice di inferenza originale per generare la voce.

Posso eseguire modelli omni vLLM su una scheda da 24 GB come una RTX 4090?

Sì, per le varianti da 3B e 7B, specialmente in bf16 con contesti modesti, oppure comodamente con quantizzazione AWQ/GPTQ su contesti più lunghi. Dovrai ottimizzare --max-model-len e --limit-mm-per-prompt per rimanere al di sotto del limite di memoria. Verifica con il Calcolatore VRAM prima di impegnarsi.

Perché la mia richiesta fallisce con un errore «trust_remote_code»?

I modelli omni-modalità includono preprocessor Python personalizzati nei loro repository Hugging Face. vLLM non eseguirà questo codice a meno che tu non specifichi --trust-remote-code all’avvio del server. Abilita questa opzione solo per repository di modelli di cui ti fidi.

Come invio un video a un endpoint vLLM omni?

Utilizza una parte di contenuto con "type": "video_url" che punta a un URL accessibile o a un file locale. vLLM estrae i frame usando decord; il numero esatto di frame e la politica di campionamento sono specifici del modello e documentati nella scheda del modello. I video consumano rapidamente token, quindi mantieni i clip brevi e imposta --limit-mm-per-prompt video=1 a meno che tu non disponga di molta VRAM.

Esiste un’immagine Docker per vLLM omni?

L’immagine ufficiale vllm/vllm-openai su Docker Hub supporta nativamente i modelli multimodali per la versione di vLLM indicata nel tag. Preferisci un tag specifico piuttosto che versione più recente per evitare che la versione richiesta dal tuo modello omni cambi inaspettatamente.

Ollama può eseguire questi modelli omni?

Ollama supporta alcuni modelli visione-linguaggio, ma la sua copertura omni-modale è inferiore a quella di vLLM e gli input audio/video sono limitati o assenti per la maggior parte dei modelli. Per un flusso di lavoro desktop, consulta la I migliori modelli locali per Ollama e il Elenco modelli Ollama per verificare quali modelli sono attualmente disponibili; per sfruttare appieno le funzionalità omni su un server, continua a usare vLLM.