vLLM-Omni 快速上手指南：安装、离线推理、OpenAI 兼容服务全流程

9次阅读

没有评论

一、什么是 vLLM-Omni

vLLM 是伯克利团队推出的高性能大模型推理引擎，主打高吞吐、低延迟；vLLM-Omni 是 vLLM 官方推出的多模态扩展组件，专门面向文生图、视觉生成类模型提供统一推理与服务能力。

核心能力：

离线批量文生图推理，Python 原生调用；
一键拉起 OpenAI 兼容接口服务，直接用 curl/SDK 调用绘图；
原生支持扩散类图像生成模型，统一调度管线；
兼容 CUDA / ROCm 双硬件生态，适配主流开源图像大模型（如 Tongyi-MAI/Z-Image-Turbo）。

版本硬性要求：vLLM 主包与 vLLM-Omni 必须保持完全相同主、次版本（示例文档配套 v0.23.0），版本错位会触发警告、--omni 参数失效、推理异常。

二、前置环境要求

仅支持 Linux 系统，依赖固定版本 Python：

OS：Linux（Windows / Mac 暂不官方支持）
Python：3.12
硬件：NVIDIA CUDA GPU 或 AMD ROCm 显卡
工具：uv（轻量虚拟环境与包管理工具）

三、完整安装步骤（源码编译安装）

1. 创建隔离虚拟环境

bash

运行

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

2. 安装对应版本 vLLM

方案 A：NVIDIA CUDA 用户

bash

运行

uv pip install vllm==0.23.0 --torch-backend=auto

方案 B：AMD ROCm 用户

bash

运行

uv pip install vllm==0.23.0+rocm722 --extra-index-url https://wheels.vllm.ai/rocm/0.23.0/rocm722

3. 拉取 vllm-omni 源码并本地安装

bash

运行

# 克隆官方仓库
git clone https://github.com/vllm-project/vllm-omni.git
cd vllm-omni
# 本地可编辑模式安装
uv pip install -e .

关键避坑提醒

vLLM 与 vllm-omni 版本必须一致（均为 0.23.0），否则命令行 vllm serve --omni 识别失败；
低于 v0.23.0 的旧版 vLLM 不再劫持入口，旧兼容方案失效，直接升级即可解决参数报错；
安装全程保持虚拟环境激活，避免全局包冲突。

四、离线批量文生图推理（Python API）

示例 1：单提示词生成图片

python

运行

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)
    # 提取图像并保存
    img = outputs[0].request_output.images[0]
    img.save("coffee.png")

示例 2：多提示批量生成

python

运行

from vllm_omni.entrypoints.omni import Omni

if __name__ == "__main__":
    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",
    ]
    outputs = omni.generate(prompts)
    # 循环保存所有图片
    for idx, res in enumerate(outputs):
        imgs = res.request_output.images
        for img_idx, img in enumerate(imgs):
            save_path = f"p{idx}-img{img_idx}.jpg"
            img.save(save_path)
            print(f"图片已保存：{save_path}")

批量推理注意事项

默认扩散管线 max_num_seqs=1，输入列表会自动切分为单条请求，批量性能提升有限；
若模型原生支持批量输入，可通过 stage_configs_path 指定 yaml 配置，修改 engine_args.max_num_seqs 调大并发；
批量仅用于接口兼容，生产大批量绘图建议拆分任务队列。

五、在线服务：OpenAI 兼容 API 部署

1. 启动 Omni 图像服务

bash

运行

# 开启omni多模态服务，监听8091端口
vllm serve Tongyi-MAI/Z-Image-Turbo --omni --port 8091

2. curl 调用接口生成图片

bash

运行

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
}
}' | jq -r '.choices[0].message.content[0].image_url.url' | cut -d',' -f2 | base64 -d > coffee.png

调用逻辑说明：