ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

vLLM-Omni 快速上手指南:从离线文生图批量推理到 OpenAI 兼容在线服务

vLLM-Omni 快速上手指南:从离线文生图批量推理到 OpenAI 兼容在线服务 vLLM-Omni 快速上手指南从离线文生图批量推理到 OpenAI 兼容在线服务【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni本篇指南面向第一次接触 vLLM-Omni 的开发者介绍如何在 Linux Python 3.12 环境下完成环境安装、版本对齐并通过两条核心路径跑通端到端的文本到图像生成使用Omni同步入口进行离线批量推理以及使用vllm serve --omni启动 OpenAI 兼容 API 服务器进行在线服务。读完本文你将掌握 vLLM-Omni 的完整启动流程、Omni.generate的调用方式、/v1/images/generations端点参数细节以及遇到版本不匹配、显存不足等问题时的排查思路。前置条件开始之前请确认你的环境满足以下要求这也是 vLLM-Omni 官方文档明确支持的运行基线操作系统LinuxvLLM-Omni 当前不原生支持 Windows详见 GPU 安装页Python3.12vLLM-Omni 本身以 Python 库形式提供框架与模型的实现支持 NVIDIA CUDA、AMD ROCm、Intel XPU、MThreads MUSA 以及 NPU 等硬件平台平台级安装差异可查阅 安装指南。安装uv 虚拟环境 源码安装官方推荐使用uv管理 Python 3.12 虚拟环境然后从源码安装 vLLM-Omni。GPU 环境下的完整步骤如下uv venv --python 3.12 --seed source .venv/bin/activate # On CUDA uv pip install vllm0.29.0 --torch-backendauto # On ROCm uv pip install vllm0.29.0rocm723 --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 .说明几点uv venv --python 3.12 --seed会创建带pip/setuptools的隔离环境避免污染系统 Python。CUDA 与 ROCm 的 vLLM 安装源不同CUDA 使用--torch-backendauto自动匹配ROCm 需要从 vLLM 官方 wheel 源安装对应版本本例为0.29.0rocm723。最后一步uv pip install -e .以可编辑模式安装当前仓库改动源码即时生效便于二次开发。除源码安装外仓库还提供预构建 wheel、Docker 镜像以及从源码构建 wheel 等多种方式且针对不同后端CUDA/ROCm/XPU/MUSA/NPU给出了差异化命令详见 GPU 安装指南 与 NPU 安装指南。仓库根目录的 Dockerfile.cuda、Dockerfile.rocm 等文件也印证了多平台镜像的构建入口。版本对齐必须与上游 vLLM 保持同一主版本号这是安装环节最容易被忽视、也最容易踩坑的一点必须安装相同 major.minor 版本的 vLLM 与 vLLM-Omni否则功能可能异常。版本不对齐时导入 vLLM-Omni 会收到警告。从源码看vLLM-Omni 的入口实现vllm_omni/entrypoints/omni.py直接依赖vllm.sampling_params.RequestOutputKind等上游 API并与 vLLM 的 V1 引擎深度耦合因此跨小版本混用极易触发兼容性问题。一个典型的症状是vllm命令无法正确识别--omni参数。这通常意味着你安装了 vLLM 0.29.0而 vLLM-Omni 为0.29.0——新版本的 vLLM-Omni 不再劫持 vLLM 的入口点--omni标志需要由匹配版本的 vLLM 自身提供。解决办法是升级 vLLM 到与 vLLM-Omni 一致的版本。离线批量推理使用 Omni 入口离线推理适用于脚本、批处理与测试场景一次性提交若干 prompt等待全部完成后再统一取回结果。单 prompt 文生图from vllm_omni.entrypoints.omni import Omni if __name__ __main__: omni Omni(modelTongyi-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)这段代码的核心调用链是Omni(model...)构造同步离线推理入口。Omni继承自OmniBase见 vllm_omni/entrypoints/omni_base.py构造时会先执行omni_snapshot_download(model)完成模型获取支持本地路径直用、Hugging Face 仓库下载且可通过VLLM_USE_MODELSCOPE环境变量切换到 ModelScope 下载ModelScope 目前属于快速落地的 workaround 路径代码中留有 TODO。内部创建AsyncOmniEngine作为底层异步引擎Omni._create_engine。generate(prompt)提交请求同步阻塞直到拿到OmniRequestOutput列表outputs[0].images为生成的 PIL 图像对象列表可直接save()。批量多 prompt 文生图generate接受 prompt 列表多个独立请求并行调度from vllm_omni.entrypoints.omni import Omni if __name__ __main__: omni Omni( modelTongyi-MAI/Z-Image-Turbo, # deploy_config./deploy-config.yaml, # Optional deploy override ) 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(fp{i_prompt}-img{i_image}.jpg) print(saved to, fp{i_prompt}-img{i_image}.jpg) # saved to p0-img0.jpg # saved to p1-img0.jpg # saved to p2-img0.jpg要点说明每个 prompt 是独立的逻辑请求。对于扩散类管线多个兼容的进行中请求会由调度器与 runner 自动合批但这属于运行时优化不改变每个 prompt 一个请求的语义。deploy_config是可选参数可传入部署配置 YAML如vllm_omni/deploy/目录下各模型对应的部署文件用于覆盖阶段划分、并行度等默认设置。返回的omni_outputs与 prompts 一一对应每个prompt_output.images是该 prompt 生成的图像列表受n等参数控制因此外层循环按 prompt 编号命名、内层按图像序号命名。generate 的完整签名与进阶用法从源码vllm_omni/entrypoints/omni.py可以看到generate的完整能力def generate( self, prompts: OmniPromptType | Sequence[OmniPromptType], sampling_params_list: OmniSamplingParams | Sequence[OmniSamplingParams] | None None, *, py_generator: bool False, use_tqdm: bool | Callable[..., tqdm] True, ) - Generator[OmniRequestOutput, None, None] | list[OmniRequestOutput]:sampling_params_list按阶段stage传入采样参数在多阶段管线如 PD 分离的 prefill/decode场景下允许只给 N-1 个参数引擎会按需展开。py_generatorTrue改为惰性返回 Python 生成器逐个 yield 完成的请求输出适合边生成边消费的场景。use_tqdm默认为 True 显示 Processed prompts 进度条也可传入自定义进度回调。离线模式下LLM 阶段默认会被强制为FINAL_ONLY输出_maybe_force_final_only_for_llm_stages只有显式请求output_kindDELTA的阶段才会走流式从而保证离线批处理的简单语义。异常处理生成过程中任一步失败会记录日志、关闭引擎并重新抛出请求被中途放弃如生成器提前退出时abort()会通知引擎取消对应请求。对于扩散管线的请求级合批、按步执行step execution与流式输出控制官方有专门文档 Diffusion Execution Modes 详细介绍要点包括目标CLI 配置串行请求执行--max-num-seqs 1请求级融合批处理--max-num-seqs N单请求按步执行--step-execution --max-num-seqs 1按步连续批处理--step-execution --max-num-seqs N分块扩散输出--diffusion-streaming-output其中--request-batch-max-wait-ms可设置批处理窗口默认 0非零值以少量延迟换取更优合批且注意不要把一个 prompt 列表作为打包的单一 prompt 提交。更多离线推理示例如 Qwen2.5-Omni 的多模态对话参见 离线推理示例。在线服务OpenAI 兼容 API Server在线场景下使用vllm serve启动一个常驻的 OpenAI 兼容 HTTP 服务器其他进程通过 REST API 访问。启动服务器vllm serve Tongyi-MAI/Z-Image-Turbo --omni --port 8091--omni是启用 vLLM-Omni 多模态能力的关键标志等价于离线入口的Omni封装。一个服务器实例只托管一个模型只有该模型支持的端点才可用详见 API Server 指南。启动后可验证服务健康状态与已加载模型export VLLM_OMNI_BASE_URLhttp://localhost:8091 curl $VLLM_OMNI_BASE_URL/health curl $VLLM_OMNI_BASE_URL/v1/models | jq .若服务器带--api-key启动则请求需携带Authorization: Bearer api-key头。调用文生图端点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命令逻辑POST JSON 请求 → 返回体含 Base64 编码的 PNG → 用jq提取data[0].b64_json→base64 -d解码落盘为coffee.png。端点参数详解POST /v1/images/generations是 OpenAI DALL-E 兼容的文生图端点详见 Image Generation API参数分两类OpenAI 标准参数参数类型默认说明promptstring必填图像的文字描述modelstring服务器模型指定模型一般与服务器一致即可ninteger1生成图像数量1-10sizestring模型默认图像尺寸如1024x1024response_formatstringb64_jsonb64_json或file后者直接返回图像文件流userstringnull用户标识跟踪用vllm-omni 扩展参数参数类型默认说明negative_promptstringnull希望图像避免的内容描述num_inference_stepsinteger模型默认扩散去噪步数guidance_scalefloat模型默认无分类器引导强度典型 0.0-20.0true_cfg_scalefloat模型默认True CFG 系数模型特有不支持时可能被忽略seedintegernull随机种子用于结果复现设计原则是透传pass-throughAPI 层只做基本类型与范围校验参数直接转发给扩散管线不做模型特定的转换不支持或不适配的参数可能被模型静默忽略或由底层管线报错。因此最佳实践是先采用模型官方推荐参数再按需微调。响应格式b64_json模式{ created: 1701234567, data: [ { b64_json: base64-encoded PNG, url: null, revised_prompt: null } ] }使用 OpenAI Python SDK 客户端服务器暴露标准http://localhost:8091/v1作为 OpenAI SDK 的base_urlfrom openai import OpenAI client OpenAI(base_urlhttp://localhost:8091/v1, api_keynone) response client.images.generate( modelTongyi-MAI/Z-Image-Turbo, prompta horse jumping over a fence nearby a babbling brook, n1, size1024x1024, response_formatb64_json )注意seed、num_inference_steps、true_cfg_scale等 vLLM-Omni 扩展参数是 OpenAI SDK 不直接暴露的需要走原生 HTTP 请求如requests直传 JSON才能使用。更完整的 curl / Python / Gradio 多客户端示例见 在线文生图示例。多卡并行加速对于 Qwen-Image 等较大模型可叠加并行度参数提升吞吐对应示例见 examples/online_serving/text_to_image/README.md# Tensor Parallel需 2 卡 vllm serve Qwen/Qwen-Image --omni --port 8091 --tensor-parallel-size 2 # TP VAE Patch Parallel VAE Tiling需 2 卡 vllm serve Qwen/Qwen-Image --omni --port 8091 --tensor-parallel-size 2 --vae-patch-parallel-size 2 --vae-use-tiling # Sequence Parallelism / Ulysses-SP需 2 卡 vllm serve Qwen/Qwen-Image --omni --port 8091 --usp 2 # Ring Attention需 2 卡 vllm serve Qwen/Qwen-Image --omni --port 8091 --ring 2显存受限时可启用--vae-use-slicing --vae-use-tiling降低内存占用。常见问题与排查版本不匹配导致--omni不生效升级 vLLM 至与 vLLM-Omni 相同的 0.29.x 主版本见上文版本对齐一节。503 Diffusion engine not initialized/v1/images/generations返回该错误说明服务器不是以扩散模型启动的——检查vllm serve model --omni中的模型是否为文生图模型。400 参数格式错误size必须是WIDTHxHEIGHT格式例如1024x1024非法值如1024x会返回 400。显存不足OOM按size: 512x512→num_inference_steps: 25→n: 1的顺序逐步降低资源占用或启用 VAE slicing/tiling。功能自检仓库提供端到端测试可通过 pytest 验证图像生成接口行为测试参考 tests/entrypoints/openai_api/test_image_server.pypytest tests/entrypoints/openai_api/test_image_server.py -v小结与下一步至此你已经掌握了 vLLM-Omni 的完整入门链路环境与版本对齐 → 离线Omni.generate批量文生图 →vllm serve --omni在线服务与/v1/images/generations调用。vLLM-Omni 在同一套框架下还覆盖语音合成、音频生成、图像编辑、视频生成、实时全双工对话与机器人策略推理等任务各端点的选择与调用方式可在 API Server 指南 中按需查阅。【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表