​作者​：昇腾实战派
​知识地图​：https://blog.csdn.net/Lumos_Lovegood/article/details/161601003

背景概述

本文聚焦于在Atlas 800I A2、HDK 25.5.0版本环境下，使用vLLM Ascend拉起GLM5模型时，主节点报错RuntimeError: Remote engine 1 must use --headless unless in external or hybrid dp lb mode的典型问题，结合实际排查过程，提供清晰的根因分析与修复方案。

问题现象

在执行服务拉起脚本后，主节点界面卡死于拉起页面，日志中输出以下错误信息：

RuntimeError: Remote engine 1 must use --headless unless in external or hybrid dp lb mode [ERROR] 2026-03-27-14:19:37 (PID:997, Device:-1, RankID:-1) ERR99999 UNKNOWN applicaiton exception

该错误表明：远程引擎（从节点）未以无头模式运行，导致与主节点的API服务发生端口冲突。

根因分析

参考GLM5部署文档从节点的拉起脚本，通过与失败运行的从节点启动脚本对比，发现关键差异在于：从节点关键参数**headless**缺失。

--headless

• 官方定义：--headless参数用于指示vLLM以"无头模式"运行。在该模式下，节点仅启动核心推理引擎（Engine Core）进程，而不启动API服务器（如OpenAI兼容的RESTful API）。这适用于分布式部署中的从节点（非主节点），使其专注于计算任务，由主节点或外部负载均衡器处理请求分发；避免从节点不必要的API服务开销，提升资源利用率。
• 缺失影响：从节点尝试启动API服务并尝试绑定与主节点相同的服务端口，导致与主节点的API服务冲突与端口冲突
• 参考链接：https://docs.vllm.ai/en/latest/cli/serve/?h=headless

解决方案

在从节点的启动脚本中，添加--headless参数。

vllm serve ...
...
--headless\
...

总结

在分布式推理服务部署中，合理配置参数是保障服务稳定拉起的关键。本案例表明，即使仅缺失一个参数，也可能导致整个服务链路中断。建议在部署脚本中统一规范参数使用，避免因配置遗漏引发线上故障。