--- title: GLM5服务拉起失败问题排查与解决方案：从节点缺失--headless参数导致端口冲突-官方技术文章-昇腾社区 description: 在基于vLLM Ascend的分布式推理部署中，需通过多节点协同方式拉起大模型服务，以提升推理吞吐与资源利用率。在实际部署过程中，若配置不当，可能导致服务启动失败或节点挂死。本文聚焦于在Atlas 800I A2硬件平台、HDK 25.5.0版本环境下，使用vLLM Ascend拉起GLM5模型时，主节点报错“RuntimeError：远程引擎需采用headless无头模式”的典型问题，结合实际排 keywords: GLM,服务拉起失败,问题排查与解,决方案,从节点缺失,参数导致端口,冲突,官方技术文章 url: https://www.hiascend.com/developer/techArticles/20260602-6?envFlag=1 section: (其他) --- # GLM5服务拉起失败问题排查与解决方案：从节点缺失--headless参数导致端口冲突-官方技术文章-昇腾社区 URL: https://www.hiascend.com/developer/techArticles/20260602-6?envFlag=1 描述: 在基于vLLM Ascend的分布式推理部署中，需通过多节点协同方式拉起大模型服务，以提升推理吞吐与资源利用率。在实际部署过程中，若配置不当，可能导致服务启动失败或节点挂死。本文聚焦于在Atlas 800I A2硬件平台、HDK 25.5.0版本环境下，使用vLLM Ascend拉起GLM5模型时，主节点报错“RuntimeError：远程引擎需采用headless无头模式”的典型问题，结合实际排 关键词: GLM,服务拉起失败,问题排查与解,决方案,从节点缺失,参数导致端口,冲突,官方技术文章 官方技术文章 [了解详情](https://www.hiascend.com/zh/developer/techArticles) GLM5服务拉起失败问题排查与解决方案：从节点缺失--headless参数导致端口冲突 GLM5服务拉起失败问题排查与解决方案：从节点缺失--headless参数导致端口冲突 vLLM 发表于: 2026/06/02 ## 背景概述 在基于vLLM Ascend的分布式推理部署中，需通过多节点协同方式拉起大模型服务，以提升推理吞吐与资源利用率。在实际部署过程中，若配置不当，可能导致服务启动失败或节点挂死。本文聚焦于在Atlas 800I A2硬件平台、HDK 25.5.0版本环境下，使用vLLM Ascend拉起GLM5模型时，主节点报错“RuntimeError：远程引擎需采用headless无头模式”的典型问题，结合实际排查过程，提供清晰的根因分析与修复方案。 ## 问题现象 在执行服务拉起脚本后，主节点界面卡死于“正在启动”状态，日志中持续输出以下错误信息： ```c 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 [了解详情](https://docs.vllm.ai/en/latest/cli/serve/?h=headless) ## 解决方案 在从节点的启动脚本中，添加`--headless`参数，确保从节点仅运行推理引擎，不启动API服务。 ```c vllm serve ... ... --headless\ ... ``` ✅建议：在多节点部署中，主节点可保留API服务（不加`--headless`），而所有从节点必须添加`--headless`参数，以实现职责分离与资源优化。 ## 总结 在分布式推理服务部署中，合理配置`--headless`参数是保障服务稳定拉起的关键。本案例表明，即使仅缺失一个参数，也可能导致整个服务链路中断。建议在部署脚本中统一规范参数使用，避免因配置遗漏引发线上故障。 本页内容