vLLM-Omni Chat Completions API 实战多模态对话、vLLM 扩展参数与批量请求【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omnivLLM-Omni 通过 OpenAI 兼容的/v1/chat/completions端点统一承载对话式与多模态推理管线请求可以携带文本、图像、音频或视频输入响应则可能返回文本、音频、图像或其他模型特定输出。本文基于仓库文档 chat_completions_api.md 与对应服务端源码讲解基础请求、vLLM 扩展参数的传递方式、扩散模型走 Chat Completions 的兼容约定以及/v1/chat/completions/batch批量端点的实现细节帮助你在接入 omni 模型服务时写对请求、避开 400 错误。一、基础请求一个端点覆盖多模态对话vLLM-Omni 的 serve 进程会启动一个 OpenAI 兼容的 HTTP 服务。从 serve CLI 的说明可以看到服务端会自动识别模型类型LLM 模型通过/v1/chat/completions提供服务纯扩散模型则主要走/v1/images/generations。对于支持对话语义的模型如 Qwen3-Omni 这类 omni 模型Chat Completions 是默认入口。最基本的请求如下curl http://localhost:8091/v1/chat/completions \ -H Content-Type: application/json -d { messages: [ {role: user, content: Describe vLLM-Omni briefly.} ], modalities: [text] }几个要点modalities字段用于声明本次请求期望的输出模态。请求未显式指定时服务端会回退到该模型支持的输出模态。传入stream: true即可获得 Server-Sent Events 流式响应不传则为一次性 JSON 响应。输入媒体的消息语法、支持的输出模态以及响应 choice 的形态都依赖具体模型完整示例见 Qwen3-Omni 在线服务示例。每个服务进程只承载一个模型。如果客户端要求model字段可以查询GET /v1/models获取当前服务的模型名。源码视角路由与 modalities 校验在 api_server.py 中/v1/chat/completions路由被 omni 自定义的 handler 接管上游 vLLM 的同名路由会被移除后重新注册。处理逻辑构造Omnichathandler 并调用create_chat_completion引擎级错误EngineGenerateError、EngineDeadError会转换为 OpenAI 风格的错误 JSON 响应非流式响应直接以JSONResponse返回序列化时抑制多模态字段带来的 Pydantic 警告流式请求返回media_typetext/event-stream的StreamingResponse。modalities的校验逻辑在 serving_chat.py服务端先从引擎读取该模型声明的输出模态列表engine_client.output_modalities过滤掉None请求未提供modalities时自动使用该默认值若请求显式声明了模型不支持的模态会返回形如Unsupported output modalities ... Supported modalities: ...的 400 错误。这意味着能输出什么模态是由加载的模型与阶段配置决定的而不是端点本身。响应协议本身也在标准 OpenAI 结构上做了 omni 扩展。protocol/chat_completion.py 中的OmniChatCompletionResponse/OmniChatCompletionStreamResponse在标准 response 之外增加了metrics字段阶段级指标可配合return_stage_metrics开关返回choice 上则带有可选的audio_metadataAudioChunkMetadata用于音频分片的元数据。二、vLLM 扩展参数标准参数之外怎么传OpenAI 官方 schema 不包含top_k这类 vLLM 原生参数。vLLM-Omni 的约定是把标准 Chat 参数和 vLLM 特定参数都作为顶层字段直接放在请求 JSON 里使用 OpenAI Python SDK 时则通过extra_body关键字传入——SDK 会把extra_body的内容合并进顶层 JSON。直接 HTTPcurlcurl http://localhost:8091/v1/chat/completions \ -H Content-Type: application/json -d { messages: [{role: user, content: Write a short haiku.}], top_k: 40 }OpenAI Python SDKfrom openai import OpenAI client OpenAI(base_urlhttp://localhost:8091/v1, api_keynone) response client.chat.completions.create( modelyour-served-model, messages[{role: user, content: Write a short haiku.}], extra_body{top_k: 40}, )两条路径最终在服务端看到的是同一种顶层 JSON因此行为完全一致。这一约定也贯穿其他端点例如 images 协议定义 中 LoRA 字段的注释就明确写道镜像/v1/chat/completions的extra_body.lora约定。三、扩散模型走 Chat Completions兼容性约定与 400 冲突部分扩散管线也支持通过 Chat Completions 做图像生成与编辑modalities声明image时serving_chat.py 会从 messages 中提取文本 prompt 与参考图转成扩散引擎的采样参数。此时请求可以接受num_inference_steps、seed、height、width等扩散字段直接 HTTP放在请求顶层OpenAI SDK放在extra_body中。需要注意的兼容边界文档明确说明顶层嵌套一个字面extra_bodyJSON 对象会被接受兼容既有客户端但不建议新客户端这样做同一个参数不要出现在多个位置。服务端对重复的扩散参数会返回400错误如果任务与 Image Generation API 或 Image Edit API 匹配应优先使用这两个专用端点——它们的请求字段与响应契约更直接。源码视角重复参数为什么报 400上述多处提供同一参数即报错的行为由 diffusion_request_utils.py 中的normalize_diffusion_request_args实现。该函数会枚举参数的六个可能来源来源路径说明request.field顶层公共/注册字段request.extra_body.field嵌套 extra_body兼容形式request.extra_args顶层模型特定扩展参数推荐request.extra_params已废弃的旧命名仅告警request.extra_body.extra_args/request.extra_body.extra_params嵌套形式只要同一个 key 出现在两个不同来源如同时给了顶层seed和嵌套extra_body.seed函数会抛出ValueError: Diffusion request parameters were provided more than once: ...最终由上层转成 400 响应。此外还有两个值得注意的规范化规则cfg_scale会被自动别名到true_cfg_scale见 serving_chat.py 的_diffusion_root_field_aliasesquality字段有取值校验必须属于DIFFUSION_QUALITY_LEVELS否则同样拒绝请求。extra_params已弃用如果请求里出现服务端只会记录一次告警日志并建议使用extra_args。四、批量请求POST /v1/chat/completions/batchPOST /v1/chat/completions/batch接受与单条请求相同的共享生成字段区别在于messages是一个对话列表list of conversations响应按输入顺序为每个对话返回一个 choicecurl http://localhost:8091/v1/chat/completions/batch \ -H Content-Type: application/json -d { messages: [ [{role: user, content: Summarize vLLM in one sentence.}], [{role: user, content: Summarize vLLM-Omni in one sentence.}] ], max_tokens: 64 }明确不支持的能力流式stream、tools、beam search、n 1。源码视角批量端点如何复用单条管线批量处理实现在 batch_serving.py 的OmniOpenAIServingChatBatch.create_batch_chat_completion关键机制请求 ID 以chatcmpl-batch-base_id为前缀每条子请求分配base_id-idx-i避免与单条请求 ID 冲突逐条把messages[i]转换成标准ChatCompletionRequest并强制stream False——如果请求里带了stream: true只会打一条 warningStreaming is not supported for batched chat completions; ignoring streamTrue.而非报错所有子请求通过asyncio.gather并发提交给同一个create_chat_completion管线任一条失败返回ErrorResponse则整个批量请求返回该错误对文本与音频分属两个 choice的模型_maybe_collapse_choices会把 content choice 与 audio choice 合并为一个 choice保证输入条数与响应 choice 严格 1:1usage字段汇总所有子请求的 prompt/completion token 数。从源码结构看批量端点本质是同进程内并发重放单条 Chat Completions 管线因此单条端点支持的所有扩展参数top_k、扩散字段等在批量请求中同样可用而批量特有的限制禁流式等是在这一层显式强制的。五、模型特定示例索引完整的、带模型特定输入输出包括图像/音频输入语法的示例请参见仓库中的在线服务示例文档Qwen3-OmniQwen2.5-OmniText-to-Image (Qwen-Image)Image-to-Image (Qwen-Image-Edit, Qwen-Image-Layered)GLM-Image与 Chat Completions 相邻的端点文档音频、图像、视频等也在 docs/serving/ 下可按任务类型选择契约更直接的专用 API。六、实践清单结合文档与源码调用/v1/chat/completions时的检查要点先GET /v1/models拿到model名每个服务进程只服务一个模型用modalities显式声明输出模态声明超出模型支持范围会得到 400 且错误信息中列出支持的模态vLLM 扩展参数top_k等顶层直传或经 SDKextra_body传递两种方式等价扩散任务字段num_inference_steps、seed、height、width等只放一处同参多处提供会触发 400cfg_scale会归一为true_cfg_scale批量场景用/v1/chat/completions/batchmessages为对话列表响应 choice 与输入顺序一一对应不要依赖流式、tools、beam search 或n 1需要阶段指标时通过extra_body中的return_stage_metrics开关控制响应中的metrics字段见 serving_chat.py 的过滤逻辑。【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考