Soporte multimodal integral de vLLM: Ejecución de modelos multimodales con vLLM

vLLM omni no es un producto independiente. Es una abreviatura para describir el uso de vLLM —el motor de inferencia de LLM de alto rendimiento— para servir modelos multimodales integrales , es decir, modelos capaces de aceptar texto, imágenes, audio y video dentro de una única conversación. En la práctica, esto casi siempre significa los modelos de la serie Qwen2.5-Omni Qwen2.5-Omni de Alibaba, aunque la pila multimodal de vLLM también admite modelos exclusivos de visión o de audio mediante la misma API.

Esta guía explica qué significa «omni» dentro del contexto de vLLM, qué modelos están admitidos, cómo instalarlos y servirlos, cuál es el formato de las solicitudes y cuáles son las limitaciones actuales.

Qué significa «Omni» en el contexto de vLLM

El subsistema multimodal de vLLM clasifica los modelos según las modalidades que aceptan como entradas. Las categorías relevantes son:

Los modelos multimodales integrales comparten una única arquitectura lingüística central, junto con codificadores independientes para cada modalidad (por ejemplo, una ViT para imágenes y fotogramas de video, un codificador de audio basado en arquitecturas tipo Whisper, etc.). La función de vLLM consiste en programar estos codificadores, almacenar en caché sus resultados y entrelazarlos con el flujo de tokens de texto en la caché KV para mantener un alto rendimiento.

La generación de salidas en vLLM es exclusivamente textual. Si necesita la funcionalidad nativa de síntesis de voz (audio-out) que ofrece Qwen2.5-Omni, actualmente debe recurrir a la implementación de referencia proporcionada por los autores del modelo; vLLM le devolverá la transcripción textual, no la forma de onda de audio. Este es el aspecto más importante que debe comprender antes de elegir vLLM para una carga de trabajo integral.

Modelos multimodales integrales admitidos

La lista oficial se encuentra en la documentación de vLLM, bajo la sección Modelos admitidos → Modelos de lenguaje multimodales. Como punto de referencia estable, estas familias han contado con soporte oficial durante algún tiempo:

• Qwen2.5-Omni (3B, 7B) —el modelo integral canónico, con entradas de texto + imagen + audio + video y salida textual.
• MiniCPM-o 2.6 —modelo integral de clase 8B desarrollado por OpenBMB.
• Qwen2-VL / Qwen2.5-VL —solo visión y video, pero frecuentemente agrupado con flujos de trabajo «integrales».
• Qwen2-Audio —versión exclusiva de audio.

Dado que el soporte para nuevos modelos se añade en cada versión, siempre consulte la documentación actual y la ficha del modelo para verificar la versión mínima requerida de vLLM. Intentar servir un nuevo modelo integral con una versión antigua de vLLM es el modo de fallo más habitual. Explore una Base de datos de modelos actualizada si aún está evaluando opciones.

Requisitos de hardware

Los modelos multimodales integrales son más pesados que sus equivalentes de solo texto con el mismo número de parámetros, ya que incluyen codificadores adicionales y porque las entradas visuales o de audio generan muchos tokens tras su tokenización. Una sola imagen a resolución nativa puede expandirse a entre 1.000 y 4.000 tokens; un minuto de audio, a varios cientos.

Estos son rangos prácticos, no mínimos teóricos indicados en las hojas de especificaciones. Para obtener una cifra exacta según su longitud de contexto y tamaño de lote, integre el modelo en Calculadora de VRAM o consulte la Referencia de requisitos de VRAM. Si aún no ha elegido el hardware, la mejoras GPUs para modelos de lenguaje local guía explica las compensaciones existentes entre las categorías de 24 GB, 48 GB y múltiples GPU.

Instalación

vLLM está orientado principalmente a Linux. Windows no es oficialmente compatible; use WSL2 o un contenedor Linux. En macOS existe una versión exclusiva para CPU que técnicamente puede cargar modelos pequeños, pero no es viable para la prestación de servicios multimodales en entornos productivos.

Linux (recomendado)

Requisitos: una GPU compatible con CUDA (capacidad de cómputo 7.0 o superior), controladores CUDA 12.x y Python 3.9–3.12.

# Cree un entorno aislado
python -m venv vllm-env
source vllm-env/bin/activate

# Instale vLLM (esto instala automáticamente una versión compatible de PyTorch)
pip install vllm

# Dependencias adicionales habitualmente necesarias para modelos omni
pip install librosa soundfile decord

vllm --version

El librosa, soundfile, y decord estos paquetes gestionan la decodificación de audio y la extracción de fotogramas de vídeo. Algunos modelos omni los incluyen automáticamente mediante trust_remote_code; instalarlos previamente evita errores en la primera solicitud.

Windows (mediante WSL2)

Instale WSL2 con una distribución Ubuntu 22.04 o 24.04, instale el controlador NVIDIA en Windows (el lado de WSL utiliza directamente el controlador de Windows) y luego siga los pasos para Linux dentro de WSL. No instale un controlador NVIDIA para Linux independiente dentro de WSL, ya que esto inutilizará CUDA.

macOS

No existe soporte CUDA en macOS y vLLM no está diseñado para Metal. Para inferencia multimodal local en chips Apple Silicon, use LM Studio u otros entornos de ejecución basados en MLX. vLLM no es la herramienta adecuada en este caso.

Servir un modelo integral

Inicie un servidor compatible con 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

Parámetros clave:

• --trust-remote-code es obligatorio porque los modelos omni incluyen código personalizado de preprocesamiento en sus repositorios de Hugging Face.
• --limit-mm-per-prompt limita el número de elementos por modalidad en cada solicitud. Aumentar estos valores incrementa el presupuesto de entrada multimodal, pero también eleva la presión sobre la VRAM.
• --max-model-len debe establecerse explícitamente. Los tokens visuales y de audio cuentan contra este límite.
• --tensor-parallel-size N distribuye la carga entre N GPU si una sola tarjeta resulta insuficiente.

Realizar solicitudes multimodales

vLLM expone la API OpenAI Chat Completions. Las partes multimodales siguen la convención del array de contenido de 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": "Describa lo que ve y oye."},
        {"type": "image_url", "image_url": {"url": "https://example.com/scene.jpg"}},
        {"type": "audio_url", "audio_url": {"url": "https://example.com/clip.wav"}}
      ]
    }]
  }'

El cliente en Python es idéntico al de 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": "Transcriba y resuma."},
        {"type": "audio_url", "audio_url": {"url": "file:///data/meeting.wav"}},
    ]}],
)
print(resp.choices[0].message.content)

Las URLs de datos (data:image/png;base64,...) y las rutas locales file:// son ambas válidas; el conjunto exacto de esquemas admitidos ha ido ampliándose con cada versión, por lo que, si algún esquema falla, consulte la documentación correspondiente a su versión.

Notas sobre rendimiento

• El prellenado domina. Codificar un clip de audio de 1 minuto o una imagen en 720p exige una alta carga de CPU/GPU y ocurre antes de generar el primer token. El procesamiento por lotes mejora el rendimiento global, pero no reduce la latencia por solicitud.
• Presión sobre la caché KV. Una sola imagen puede añadir miles de tokens a la caché. Reduzca --max-model-len o disminuya --limit-mm-per-prompt si experimenta errores de memoria insuficiente (OOM) bajo carga.
• Cuantización. Las variantes AWQ y GPTQ de 4 bits de Qwen2.5-Omni-7B caben en una tarjeta de 16 GB y pierden relativamente poca calidad en tareas de comprensión visual y auditiva. Su disponibilidad depende de las cargas realizadas por la comunidad en Hugging Face.
• Prefill fragmentado (activado por defecto en versiones recientes) suaviza la latencia al mezclar solicitudes multimodales y solicitudes exclusivamente textuales.

Cuándo usar vLLM Omni frente a alternativas

Si aún está decidiendo si autoalojar o no, calcule los costos con la calculadora de punto de equilibrio entre alojamiento local y uso de API. Las cargas de trabajo omni-modales inclinan la respuesta, ya que el número de tokens por solicitud es mucho mayor que en tareas exclusivamente textuales, lo que hace que el precio basado en el uso de la API resulte más caro por sesión.

Preguntas frecuentes

¿Admite vLLM la salida de voz de Qwen2.5-Omni?

No. vLLM se encarga de la generación de texto a partir del núcleo lingüístico. La cabeza opcional de decodificación de audio, que produce respuestas habladas en la implementación de referencia de Qwen2.5-Omni, no está integrada en vLLM. Obtendrá la respuesta textual del modelo y necesitará un paso adicional independiente de síntesis de voz (TTS) o el código original de inferencia para sintetizar el habla.

¿Puedo ejecutar modelos omni de vLLM en una tarjeta de 24 GB, como una RTX 4090?

Sí, para las variantes de 3B y 7B, especialmente en bf16 con un contexto moderado, o cómodamente con cuantización AWQ/GPTQ en contextos más largos. Deberá ajustar --max-model-len y --limit-mm-per-prompt para permanecer por debajo del límite de memoria. Verifíquelo con la Calculadora de VRAM antes de comprometerse.

¿Por qué falla mi solicitud con un error «trust_remote_code»?

Los modelos omni-modales incluyen preprocesadores personalizados en Python en sus repositorios de Hugging Face. vLLM no ejecutará este código a menos que pase --trust-remote-code al iniciar el servidor. Solo habilite esta opción para repositorios de modelos de los que confíe plenamente.

¿Cómo envío vídeo a un extremo (endpoint) omni de vLLM?

Utilice una parte de contenido con "type": "video_url" que apunte a una URL accesible o a un archivo local. vLLM muestrea fotogramas mediante decord; el número exacto de fotogramas y la política de muestreo son específicos del modelo y están documentados en su ficha técnica (model card). Los vídeos consumen tokens rápidamente, así que mantenga los clips cortos y establezca --limit-mm-per-prompt video=1 a menos que disponga de mucha VRAM.

¿Existe una imagen Docker para vLLM omni?

La imagen oficial de vllm/vllm-openai en Docker Hub admite modelos multimodales listos para usar, según la versión de vLLM con la que esté etiquetada. Fije su uso a una etiqueta específica en lugar de la más reciente para evitar que la versión requerida por su modelo omni cambie sin previo aviso.

¿Puede Ollama ejecutar estos modelos omni en su lugar?

Ollama admite algunos modelos de visión y lenguaje, pero su cobertura omni-modal queda atrás respecto a la de vLLM, y las entradas de audio y vídeo están limitadas o ausentes en la mayoría de los modelos. Para flujos de trabajo en escritorio, consulte la mejores modelos locales para Ollama y la Lista de modelos de Ollama para ver qué está disponible actualmente; para disfrutar de todas las funciones omni en un entorno de servidor, siga utilizando vLLM.