Suporte Omni-Modal do vLLM: Executando Modelos Multimodais com o vLLM

vLLM omni não é um produto separado. É uma abreviação para o uso do vLLM — mecanismo de inferência de LLM de alta vazão — para servir modelos omni-modais modelos omni-modais, ou seja, modelos que aceitam texto, imagens, áudio e vídeo em uma única conversa. Na prática, isso quase sempre significa a série Qwen2.5-Omni da Alibaba, embora a pilha multimodal do vLLM também processe modelos exclusivamente visuais ou exclusivamente auditivos por meio da mesma API.

Este guia explica o que significa “omni” no contexto do vLLM, quais modelos são compatíveis, como instalá-los e executá-los, qual é o formato das solicitações e quais são as limitações atuais.

O que “Omni” Significa no Contexto do vLLM

O subsistema multimodal do vLLM agrupa os modelos conforme as modalidades que aceitam na entrada. As categorias relevantes são:

Modelos omni-modais compartilham uma única estrutura linguística principal, com codificadores separados para cada modalidade (um ViT para imagens e quadros de vídeo, um codificador de áudio derivado de arquiteturas estilo Whisper, entre outros). A tarefa do vLLM é agendar esses codificadores, armazenar em cache suas saídas e intercalar essas saídas com o fluxo de tokens de texto no cache KV, mantendo assim uma alta vazão.

A geração de saída no vLLM é textual. Se você deseja a funcionalidade nativa de síntese de fala suportada pela Qwen2.5-Omni, atualmente precisa usar a implementação de referência dos autores do modelo — o vLLM fornecerá apenas a transcrição textual, não a forma de onda de áudio. Essa é a informação mais importante a ser compreendida antes de optar pelo vLLM para cargas de trabalho omni.

Modelos Omni-Modais Compatíveis

A lista oficial está disponível na documentação do vLLM, sob Modelos Compatíveis → Modelos de Linguagem Multimodais. Como ponto de referência estável, as seguintes famílias têm suporte consolidado há algum tempo:

• Qwen2.5-Omni (3B, 7B) — o modelo “omni” padrão, com entradas de texto + imagem + áudio + vídeo e saída textual.
• MiniCPM-o 2.6 — modelo omni de classe 8B da OpenBMB.
• Qwen2-VL / Qwen2.5-VL — apenas visão e vídeo, mas frequentemente incluído nos fluxos de trabalho “omni”.
• Qwen2-Audio — complemento exclusivamente auditivo.

Como o suporte a modelos é adicionado em cada nova versão, verifique sempre a documentação atual e o cartão do modelo para identificar a versão mínima do vLLM exigida. Tentar executar um novo modelo omni em uma versão antiga do vLLM é o modo de falha mais comum. Consulte uma lista atualizada de banco de dados de modelos se você ainda estiver escolhendo.

Requisitos de hardware

Modelos omni-modais são mais pesados do que seus equivalentes de texto puro com a mesma contagem de parâmetros, pois incorporam codificadores adicionais e porque entradas visuais/auditivas geram muitos tokens após a tokenização. Uma única imagem em resolução nativa pode expandir-se para 1.000–4.000 tokens; um minuto de áudio, para várias centenas.

Essas são faixas práticas, não mínimos indicados nas folhas de especificações. Para um valor exato conforme seu comprimento de contexto e tamanho de lote, insira o modelo no Calculadora de VRAM ou consulte o Referência de requisitos de VRAM. Se você ainda não escolheu o hardware, o melhores GPUs para LLMs locais guia aborda as compensações nas faixas de 24 GB, 48 GB e múltiplas GPUs.

Instalação

O vLLM prioriza Linux. O Windows não é oficialmente suportado; use WSL2 ou um contêiner Linux. O macOS possui uma versão compatível apenas com CPU, que tecnicamente carrega modelos pequenos, mas não é viável para atendimento multimodal em produção.

Linux (recomendado)

Requisitos: GPU compatível com CUDA (capacidade de computação 7.0+), drivers CUDA 12.x e Python 3.9–3.12.

# Crie um ambiente isolado
python -m venv vllm-env
source vllm-env/bin/activate

# Instale o vLLM (isso instala automaticamente uma versão compatível do PyTorch)
pip install vllm

# Dependências adicionais comumente necessárias para modelos omni
pip install librosa soundfile decord

vllm --version

O librosa, soundfile, e decord esses pacotes lidam com a decodificação de áudio e a extração de quadros de vídeo. Alguns modelos omni os importam automaticamente por meio de trust_remote_code; instalá-los antecipadamente evita falhas na primeira requisição.

Windows (via WSL2)

Instale o WSL2 com uma distribuição Ubuntu 22.04 ou 24.04, instale o driver NVIDIA no Windows (o lado WSL usa diretamente o driver do Windows) e, em seguida, siga os passos para Linux dentro do WSL. Não instale um driver NVIDIA Linux separado dentro do WSL — isso quebrará o CUDA.

macOS

Não há suporte para CUDA no macOS, e o vLLM não tem suporte nativo ao Metal. Para inferência multimodal local em chips Apple Silicon, use LM Studio ou ambientes de execução baseados em MLX. O vLLM não é a ferramenta adequada nesse caso.

Executando um Modelo Omni

Inicie um servidor compatível com a 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

Principais flags:

• --trust-remote-code é obrigatória porque os modelos omni incluem código personalizado de pré-processamento em seus repositórios no Hugging Face.
• --limit-mm-per-prompt limita o número de entradas por modalidade em cada requisição. Aumentar esses valores amplia o orçamento de entrada multimodal, mas também eleva a pressão sobre a VRAM.
• --max-model-len deve ser definido explicitamente. Tokens visuais e de áudio contam contra esse limite.
• --tensor-parallel-size N divide o processamento entre N GPUs caso uma única placa seja insuficiente.

Fazendo Solicitações Multimodais

O vLLM expõe a API OpenAI Chat Completions. As partes multimodais seguem a convenção do array de conteúdo da 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": "Descreva o que você vê e ouve."},
        {"type": "image_url", "image_url": {"url": "https://example.com/scene.jpg"}},
        {"type": "audio_url", "audio_url": {"url": "https://example.com/clip.wav"}}
      ]
    }]
  }'

O cliente Python é idêntico ao da 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": "Transcreva e resuma."},
        {"type": "audio_url", "audio_url": {"url": "file:///data/meeting.wav"}},
    ]}],
)
print(resp.choices[0].message.content)

URLs de dados (data:image/png;base64,...) e caminhos locais file:// funcionam; o conjunto exato de esquemas aceitos foi ampliado ao longo das versões, portanto, consulte a documentação da versão específica caso algum esquema não funcione.

Observações sobre Desempenho

• A fase de prefill domina. Codificar um clipe de áudio de 1 minuto ou uma imagem em 720p exige grande carga da CPU/GPU e ocorre antes da geração do primeiro token. O agrupamento (batching) melhora o throughput, mas não reduz a latência por requisição.
• Pressão sobre o cache KV. Uma única imagem pode adicionar milhares de tokens ao cache. Reduza --max-model-len ou diminua --limit-mm-per-prompt se você encontrar erros de memória insuficiente (OOM) sob carga.
• Quantização. Variantes AWQ e GPTQ de 4 bits do Qwen2.5-Omni-7B cabem em uma placa de 16 GB e apresentam perda relativamente pequena de qualidade em tarefas de compreensão visual e auditiva. A disponibilidade depende de envios da comunidade no Hugging Face.
• Prefill fragmentado (ativado por padrão em versões recentes) suaviza a latência ao misturar requisições multimodais e requisições exclusivamente textuais.

Quando Usar o vLLM Omni versus Alternativas

Se você ainda está decidindo se deve fazer o autohospedagem ou não, faça os cálculos com a calculadora de ponto de equilíbrio entre hospedagem local e uso de API. Cargas de trabalho omni-modais inclinam a resposta, pois a contagem de tokens por solicitação é muito maior do que em modelos somente de texto, tornando o preço baseado no uso da API mais caro por sessão.

Perguntas frequentes

O vLLM suporta a saída de fala do Qwen2.5-Omni?

Não. O vLLM lida com a geração de texto a partir da estrutura linguística do modelo. A cabeça opcional de decodificação de áudio — responsável pela produção de respostas faladas na implementação de referência do Qwen2.5-Omni — não está integrada ao vLLM. Você obtém a resposta textual do modelo e precisará de um passo separado de TTS (conversão texto-para-fala) ou do código original de inferência para sintetizar a fala.

Posso executar modelos omni do vLLM em uma placa de 24 GB, como uma RTX 4090?

Sim, para as variantes de 3B e 7B, especialmente em bf16 com contexto modesto, ou confortavelmente com quantização AWQ/GPTQ em contextos mais longos. Você precisará ajustar --max-model-len e --limit-mm-per-prompt para permanecer abaixo do limite de memória. Verifique com o Calculadora de VRAM antes de comprometer-se.

Por que minha solicitação falha com um erro "trust_remote_code"?

Modelos omni-modais incluem preprocessadores Python personalizados em seus repositórios no Hugging Face. O vLLM não executa esse código a menos que você passe --trust-remote-code na inicialização do servidor. Ative essa opção apenas para repositórios de modelos de que você confia.

Como envio um vídeo para um endpoint omni do vLLM?

Use uma parte de conteúdo com "type": "video_url" apontando para uma URL acessível ou para um arquivo local. O vLLM amostra quadros usando decord; o número exato de quadros e a política de amostragem são específicos do modelo e documentados na ficha técnica do modelo. Vídeos consomem tokens rapidamente, portanto mantenha os clipes curtos e defina --limit-mm-per-prompt video=1 a menos que você tenha muita VRAM disponível.

Existe uma imagem Docker para o vLLM omni?

A imagem oficial do vllm/vllm-openai no Docker Hub suporta modelos multimodais nativamente, para qualquer versão do vLLM com a qual ela for marcada. Prefira fixar uma tag específica em vez de usar mais recente para evitar que a versão exigida pelo seu modelo omni seja alterada sem aviso.

O Ollama pode executar esses modelos omni em vez disso?

O Ollama suporta alguns modelos de linguagem e visão, mas sua cobertura omni-modal fica atrás da do vLLM, e entradas de áudio/vídeo são limitadas ou inexistentes na maioria dos modelos. Para fluxos de trabalho em desktop, consulte a melhores modelos locais para Ollama e o Lista de modelos do Ollama para ver quais modelos estão atualmente disponíveis; para recursos omni completos em um servidor, continue utilizando o vLLM.