vllm-project/vllm-omni · 上手攻略

仓库：vllm-project/vllm-omni
链接：https://github.com/vllm-project/vllm-omni
分类：ai
作者：Tom
更新：2026-07-13

这是什么

vLLM-Omni 是 vLLM 社区推出的全模式（omni-modality）推理框架，将 vLLM 的高性能 LLM 推理能力扩展到任意到任意的多模态模型——不只是理解图像/视频/音频，而是能同时生成多种模态的输出（文本+图像+视频+音频）。

支持的输出类型： - 自回归（AR）生成：文本问答、代码生成等 - 扩散模型（DiT）生成：图片生成、视频生成 - TTS 语音合成：端到端语音输出 - 混合输出：如 Qwen3-Omni 的 Thinker-Talker 架构，同时输出文本和语音

一句话概括：vLLM 在多模态生成领域的扩展，让研究者和企业能用生产级性能跑 Omni-Modality 模型。

解决什么问题

多模态模型推理框架碎片化：每个模型（Qwen-Omni、HunyuanImage、Wan2.2、TTS 模型）有自己的推理代码，vLLM-Omni 提供统一抽象
性能瓶颈：原生 PyTorch 推理太慢，vLLM-Omni 复用 vLLM 的 PagedAttention KV cache 管理，显著提升吞吐量
部署复杂：多阶段模型（如图像→文本→语音）需要手动编排流水线，vLLM-Omni 用 OmniConnector 和异构流水线抽象简化
分布式推理门槛：多 GPU/TPU 部署需要手动写并行代码，框架内置 Tensor/Pipeline/Data/Expert 并行支持
API 兼容性：提供 OpenAI-Compatible API Server，方便迁移现有应用

快速安装

环境要求

OS：Linux（GPU 版本）
Python：3.12
GPU：NVIDIA CUDA（或 AMD ROCm、Intel XPU、MT MUSA、NPU）
磁盘：HuggingFace 模型通常 5-30GB，建议预留充足空间

从源码安装（CUDA）

# 创建虚拟环境
uv venv --python 3.12 --seed
source .venv/bin/activate

# 安装 vLLM（CUDA 后端）
uv pip install vllm==0.25.0 --torch-backend=auto

# 克隆并安装 vLLM-Omni
git clone https://github.com/vllm-project/vllm-omni.git
cd vllm-omni
uv pip install -e .

⚠️ 版本匹配重要：vLLM 和 vLLM-Omni 必须使用相同的主版本号（如都是 0.25.0），否则会报兼容错误。如果 vllm serve --omni 不认 --omni 参数，大概率是 vLLM 版本低于 0.25.0。

Docker（NVIDIA GPU）

docker run --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8091:8091 \
  nvcr.io/nvidia/pytorch:24.01-py3 \
  bash -c "uv pip install vllm==0.25.0 && git clone https://github.com/vllm-project/vllm-omni && cd vllm-omni && uv pip install -e . && vllm serve Qwen/Qwen2.5-Omni --omni --port 8091"

其他后端

# AMD ROCm
uv pip install vllm==0.25.0+rocm723 --extra-index-url https://wheels.vllm.ai/rocm/0.25.0/rocm723

# Intel XPU
# 见 https://docs.vllm.ai/projects/vllm-omni/en/latest/getting_started/installation/gpu/

# NPU（华为昇腾）
# 见 https://docs.vllm.ai/projects/vllm-omni/en/latest/getting_started/installation/npu/

核心用法

方式一：离线推理（Python API）

文生图

from vllm_omni.entrypoints.omni import Omni

omni = Omni(model="Tongyi-MAI/Z-Image-Turbo")
prompt = "a cup of coffee on the table"
outputs = omni.generate(prompt)
images = outputs[0].request_output.images
images[0].save("coffee.png")

批量推理

from vllm_omni.entrypoints.omni import Omni

omni = Omni(model="Tongyi-MAI/Z-Image-Turbo")

prompts = [
    "a cup of coffee on a table",
    "a toy dinosaur on a sandy beach",
    "a fox waking up in bed and yawning",
]

omni_outputs = omni.generate(prompts)

for i_prompt, prompt_output in enumerate(omni_outputs):
    this_images = prompt_output.request_output.images
    for i_image, image in enumerate(this_images):
        image.save(f"p{i_prompt}-img{i_image}.jpg")

Omni-Modality 模型（文本+图像+音频混合）

# Qwen3-Omni 等模型用法（以文档示例为准）
# 文档：https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/examples/offline_inference/qwen2_5_omni/

方式二：在线推理（OpenAI-Compatible API）

启动服务器（推荐用于生产）：

# 文生图服务
vllm serve Tongyi-MAI/Z-Image-Turbo \
  --omni \
  --port 8091 \
  --tensor-parallel-size 2    # 多卡并行

# Qwen3-Omni 服务（带语音的 Omni 模型）
vllm serve Qwen/Qwen2.5-Omni \
  --omni \
  --port 8091

调用 API：

# OpenAI Chat Completions 格式
curl -s http://localhost:8091/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "a cup of coffee on the table"}
    ],
    "extra_body": {
      "height": 1024,
      "width": 1024,
      "num_inference_steps": 50,
      "guidance_scale": 4.0,
      "seed": 42
    }
  }'

方式三：HuggingFace 兼容推理（transformers 直接调用）

# 通过 vllm.llm 高级 API
from vllm import LLM

llm = LLM(
    model="Qwen/Qwen2.5-Omni",
    omni=True,               # 启用 omni 模式
    tensor_parallel_size=2,  # 多卡
    gpu_memory_utilization=0.9
)

outputs = llm.chat([
    {"role": "user", "content": "Explain quantum computing"}
])
print(outputs[0].outputs[0].text)

支持的主要模型

类型	代表模型	支持情况
Omni-Modality	Qwen2.5-Omni, Qwen3-Omni, Cosmos, Bagel	✅ AR + 多输出
文生图	Wan2.2, FLUX, HunyuanImage, Qwen-Image	✅ DiT 加速
视频生成	Wan2.2 Video	✅ 流水化执行
TTS	Qwen3-TTS, Moss-TTS, CosyVoice3	✅ 端到端
通用 VLMs	Qwen2.5-VL, LLaVA 等	✅ 标准 VLM

完整列表见：https://docs.vllm.ai/projects/vllm-omni/en/latest/models/supported_models/

典型适用场景

场景	为什么用 vLLM-Omni
企业级多模态 API 服务	OpenAI-Compatible API + 高吞吐 + 多卡并行
AI 助手语音输出	Omni 模型同时输出文本+语音，不需要 TTS 微服务
图像/视频生成流水线	DiT 模型加速，pipeline 并行减少端到端延迟
多模态 RAG	Omni 模型统一处理文档中的文本+图像+表格
研究实验	统一的推理框架，方便对比不同多模态模型
多 Agent 系统	不同 Agent 调用统一的多模态推理服务

坑与注意

版本匹配是硬性要求：vLLM-Omni 0.25.0 必须配 vLLM 0.25.0。混用版本会导致 Omni 类报错或 --omni 参数不识别。更新时两个包一起更新
多节点分布式需要 Ray：多 GPU 但不同机器需要 Ray 集群，tensor_parallel_size 只在同一机器内有效
OMNI 模块独立安装：vLLM-Omni 是 vLLM 的插件扩展，不是 vLLM 内置模块，需要单独 git clone 和 pip install -e .
NVIDIA GPU 是主力后端：CUDA 支持最完整，ROCm/XPU/MUSA/NPU 可能有额外踩坑，参考文档对应章节
HuggingFace 模型下载慢：建议提前 huggingface-cli download 或配置镜像（如 hf-mirror.com），首次启动会下载大量权重
diffusion 模型的 batching 控制：扩散类模型用 max_num_seqs 和 request_batch_max_wait_ms 控制批处理，参考文档 Request-Level Batching 章节
内存要求高：高分辨率图像/视频生成需要大显存，建议至少 24GB GPU（如 A100）或用量化版本

与同类对比

框架	定位	多模态生成	性能	部署难度
vLLM-Omni	Omni-Modality 推理框架	✅ 图/视频/TTS/Omni	高（继承vLLM PagedAttention）	中等
vLLM	LLM 高性能推理	❌ 纯文本	最高	低
Ollama	本地模型一键跑	✅ 基础多模态	中等	最低
llama.cpp	CPU/GPU 量化推理	✅ 基础多模态	中等（量化）	低
TGI (HuggingFace)	文本推理服务	✅ VLMs	高	低
vLLM + 微服务	多模态拼接方案	✅ 各模态独立服务	低（无统一调度）	高（多组件）
MLX (Apple Silicon)	Apple GPU 优化	✅	中等（MLX优化）	中

vLLM-Omni 的核心差异：第一个将 vLLM 的高性能推理架构扩展到任意多模态生成的框架，同时支持 AR 和 DiT 两种范式的统一调度。如果已经在用 vLLM，想扩展多模态生成能力，门槛最低。

一句话推荐结论

vLLM-Omni 是多模态 AI 时代的高性能推理底座——把 vLLM 的效率带到 Omni-Modality、Diffusion、TTS 全家桶，适合需要同时处理文本/图像/视频/音频的企业 AI 服务和研究流水线。（⚠️ 版本匹配是首要避坑点，vLLM 和 vLLM-Omni 必须同版本号。）