# PR #49129 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[CI][NIXL] Isolate concurrent engine internal ports
- 合并时间：2026-07-21 11:28
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/49129

---

# 执行摘要

- 一句话：隔离 NIXL 并发引擎内部端口冲突
- 推荐动作：该 PR 是典型的 CI 稳定性修复，值得快速合并。可后续关注是否按建议将 `VLLM_PORT` 替换为 CLI 参数 `--port` 以统一风格。

# 功能与动机

AMD CI 构建运行（https://buildkite.com/vllm/amd-ci/builds/11018）显示第四组 NIXL 配置（并发 prefill 和 decoder）均选择内部端口 43991，导致 EADDRINUSE 错误和 1200 秒启动超时。分析确认此前无相关代码变更，仅为随机端口选择的竞态问题。

# 实现拆解

1. 在 `run_accuracy_test.sh` 的配置区定义三个环境变量：`PREFILLER_INTERNAL_PORT_BASE`（默认 20000）、`DECODER_INTERNAL_PORT_BASE`（默认 30000）、`INTERNAL_PORT_STRIDE`（默认 100），用于控制端口窗口。
2. 在 prefill 实例启动循环中，计算 `INTERNAL_PORT=$((PREFILLER_INTERNAL_PORT_BASE + i * INTERNAL_PORT_STRIDE))`，并将 `VLLM_PORT=$INTERNAL_PORT` 注入到启动命令的环境变量中。
3. 在 decoder 实例启动循环中，类似地计算端口，但只在非 DP（`DP_EP` 为空）时设置 `DECODER_INTERNAL_PORT_ENV` 并注入 `VLLM_PORT`；DP decoder 保留原有内部端口选择，因为其 EngineCores 运行在同一服务器进程内，不应冲突。
4. 仅修改测试脚本，无源码或配置变更。

关键文件：
- `tests/v1/kv_connector/nixl_integration/run_accuracy_test.sh`（模块 测试脚本；类别 test；类型 test-coverage）: 唯一变更文件，引入预定义内部端口窗口，解决并发引擎端口冲突。

关键符号：run_tests_for_model

## 关键源码片段

### `tests/v1/kv_connector/nixl_integration/run_accuracy_test.sh`

唯一变更文件，引入预定义内部端口窗口，解决并发引擎端口冲突。

```bash
# 在配置段新增：为并发引擎指定独立内部端口窗口
PREFILLER_INTERNAL_PORT_BASE=${PREFILLER_INTERNAL_PORT_BASE:-20000}
DECODER_INTERNAL_PORT_BASE=${DECODER_INTERNAL_PORT_BASE:-30000}
INTERNAL_PORT_STRIDE=${INTERNAL_PORT_STRIDE:-100}

# Prefill 实例循环中：
INTERNAL_PORT=$((PREFILLER_INTERNAL_PORT_BASE + i * INTERNAL_PORT_STRIDE))
# 注入到环境变量
BASE_CMD="... VLLM_PORT=$INTERNAL_PORT ..."

# Decoder 实例循环中（仅非 DP 时设置）：
INTERNAL_PORT=$((DECODER_INTERNAL_PORT_BASE + i * INTERNAL_PORT_STRIDE))
DECODER_INTERNAL_PORT_ENV=
if [[ -z "${DP_EP:-}" ]]; then
  DECODER_INTERNAL_PORT_ENV="VLLM_PORT=$INTERNAL_PORT"
fi
BASE_CMD="... $DECODER_INTERNAL_PORT_ENV ..."

```

# 评论区精华

NickLucche 在审核中建议优先使用 CLI 参数 `--port` 而非环境变量 `VLLM_PORT`，因为团队倾向于标准化 CLI 参数。但作者未就该建议进行回复或修改。

- 使用 CLI 参数还是环境变量 (design): 作者未回应，直接合并。后续可考虑改用 `--port` 参数。

# 风险与影响

- 风险：风险较低：变更仅限于测试脚本（`run_accuracy_test.sh`），未影响生产代码。端口基址和步长可通过环境变量覆盖，默认值留有充足间隔（10000 端口差距），基本不可能冲突。DP decoder 保留原有行为，无回归风险。
- 影响：影响范围限于 AMD CI 中 NIXL 集成测试的并发启动稳定性。直接修复了偶发的 EADDRINUSE 超时问题，预期 CI 构建成功率提升。对其他测试或生产部署无影响。
- 风险标记：测试脚本变更 , 无生产代码影响

# 关联脉络

- PR #46570 NIXL port selection change ( 推测 ): PR body 提及该端点的 PR#46570 与此无关，但可能涉及 NIXL 端口选择逻辑。