vLLM-Omni 深度研究：
使用方法完全指南

2. 安装与入门

2.1 三种安装方式对比

推荐: 生产环境优先使用 pip install vllm-omni；开发调试使用源码安装。

2.2 系统要求

2.3 快速入门三步走

步骤 1 — 安装

pip install vllm-omni

步骤 2 — Python API 调用（离线推理）

# 创建编排器并执行推理
from vllm_omni import Omni
omni = Omni(model="Qwen/Qwen3-Omni-30B-A3B-Instruct", omni=True)
outputs = omni.generate({"prompt": "你好，请介绍一下自己"})
print(outputs)

步骤 3 — 启动在线服务

# 通过 CLI 启动 OpenAI 兼容 API 服务
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091

3. 核心 API 使用（Omni / AsyncOmni）

3.1 架构层次

三源交叉验证确认的一致架构层次：

3.2 Omni（同步编排器）vs AsyncOmni（异步编排器）

3.3 Omni.generate() 参数详解

# 函数签名
def generate(
    self,
    prompts: OmniPromptType | Sequence[OmniPromptType],   # 输入类型
    sampling_params_list: OmniSamplingParams
                         | Sequence[OmniSamplingParams]
                         | None = None,
    *,
    py_generator: bool = False,        # True=流式, False=批量
    use_tqdm: bool | Callable = True,  # 进度条
) -> Generator[OmniRequestOutput, None, None] | list[OmniRequestOutput]:

3.4 AsyncOmni.generate() 参数详解

# 函数签名
async def generate(
    self,
    prompt: OmniPromptType
            | AsyncGenerator[StreamingInput, None]
            | list[OmniPromptType],
    sampling_params: Any = None,
    request_id: str = "",
    *,
    prompt_text: str | None = None,
    lora_request: Any = None,
    tokenization_kwargs: dict[str, Any] | None = None,
    sampling_params_list: Sequence[OmniSamplingParams] | None = None,
    output_modalities: list[str] | None = None,  # 如 ["text", "audio"]
    trace_headers: Mapping[str, str] | None = None,
    priority: int = 0,
    data_parallel_rank: int | None = None,
    reasoning_ended: bool | None = None,
) -> AsyncGenerator[OmniRequestOutput, None]:

3.5 多模态输入格式

Prompt 字典结构，支持文本、图像、音频、视频的任意组合：

prompt = {
    # 文本提示（含对话模板标记）
    "prompt": "<|im_start|>system\n...<|im_end|>\n"
              "<|im_start|>user\n...<|im_end|>\n"
              "<|im_start|>assistant\n",

    # 多模态数据
    "multi_modal_data": {
        "image": pil_image,                # PIL.Image (RGB)
        "audio": (audio_signal, sr),       # Tuple[np.ndarray, int]
        "video": video_frames,             # np.ndarray
    },

    # 输出模态控制
    "modalities": ["text", "audio"],

    # 多模态处理器参数
    "mm_processor_kwargs": {
        "use_audio_in_video": True,
    },

    # 扩散模型专用：负提示词
    "negative_prompt": "...",

    # 每 prompt 模态数量限制
    "limit_mm_per_prompt": {"image": 1, "audio": 1, "video": 1},
}

3.6 输出数据结构

OmniRequestOutput 包含 17 个核心字段：

@dataclass
class OmniRequestOutput:
    request_id: str
    finished: bool
    stage_id: int | None
    final_output_type: str            # "text" | "image" | "audio" | "latents"
    request_output: RequestOutput | None    # 管道模式输出
    images: list[Image.Image]         # 扩散模式输出
    prompt: OmniPromptType | None
    latents: torch.Tensor | None
    trajectory_latents: torch.Tensor | None
    trajectory_timesteps: torch.Tensor | None
    metrics: dict[str, Any]
    stage_durations: dict[str, float]
    peak_memory_mb: float
    error: str | None

便利属性（由核心字段派生）: multimodal_output、custom_output、num_images、is_diffusion_output、is_pipeline_output。

3.7 采样参数类型

OmniDiffusionSamplingParams 参数说明

4. CLI 命令行详解

4.1 命令入口

CLI 入口位于 vllm_omni/entrypoints/cli/main.py，通过 --omni 标志触发 Omni 模式。当未检测到 --omni 时，拦截器将命令转发给标准 vLLM CLI。

vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni

子命令：serve、benchmark。

4.2 参数分类速查

基础服务参数

阶段配置参数

分布式参数

扩散模型并行参数

缓存优化参数

内存优化参数

视频模型参数

4.3 常用 CLI 命令示例

# 1. 启动文本/多模态 LLM 服务
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091

# 2. 启动文生图服务
vllm serve Qwen/Qwen-Image --omni --port 8091

# 3. 启动文生视频服务（Wan2.2）
vllm serve Wan-AI/Wan2.2-T2V-A14B-Diffusers --omni --port 8098 \
    --boundary-ratio 0.875 --flow-shift 5.0

# 4. 启动 TTS 服务
vllm-omni serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
    --deploy-config vllm_omni/deploy/qwen3_tts.yaml \
    --host 0.0.0.0 --port 8091 --gpu-memory-utilization 0.9 \
    --trust-remote-code --omni

# 5. 多 GPU 并行扩散模型
vllm serve Qwen/Qwen-Image --omni \
    --num-gpus 4 \
    --tensor-parallel-size 2 \
    --ulysses-degree 2 \
    --cfg-parallel-size 2 \
    --use-hsdp

# 6. Headless 模式（运行单个阶段）
vllm serve Qwen/Qwen2.5-Omni-7B --omni --headless --stage-id 0 \
    --omni-master-address 192.168.1.10 --omni-master-port 50051

5. OpenAI 兼容 API

5.1 完整端点列表

5.2 Chat Completions API 详解

文本对话

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-Omni-7B",
    "messages": [{"role": "user", "content": "What is 2+2?"}],
    "max_tokens": 50,
    "stream": false
  }'

多模态输入

支持 image_url、audio_url、video_url、text 四种内容类型。

{
  "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
  "messages": [
    {"role": "system", "content": [{"type": "text", "text": "You are Qwen, a virtual human..."}]},
    {"role": "user", "content": [
      {"type": "audio_url", "audio_url": {"url": "https://example.com/audio.wav"}},
      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,XXXXX"}},
      {"type": "text", "text": "What is this content?"}
    ]}
  ],
  "modalities": ["text", "audio"],
  "stream": false
}

Omni 扩展参数

5.3 图像生成 API (DALL-E 兼容)

curl 示例

curl -X POST http://localhost:8091/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a dragon laying over the spine of the Green Mountains of Vermont",
    "size": "1024x1024",
    "n": 1,
    "seed": 42,
    "num_inference_steps": 30,
    "guidance_scale": 7.5,
    "response_format": "b64_json"
  }'

参数说明

Python SDK 示例

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8091/v1", api_key="EMPTY")
response = client.images.generate(
    model="Qwen/Qwen-Image",
    prompt="A cat sitting on a windowsill",
    n=1, size="1024x1024", response_format="b64_json",
)

5.4 视频生成 API

vLLM-Omni 的 /v1/videos 端点支持异步视频生成，分为三步流程。

步骤一：提交生成请求

curl -sS -X POST "${BASE_URL}/v1/videos" \
  -F "prompt=Two anthropomorphic cats in comfy boxing gear fighting on a spotlighted stage." \
  -F "seconds=2" -F "size=832x480" -F "fps=16" \
  -F "num_inference_steps=40" -F "guidance_scale=4.0" \
  -F "boundary_ratio=0.875" -F "flow_shift=5.0" -F "seed=42"

步骤二：查询生成状态

curl -sS "${BASE_URL}/v1/videos/${video_id}"

步骤三：下载生成的视频

curl -sS -L "${BASE_URL}/v1/videos/${video_id}/content" -o output.mp4

5.5 TTS API

三种任务类型

curl 示例（CustomVoice）

curl -X POST http://localhost:8091/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello, how are you?", "voice": "vivian", "language": "English"}' \
  --output output.wav

支持格式：wav, mp3, pcm, flac, aac, opus

5.6 图像编辑 API

curl -X POST http://localhost:8000/v1/images/edits \
  -F "model=xxx" -F "image=@gift-basket.png" \
  -F "mask=@mask.png" -F "prompt='a bear wearing sportwear, holding a basketball'" \
  -F "size=1024x1024" -F "output_format=png"

5.7 流式响应处理

from openai import OpenAI
import base64

client = OpenAI(base_url="http://localhost:8091/v1", api_key="EMPTY")
response = client.chat.completions.create(
    messages=[system_msg, user_msg],
    model="Qwen/Qwen3-Omni-30B-A3B-Instruct",
    modalities=["text", "audio"],
    stream=True,
)

for chunk in response:
    for choice in chunk.choices:
        if chunk.modality == "audio":
            audio_data = base64.b64decode(choice.delta.content)
            with open("output.wav", "wb") as f:
                f.write(audio_data)
        elif chunk.modality == "text":
            print(choice.delta.content, end="")

6. 扩散模型（图像/视频/音频）

6.1 完整支持模型列表

三方来源综合：B（源码注册表）最为完整，收录 30+ Pipeline 类。A 覆盖约 20 个常用模型，C 覆盖约 25 个。

图像生成模型

视频生成模型

音频 / TTS 模型

验证结论：B（源码注册表）最为完整，收录 30+ Pipeline 类。A 覆盖约 20 个常用模型。C 覆盖约 25 个。

6.2 扩散模型离线推理

以下示例演示使用 Omni 接口进行 Qwen-Image 图像生成推理：

from vllm_omni.entrypoints.omni import Omni
from vllm_omni.inputs.data import OmniDiffusionSamplingParams
import torch

omni = Omni(model="Qwen/Qwen-Image")

outputs = omni.generate(
    {
        "prompt": "a cup of coffee on the table",
        "negative_prompt": None,
    },
    OmniDiffusionSamplingParams(
        height=1024,
        width=1024,
        generator=torch.Generator("cuda").manual_seed(42),
        true_cfg_scale=4.0,
        guidance_scale=4.0,
        num_inference_steps=50,
        num_outputs_per_prompt=1,
    ),
)

# 提取图像
images = outputs[0].request_output.images
images[0].save("coffee.png")

来源：A/B 提供完整示例，C 确认 API 可用性。

6.3 扩散模型加速组件

6.4 Cache-DiT & TeaCache 配置

Cache-DiT 配置

cache_config = {
    # DBCache 参数
    "Fn_compute_blocks": 1,
    "Bn_compute_blocks": 0,
    "max_warmup_steps": 4,
    "residual_diff_threshold": 0.24,     # 越高缓存越激进
    "max_continuous_cached_steps": 3,
    # TaylorSeer 参数
    "enable_taylorseer": False,
    "taylorseer_order": 1,
    # SCM (Step Computation Masking)
    "scm_steps_mask_policy": None,       # slow/medium/fast/ultra
    "scm_steps_policy": "dynamic",
}

TeaCache 配置

cache_config = {
    "rel_l1_thresh": 0.2,  # 累积相对 L1 距离阈值
}

来源：A 提供详细配置参数，C 提供背景说明。

7. 多阶段 LLM（Qwen2.5-Omni / Qwen3-Omni）

7.1 架构对比

7.2 三阶段推理流程

来源：A/B/C 一致。B 补充了 worker_type 细节。

7.3 完整离线推理示例

from vllm_omni.entrypoints.omni import Omni
from vllm.sampling_params import SamplingParams

# 初始化 Omni（Qwen3-Omni）
omni = Omni.from_cli_args(args, model="Qwen/Qwen3-Omni-30B-A3B-Instruct")

# 配置每阶段采样参数
thinker_sampling_params = SamplingParams(
    temperature=0.9, top_p=0.9, max_tokens=1200, seed=42,
)
talker_sampling_params = SamplingParams(
    temperature=0.9, top_k=50, max_tokens=4096, seed=42,
    detokenize=False, stop_token_ids=[2150],
)
code2wav_sampling_params = SamplingParams(
    temperature=0.0, max_tokens=4096*16, seed=42, detokenize=True,
)

sampling_params_list = [thinker_sampling_params, talker_sampling_params, code2wav_sampling_params]

# 执行生成（流式输出）
omni_generator = omni.generate(prompts, sampling_params_list, py_generator=True)

for stage_outputs in omni_generator:
    output = stage_outputs.request_output
    if stage_outputs.final_output_type == "text":
        text_output = output.outputs[0].text
        print(f"Text: {text_output}")
    elif stage_outputs.final_output_type == "audio":
        audio_tensor = output.outputs[0].multimodal_output["audio"]
        sf.write("output.wav", audio_tensor.detach().cpu().numpy(), samplerate=24000)

omni.close()

来源：A/B/C 一致，B 提供最完整的代码分析。

7.4 多模态标记格式

来源：A/B 一致。

7.5 阶段配置 YAML 结构

# qwen3_omni_moe.yaml
async_chunk: true
stages:
  - stage_id: 0
    model_stage: "thinker"
    model_arch: "Qwen3OmniMoeThinkerForConditionalGeneration"
    engine_input_source: []
    final_output: false
    worker_type: "ar"
  - stage_id: 1
    model_stage: "talker"
    model_arch: "Qwen3OmniMoeTalkerForConditionalGeneration"
    engine_input_source: [0]
    custom_process_input_func: "thinker2talker"
    final_output: false
    worker_type: "ar"
  - stage_id: 2
    model_stage: "code2wav"
    model_arch: "Qwen3OmniMoeCode2Wav"
    engine_input_source: [1]
    custom_process_input_func: "talker2code2wav"
    final_output: true
    final_output_type: "audio"
    worker_type: "generation"

来源：A/B 一致。注意 stage-configs-path 已废弃，新格式使用 deploy-config。

7.6 Async Chunk 模式

Async Chunk 让下游阶段在上游阶段完成之前开始处理（阶段级并发），从而显著减少端到端延迟：

# 单 prompt
bash run_single_prompt_async_chunk.sh

# 多 prompt 带并发控制
bash run_multiple_prompts_async_chunk.sh --max-in-flight 4

# 自定义阶段配置
python end2end_async_chunk.py --query-type use_audio --deploy-config /path/to/config.yaml

来源：A 提供最完整的说明和示例。