vLLM-Omni：全模态模型推理与服务的统一框架——从文本 AR 到 DiT、TTS 与机器人策略

vLLM-Omni：全模态模型推理与服务的统一框架——从文本 AR 到 DiT、TTS 与机器人策略

【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni

vLLM-Omni 是 vLLM 社区为 omni-modality（全模态）模型推理与服务打造的扩展框架，在保留 vLLM 高效 KV Cache 管理与自回归（AR）能力的同时，将执行边界扩展到 Diffusion Transformer（DiT）等非自回归并行生成模型，并统一承载文本、图像、音频、视频与动作（action）数据。本文将基于仓库 README.md 与 架构总览、快速开始、API Server 指南 等文档，系统讲解其定位、核心能力、架构原理、安装方式与实战用法，帮助读者快速上手并理解底层运行机制。

项目定位：为什么需要 vLLM-Omni

vLLM 最初面向的是基于文本的自回归生成任务。然而当前的模型生态早已跨越单一文本模态：语音对话模型需要流式输出音频、图像生成模型依赖 DiT 去噪、视频与音乐生成模型需要非自回归的并行解码、机器人策略模型（VLA）则需要输出动作序列。vLLM-Omni 正是为解决这一缺口而设计，围绕三个核心方向扩展 vLLM：

• Omni-modality：统一处理文本、图像、音频、视频和动作数据的输入与输出；
• 非自回归架构：在 vLLM 的 AR 支持之外，将执行能力扩展至 Diffusion Transformers（DiT）及其他并行生成模型；
• 异构输出：从传统文本生成扩展为多模态输出与动作输出。

从仓库源码结构看，这一扩展体现在两个并行的模型执行模块上：vllm_omni/model_executor承载 AR 类模型（如 Qwen3-Omni、Qwen2.5-Omni、TTS 模型），vllm_omni/diffusion承载 DiT 类扩散模型（如 MiniMax H3、LTX-2.5、Wan2.2、Cosmos3），而 vllm_omni/engine 通过统一的AsyncOmniEngine将它们编排进同一条请求管线。

核心能力概览

性能：快在哪里

vLLM-Omni 的性能优势建立在三条基线上：

1. 一流的 AR 支持：直接复用 vLLM 成熟的 KV Cache 管理与调度机制，多模态模型中文本/音频 token 的自回归部分沿用经过大规模验证的连续批处理（continuous batching）路径；
2. 流水线阶段执行重叠：模型的不同组件被划分为多个 stage，stage 之间以异步分块（async chunk）方式交接数据，从而实现高吞吐；以 Qwen3-Omni 为例，Thinker → Talker → Code2Wav 三段可以各自独立调度，前一段产出后立即交接给后一段；
3. 完全分离式部署（Fully Disaggregation）：基于OmniConnector实现跨 stage 的负载与 KV Cache 传输，并支持按 stage 动态分配资源。

易用性：灵活在哪里

• 异构流水线抽象：PipelineConfig描述逻辑 stage 及其关系，DeployConfig描述放置与资源，二者分离使得同一模型可以按 AR-only、DiT-only 或 AR → DiT 多种拓扑部署，而无需改动模型代码；
• 无缝集成 Hugging Face 模型：模型名直接作为入口参数，如Omni(model="Qwen/Qwen3-Omni-30B-A3B-Instruct")；
• 分布式推理：支持张量并行、流水线并行、数据并行与专家并行；
• 流式输出：音频、视频等媒体输出可以分块流式返回；
• OpenAI 兼容 API Server：通过vllm serve <model> --omni一键启动；
• 全双工实时服务：支持流式音频输入与输出的 realtime full-duplex 服务。

架构原理：stage 化执行范式

为什么需要 stage 抽象

自回归解码、扩散去噪、多模态编码与媒体解码的执行循环、批处理方式、注意力机制、并行度、显存与量化需求完全不同，单一调度器与执行策略无法覆盖所有组件。vLLM-Omni 由此引入stage概念：一个逻辑执行单元，拥有自己的模型组件、执行策略、资源归属与性能目标。stage 不一定是独立进程——Cosmos3 将 reasoner 与 generator 放在同一个 diffusion pipeline 内，而 MiniMax-H3 在文本编码、去噪与 VAE 解码之间暴露逻辑边界，两者都是同一抽象下的合法映射。

分层设计

架构总览 中给出了清晰的层级划分：

Model structure 什么被计算、组件之间如何关联 ↓ PipelineConfig 存在哪些逻辑 stage、如何连接 ↓ Stage runtime policy 每个 stage 如何批处理、注意力、并行化、量化 ↓ DeployConfig stage 运行在哪里、使用哪些设备/副本/连接器

AsyncOmniEngine与Orchestrator负责协调流水线，OmniConnector传输 stage 输出，StageRuntime具体落实放置方案。这种分离保证了一个逻辑模型可以支持多种服务拓扑，模型代码与进程布局、部署资源解耦。

从源码结构看，vllm_omni/config 中的StageConfigFactory与VllmOmniConfig负责将PipelineConfig+DeployConfig解析为类型化的 stage 配置（AR / Generation / Diffusion 三类），再经OmniConfigResolution交接给AsyncOmniEngine与无头启动流程。

代表性模型到 stage 的映射

指标语义：按输出模态选择指标

安装指南

环境前提

• 操作系统：Linux
• Python：3.12

源码安装（GPU）

uv venv --python 3.12 --seed source .venv/bin/activate # CUDA 平台 uv pip install vllm==0.29.0 --torch-backend=auto # ROCm 平台 uv pip install vllm==0.29.0+rocm723 --extra-index-url https://wheels.vllm.ai/rocm/0.29.0/rocm723 git clone https://github.com/vllm-project/vllm-omni.git cd vllm-omni uv pip install -e .

其他安装方式（Docker 镜像、NPU/XPU/MUSA 平台等）详见 安装指南。

版本对齐要求：必须安装相同 major.minor 版本的 vLLM 与 vLLM-Omni，否则导入时会出现版本不匹配警告，且vllm命令可能无法正确处理--omni标志。从 0.29.0 起 vLLM-Omni 不再劫持 vLLM 入口点，若--omni行为异常，多为 vLLM 版本过旧所致，升级 vLLM 即可解决。

仓库根目录的 setup.py 与 requirements 目录可进一步查看依赖约束；docker 目录提供了 CUDA、ROCm、NPU、XPU 等平台的镜像构建文件。

快速开始：离线推理

文本生成图像（单条 prompt）

from vllm_omni.entrypoints.omni import Omni if __name__ == "__main__": omni = Omni(model="Tongyi-MAI/Z-Image-Turbo") prompt = "a cup of coffee on the table" outputs = omni.generate(prompt) images = outputs[0].images images[0].save("coffee.png")

批量 prompt

from vllm_omni.entrypoints.omni import Omni if __name__ == "__main__": omni = Omni( model="Tongyi-MAI/Z-Image-Turbo", # deploy_config="./deploy-config.yaml", # 可选部署覆盖 ) 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.images for i_image, image in enumerate(this_images): image.save(f"p{i_prompt}-img{i_image}.jpg") print("saved to", f"p{i_prompt}-img{i_image}.jpg")

说明：对于 diffusion 流水线，每条 prompt 都会成为一个独立的逻辑请求，运行时会通过调度器与 runner 自动合并兼容的在途请求进行批处理。关于请求级/步级批处理与流式控制，参见 Diffusion 执行模式。

多模态输入（以 Qwen3-Omni 为例）

架构总览 给出了离线 Python 接口的通用形态：Omni类接收prompt与multi_modal_data（如视频帧、音频信号），并可为各 stage 分别传入sampling_params_list：

from vllm_omni.entrypoints.omni import Omni omni = Omni(model="Qwen/Qwen3-Omni-30B-A3B-Instruct") om_inputs = { "prompt": prompt, "multi_modal_data": { "video": video_frames, "audio": audio_signal, }, } outputs = omni.generate(om_inputs, sampling_params_list)

从源码看，vllm_omni/entrypoints/omni.py 中的Omni.generate()默认将非 diffusion 的 LLM 阶段强制为FINAL_ONLY输出（除非显式请求DELTA流式输出），并支持py_generator=True以生成器方式逐条产出OmniRequestOutput。

更多离线示例（包括 Qwen2.5-Omni、TTS、文生视频、图生视频、机器人策略等）可参考 离线推理示例 及 examples/offline_inference 目录。

快速开始：在线服务（OpenAI 兼容 API）

启动服务

vllm serve Tongyi-MAI/Z-Image-Turbo --omni --port 8091

文生图请求

curl -s http://localhost:8091/v1/images/generations \ -H "Content-Type: application/json" \ -d '{ "prompt": "a cup of coffee on the table", "size": "1024x1024", "response_format": "b64_json", "seed": 42 }' | jq -r '.data[0].b64_json' | base64 -d > coffee.png

服务健康检查

export VLLM_OMNI_BASE_URL=http://localhost:8091 curl "$VLLM_OMNI_BASE_URL/health" curl "$VLLM_OMNI_BASE_URL/v1/models" | jq .

启动后可将http://localhost:8091/v1作为 OpenAI SDK 客户端的base_url；若服务端配置了--api-key，请求需携带Authorization: Bearer <api-key>头。

按任务选择端点

vLLM-Omni 的每个服务实例承载一个模型，端点可用性取决于所加载模型支持的任务。核心任务端点如下：

各端点最小请求示例（Chat、Speech、Audio、Image、Image edit 等）详见 API Server 指南。此外，部分流水线还暴露联合视频/音频生成等扩展端点，端点支持与模型相关，使用前应查阅对应模型指南。

支持的模型生态

vLLM-Omni 原生支持模型的实现位于 vllm_omni/model_executor/models（AR 类）与 vllm_omni/diffusion/models（DiT 类）。完整支持矩阵见 支持的模型列表，主要包括：

• 全模态模型：Qwen3-Omni、Qwen2.5-Omni、MiniCPM-o 4.5、Cosmos3、HunyuanImage、BAGEL、Ming-flash-omni-2.0、MammothModa2 等；
• TTS 模型：Qwen3-TTS、IndexTTS 2.5、dots.tts、CosyVoice3、MOSS-TTS、GLM-TTS、Breeze-TTS-2 等；
• 扩散模型（图像/视频/音频生成）：MiniMax H3、LTX-2 / LTX-2.5、SANA-Video、Wan2.1/Wan2.2 系列、Qwen-Image 系列、FLUX 系列、Stable Diffusion、Stable-Audio-Open、HunyuanVideo 等；
• 机器人策略与动作模型：π0（Pi-Zero）、GR00T-N1.7、DreamZero-DROID、InternVLA-A1、SenseNova-U1 等。

硬件支持涵盖 NVIDIA GPU、AMD GPU（ROCm）、Intel GPU（XPU）、Ascend NPU 与 MThreads MUSA，具体到每个模型的支持状态与已验证部署配方（recipe）请查阅 支持的模型列表 与 recipes 目录。

分布式执行与通信

• 分离式推理（Disaggregated Inference）：逻辑 stage 可以运行在独立进程、设备或节点上，Orchestrator保持其声明关系，OmniConnector负责跨 stage 传输张量、KV Cache 数据与控制面元数据，支持共享内存以及多节点的 Mooncake、Mori、Yuanrong 等传输实现，详见 disaggregated_inference 设计文档；
• 扩散加速：扩散 stage 可按流水线与硬件拓扑组合 CFG 并行、专家并行、HSDP、流水线并行、序列并行、张量并行与 VAE patch 并行，并可通过 Skip-Softmax、Cache-DiT、TeaCache 等后端与去噪步优化手段加速；量化与 分布式逐层卸载 则用于显存效率优化；
• 前缀缓存（Automatic Prefix Caching）：对具有公共前缀的请求复用 KV-Cache 对齐的 stage 输出与多模态张量，参见 prefix_caching 设计文档；
• 异步输出执行：异步分块（async_chunk）向前推进部分 stage 输出，异步扩散输出与 Omni 输出物化将 CPU 端载荷构建移出 AR 解码关键路径。

社区、引用与许可证

• 参与贡献：欢迎各类贡献与协作，贡献指南见 Contributing to vLLM-Omni；
• 引用：若在研究中使用了 vLLM-Omni，可引用官方论文（arXiv:2602.02204），仓库 README.md 中提供了完整的 BibTeX 条目；
• 社区交流：可在 vLLM 社区#sig-omniSlack 频道或用户论坛提问与反馈；
• 许可证：Apache License 2.0，详见仓库根目录 LICENSE 文件。

总结

vLLM-Omni 以 stage 化执行为核心抽象，将 vLLM 高效的 AR 运行时与 DiT 扩散运行时统一进一条异构流水线，覆盖文本、图像、音频、视频与动作的全模态服务场景。无论是通过Omni类做离线批处理，还是通过vllm serve --omni启动 OpenAI 兼容的在线服务，都只需指定模型名即可开始使用；而PipelineConfig/DeployConfig的分离、OmniConnector的分离式部署与全套扩散加速手段，则为生产级的多模态服务提供了可组合、可扩展的底层支撑。

【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni