背景概述

在基于vLLM Ascend的分布式推理部署中，需通过多节点协同方式拉起大模型服务，以提升推理吞吐与资源利用率。在实际部署过程中，若配置不当，可能导致服务启动失败或节点挂死。本文聚焦于在Atlas 800I A2硬件平台、HDK 25.5.0版本环境下，使用vLLM Ascend拉起GLM5模型时，主节点报错“RuntimeError：远程引擎需采用headless无头模式”的典型问题，结合实际排查过程，提供清晰的根因分析与修复方案。

问题现象

在执行服务拉起脚本后，主节点界面卡死于“正在启动”状态，日志中持续输出以下错误信息：

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官方（https://docs.vllm.ai/projects/ascend/en/latest/tutorials/models/GLM5.html）拉起文档的从节点脚本与失败运行的从节点启动脚本，发现关键差异在于：从节点关键参数headless缺失。

--headless:

官方定义：

--headless参数用于指示vLLM以"无头模式"运行。在该模式下，节点仅启动核心推理引擎（Engine Core）进程，而不启动API服务器（如OpenAI兼容的RESTful API）。这适用于分布式部署中的从节点（非主节点），使其专注于计算任务，由主节点或外部负载均衡器处理请求分发；避免从节点不必要的API服务开销，提升资源利用率。

缺失后果：

从节点在未启用--headless的情况下，会尝试启动独立的API服务，并绑定与主节点相同的默认服务端口（如8000）。当多个节点同时尝试绑定同一端口时，引发端口冲突，导致主节点无法正常建立通信通道，最终服务拉起失败。

参考链接：https://docs.vllm.ai/en/latest/cli/serve/?h=headless

解决方案

在从节点的启动脚本中，添加--headless参数，确保从节点仅运行推理引擎，不启动API服务。

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

✅ 建议：在多节点部署中，主节点可保留API服务（不加--headless），而所有从节点必须添加--headless参数，以实现职责分离与资源优化。

总结

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