vllm-omni serve 命令详解基于 Stage 的分进程部署与参数配置指南【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni导读vllm serve是 vLLM-Omni 启动本地 OpenAI 兼容 API 服务器的核心入口本文聚焦其Stage-based CLI基于阶段的分进程部署范式通过--stage-id、--headless、--omni-master-address/port等参数将一个多模态流水线如 Qwen3-Omni 的多阶段 LLM 模型、Qwen-Image 等扩散模型拆分为跨进程、跨 GPU、甚至跨主机的独立阶段运行。读完本文你将掌握 Orchestrator Worker 的分阶段启动命令、--deploy-config自定义部署 YAML 的使用方法以及--stage-overrides与逐阶段直传参数的取舍原则并理解这些行为背后的 CLI 源码实现。一、Stage-based CLI为什么需要分进程启动多模态 Omni 模型如 Qwen3-Omni 的 thinker/talker 多阶段结构通常包含多个流水线阶段StageOrchestrator编排器与 API Server、推理 Worker 等。默认的单进程模式将全部阶段塞进一个操作系统进程而stage-based CLI 面向的是需要将每个流水线阶段隔离到独立进程的部署场景例如跨越多个操作系统进程进程级隔离便于独立扩缩容与故障恢复分别绑定不同的 GPU 设备分布在多台分布式主机上。其典型拓扑为Stage 0 运行 Orchestrator 与 API Server对外提供 HTTP 服务其余 Stage 以headless无头Worker形式挂载到 Stage 0 的 master 地址上参与计算。二、快速开始Stage 0 与 Headless Worker 的启动命令以下命令展示了一个常见设备映射Stage 0 独占 GPU 0Worker 阶段通过CUDA_VISIBLE_DEVICES绑定 GPU 1。2.1 初始化 Stage 0Orchestrator 与 API ServerCUDA_VISIBLE_DEVICES0 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \ --port 8091 \ --stage-id 0 \ --omni-master-address 127.0.0.1 \ --omni-master-port 26000参数说明参数作用--omni启用 vLLM-Omni 的 Omni 配置组是走 Omni 流水线的前提--port 8091对外 HTTP API 服务端口--stage-id 0声明本进程承载 Stage 0编排与 API Server 角色--omni-master-address 127.0.0.1masterStage 0的绑定地址--omni-master-port 26000master 的 RPC/协调端口headless Worker 通过它与 Stage 0 通信2.2 初始化 Headless Worker 阶段Stage 1CUDA_VISIBLE_DEVICES1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \ --stage-id 1 \ --headless \ --omni-master-address 127.0.0.1 \ --omni-master-port 26000与 Stage 0 相比Worker 进程多了一个--headless标志它不启动对外 API 服务只作为计算阶段向 master 注册并回报心跳heartbeat。注意--stage-id与--omni-master-address、--omni-master-port三者必须同时出现。在 serve.py 的校验逻辑中只要设置了--stage-id而未同时提供 master 地址与端口CLI 会直接抛出ValueError: --stage-id requires both --omni-master-address and --omni-master-port to be set。2.3 使用自定义部署 YAML对于已迁移模型vLLM-Omni 内置了部署配置位于 vllm_omni/deploy/ 目录如qwen3_omni_moe_thinking.yaml、bagel_single_stage.yaml等。默认情况下直接执行vllm serve MODEL --omni ...就会自动加载对应的内置部署配置仅当你需要覆盖默认配置时才需要追加--deploy-configvllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --deploy-config /path/to/override.yaml也就是说--deploy-config的角色是按需覆盖而非必填项。以内置的 qwen3_omni_moe_thinking.yaml 为例一个部署 YAML 的核心结构如下pipeline: qwen3_omni_moe_thinker_only # 指定流水线拓扑 distributed_executor_backend: mp enable_prefix_caching: true stages: - stage_id: 0 devices: 0,1 max_num_seqs: 1 gpu_memory_utilization: 0.9 enforce_eager: true async_scheduling: false tensor_parallel_size: 2 default_sampling_params: temperature: 0.4 top_p: 0.9 top_k: 1 max_tokens: 2048 seed: 42 repetition_penalty: 1.05其中pipeline字段决定整个流水线的拓扑例如 thinker-only 单阶段拓扑stages列表按stage_id声明每个阶段绑定哪些设备、张量并行大小与默认采样参数。自定义覆盖 YAML 时只需遵循同样的 schema 即可。三、--stage-overrides与逐阶段直传参数两种调参范式在标准执行范式单进程承载多个 Stage中使用--stage-overrides通过一个 JSON 字符串对指定 Stage 应用专属配置。但在stage-based CLI范式下每个进程严格只封装单个 Stage因此官方推荐直接通过离散的命令行参数为对应阶段调参而不是拼装复杂的--stage-overridesJSON 串。例如对于下面这条复合配置写法vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 \ --stage-overrides {1: {gpu_memory_utilization: 0.5}}stage-based CLI 允许你直接初始化 Stage 1 并显式传入参数CUDA_VISIBLE_DEVICES1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \ --stage-id 1 \ --headless \ --gpu-memory-utilization 0.5 \ --omni-master-address 127.0.0.1 \ --omni-master-port 26000两种写法的效果等价但后者语义更清晰、更易维护也避免了手工转义 JSON 的出错风险。从源码看--stage-overrides的解析定义在 serve.py其值必须是一个 JSON 对象结构约定为{stage_id: {采样/配置参数: value, ...}, ...}见 serve.py 的帮助文本解析失败或非对象类型时会抛出ArgumentTypeError。而在 headless 流程 run_headless 中stage_overrides与deploy_config会从参数中弹出先完成整个部署配置的解析resolve再通过stage_by_id(stage_id)精确锁定本进程对应的阶段配置——这就是每个进程严格封装单个 Stage的底层依据。四、JSON CLI 参数支持vllm serve --omni的多数参数同时支持 JSON 形式传入在 YAML 部署配置或编程式启动中尤为常用。参数解析层基于TrackingArgumentParser见 serve.py 的导入与使用它会在用户键入每个标志时将其解析到真实的dest字段并记录显式传入的键explicit_keys从而支持CLI 直传参数优先于默认配置的合并语义。例如--model-config、--stage-overrides、--deploy-config等复合参数均接受 JSON 对象字符串其中--stage-overrides必须为{stage_id: {...}}形式的 JSON 对象--model-config等其他配置组参数同样要求合法的 JSON 对象类型校验见_json_objectserve.py。查询某个配置组下所有可用参数可直接使用帮助分组检索vllm serve MODEL --omni --helpOmniConfig # 查看 Omni 配置组 vllm serve MODEL --omni --helpall # 查看全部可用参数五、headless 模式的关键约束与校验结合 serve.py 的validate与run_headless实现headless Worker 模式有以下硬性约束使用前务必核对--stage-id必填headless 模式下若未指定--stage-id会抛出ValueError: --stage-id is required in headless modeserve.py。master 地址与端口必填headless 模式要求同时提供--omni-master-address与--omni-master-portserve.py。worker 后端必须为多进程headless 模式要求worker_backendmulti_process否则直接拒绝启动serve.py。--omni-replica-address仅限 headless该参数只在run_headless()中被读取若在非 headless 模式下传入会被拒绝serve.py。数据并行规模参数当本地数据并行规模omni_dp_size_local ! 1时必须显式声明--stage-id单一运行时场景或改用--omni-dp-size-localheadless / 多运行时场景否则校验不通过serve.py。headless 进程的设备分配由get_headless_replica_devices依据stage_cfg计算随后按模型类型分流扩散模型走launch_headless_diffusion_replicasLLM 模型走launch_headless_llm_replicasserve.py并会注入 KV Connector 配置以打通跨阶段 KV 传输inject_omni_kv_connector_config。六、vllm serve --omni的整体入口行为CLI 入口由OmniServeCommand承载serve.py其核心行为包括自动识别模型类型LLM 模型经/v1/chat/completions端点服务扩散模型经/v1/images/generations端点服务用户无需手工指定见 serve.py 的命令描述。模型参数优先级若在 CLI 中以位置参数传入模型名model_tag它会覆盖--model配置值。分支执行设置--headless时进入run_headless(args)分进程执行否则通过uvloop.run(omni_run_server(args))启动完整的 Omni API Serverserve.py。总结Stage-based CLI 是 vLLM-Omni 面向生产级多阶段部署提供的核心范式以--stage-id界定进程角色、以--headless区分 API Server 与纯计算 Worker、以--omni-master-address/port建立阶段间协调通道。配合vllm_omni/deploy/下的内置 YAML 与--deploy-config覆盖机制可以在不改动模型代码的前提下将单条vllm serve ... --omni命令拆解为多进程、多 GPU、多主机的可编排部署而--stage-overrides与逐阶段直传参数两种调参范式则让 GPU 显存等资源配置既可以在统一 YAML 中声明也可以按阶段精细覆盖兼顾了简洁性与灵活性。进一步阅读serve 命令 CLI 文档、部署配置目录、CLI 入口实现、在线服务示例。【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考