vLLM CI 故障排查完全指南:从判断失败原因到定位根因的完整工作流

原创2026-09-06 14:07:561,868 阅读
文章标签:推理引擎模型推理服务人工智能大模型深度学习模型量化模型优化本地部署多模态

vLLM CI 故障排查完全指南:从判断失败原因到定位根因的完整工作流

当你的 PR 在 vLLM 的 CI 中失败,但你认为失败与自己的改动无关时,如何系统性地判断原因、抓取和清洗日志、复现 flaky 测试、定位引入失败的 PR,并把结果沉淀为可追踪的 issue?本文基于仓库文档 CI Failures 展开,结合 ci-fetch-log.sh、ci-clean-log.sh、rerun-test.sh 三个官方脚本的源码实现,以及 issue 模板 450-ci-failure.yml,完整讲解 vLLM 项目处理 CI 测试失败的标准流程。读完本文,你可以独立完成一次从“PR 红了”到“根因 PR 被锁定并修复”的闭环操作。

一、先判断:失败到底是不是你的 PR 引起的

CI 失败的第一反应应该是查证,而不是盲目改代码。vLLM 维护着一个专门的 CI Failures Dashboard(GitHub Projects 面板),用于登记当前 main 分支上已知的失败测试:

  • 如果你的失败已在面板中列出:大概率与你的 PR 无关。此时欢迎顺带帮忙修复,并:
    • 在对应 issue 中留下新出现该失败的实例链接(补充证据);
    • 用 👍 表情标记受影响的次数,帮助维护者判断严重程度。
  • 如果面板中没有记录你的失败:应当提交一个新的 issue 报告它。

这一步的意义在于:vLLM 的 CI 规模很大,main 上常存在他人引入的已知失败。先对表再动手,可以避免在他人引入的问题上浪费调试时间。

二、如何报告一次 CI 失败:Issue 规范与模板

报告一个新的 CI 失败需要遵循固定格式,便于面板归类和检索:

标题格式:

[CI Failure]: failing-test-job - regex/matching/failing:test

即“失败步骤名 - 匹配该失败的正则/测试名”。

Environment 字段:说明该失败在当前 main 分支上仍然复现,并附上 commit:

Still failing on main as of commit abcdef123

描述中列出失败的测试,每条一行,附上失败说明:

FAILED failing/test.py:failing_test1 - Failure description
FAILED failing/test.py:failing_test2 - Failure description
FAILED failing/test.py:failing_test3 - Failure description

附上日志,建议使用可折叠区块避免污染正文:

<details>
<summary>Logs:</summary>

ERROR 05-20 03:26:38 [dump_input.py:68] Dumping input data
--- Logging error ---
Traceback (most recent call last):
  File "/usr/local/lib/python3.12/dist-packages/vllm/v1/engine/core.py", line 203, in execute_model
    return self.model_executor.execute_model(scheduler_output)
...
FAILED failing/test.py:failing_test1 - Failure description
</details>

仓库中对应的 issue 模板是 450-ci-failure.yml(标题自动带 [CI Failure]: 前缀,并自动打上 ci-failure 标签)。从模板源码看,除了必填的“失败测试全名”和“失败描述”外,还要求提供两部分信息:

  1. 基础信息勾选框:是否为 Flaky test、是否可在本地复现、是否由外部库(如 transformers)引入;
  2. 失败历史:测试从何时开始失败?模板中明确建议三种定位手段——
    • 用 Buildkite Test Suites 分析页找到首次失败的构建并本地复现;
    • 本地运行 git bisect;
    • 对疑似 PR 在 main 上手动解锁 Buildkite 步骤验证(仅限授权用户)。

此外模板还提供了 CC List 字段,通常应 @ 导致测试失败的那个 PR 的作者——这与“找到强候选 PR 后在 issue 中提及并 ping 相关贡献者”的流程相呼应。

三、日志抓取与清洗:官方脚本详解

vLLM 的 CI 日志是公开的,无需登录 Buildkite。仓库提供了两个配套脚本,位于 .buildkite/scripts/ 下。

3.1 ci-fetch-log.sh:按 PR / 构建 / 单个任务拉取日志

ci-fetch-log.sh 把每个日志保存为 ci-<build>-<job-name>.log,并自动剥离时间戳与 ANSI 转义码。三种典型用法:

# 拉取某个 PR 最新构建中所有失败任务的日志
# (省略 <PR> 时取当前分支对应的 PR)
.buildkite/scripts/ci-fetch-log.sh --pr <PR>

# 拉取某次构建中所有失败任务的日志
# --soft 额外包含 soft-failed 任务;--all 拉取全部已完成任务
.buildkite/scripts/ci-fetch-log.sh "https://buildkite.com/vllm/ci/builds/<N>"

# 只拉单个任务:`gh pr checks` 风格的 URL(#<job_uuid>)
# 与 Web UI 风格 URL(?sid=<uuid>)都支持;
# 第二个参数传 "-" 则流式输出到 stdout
.buildkite/scripts/ci-fetch-log.sh "https://buildkite.com/vllm/ci/builds/<N>#<job_uuid>"

结合脚本源码可以看到几个值得了解的行为细节:

  • --pr 模式的实现:脚本调用 gh pr checks 获取该 PR 所有检查的 Buildkite URL,取编号最大的构建(即最新一次)。源码中特别注释了“gh pr checks 在检查失败时返回非零退出码,这正是期望的情况”,因此对退出码做了容错处理;
  • URL 双格式兼容:#<job_uuid> 是 gh pr checks 输出的形式,?sid=<uuid> 是 Buildkite 页面 URL 的形式;源码中说明 sid 实际上是 step uuid,脚本会先拉取构建的任务列表(/data/jobs 端点返回 JSON),再用 sid 匹配出对应的 job id 才去下载;
  • 作用域过滤:默认只抓“硬失败”任务(passed is False 且非 soft-failed);若存在被跳过的 soft-failed 任务,会在 stderr 提示数量并建议使用 --soft;
  • 重试任务防重名:重试任务与原始任务同名,脚本会在文件名冲突时附加 job uuid 前缀来消歧;
  • 幂等与强制重抓:已存在的日志文件默认保留不覆盖,设置 CI_FETCH_LOG_FORCE=1 环境变量可强制重新拉取;
  • 每抓完一个任务,脚本以 <文件>\t<任务名> 的形式输出一行,方便在 shell 中管道处理后续分析。

3.2 ci-clean-log.sh:清洗已下载的日志

如果手头已有一个原始日志文件,可用 ci-clean-log.sh 原地清洗:

./ci-clean-log.sh ci.log

从源码看,清洗包含三类替换:

  1. 去掉行首的 ISO 时间戳(形如 [2024-01-01T00:00:00Z]);
  2. 去掉 Buildkite 的内联时间戳标记(ESC _bk;t=<ms> BEL 序列);
  3. 去掉 ANSI 颜色/光标控制序列。

清洗后的日志更适合粘贴进 issue 或做 diff 对比——这也呼应了第一部分“附上日志”时为什么日志里不应有时间和颜色噪声。

3.3 快速复制:配合 wl-clipboard

文档建议安装 wl-clipboard(开源工具,用于无头 Linux 环境的剪贴板操作),快速复制日志末尾的关键段落:

tail -525 ci_build.log | wl-copy

四、调查失败:二分定位首个出问题的构建

调查一个 CI 失败的标准步骤(对应文档 “Investigating a CI Test Failure” 一节):

  1. 打开 Buildkite 的 main 分支构建列表,按时间倒序浏览;
  2. 二分(bisect) 找到第一个出现该问题的构建;
  3. 把你的调查结论补充到对应 GitHub issue 中;
  4. 如果找到了强候选 PR,在 issue 中提及并 ping 相关贡献者。

配合 issue 模板中的“失败历史”要求,这里给出可操作的二分路径:

  • 粗定位:先看 Buildkite Test Suites 分析页(按可靠性排序),确认该测试的失败起始时间点,缩小 bisect 区间;
  • 精定位:本地 git bisect,区间两端分别是“最后绿色 commit”和“第一个红色 commit”,对区间内 commit 反复运行目标测试;
  • 验证:锁定候选 PR 后,在 issue 的 CC List 中 @ 其作者。

五、复现 flaky 失败:用循环反复运行

CI 失败可能是 flaky 的(间歇性失败)。文档建议使用 bash 循环反复运行目标测试,仓库提供了现成脚本 rerun-test.sh:

./rerun-test.sh tests/v1/engine/test_engine_core_client.py::test_kv_cache_events[True-tcp]

脚本示例中的测试真实存在于 tests/v1/engine/test_engine_core_client.py,参数化标签 [True-tcp] 对应 KV cache events 在不同配置下的用例。从脚本源码看,其逻辑是:

while pytest -sv "$TEST"; do
    COUNT=$((COUNT + 1))
    echo "RUN NUMBER ${COUNT}"
done

即持续运行直到某次失败为止,每轮打印运行次数。这正好与“flaky 测试只有连续跑 N 次后偶发失败才暴露”的场景匹配:脚本帮你把“跑很多次”这件事自动化,你在它停下来那一刻就拿到了失败现场(配合 -sv 的详细输出便于定位断言行)。对于确定稳定的测试,记得手动 Ctrl-C 终止循环。

六、提交修复 PR 的收尾规范

当你提交一个用于修复 CI 失败的 PR 时:

  • 在 PR 描述中关联 issue:写入 Closes #12345,合并后自动关闭对应 CI Failure issue;
  • 给 PR 打上 ci-failure 标签:issue 模板会自动给 issue 打该标签,PR 也应保持一致,便于在 CI Failures 面板中追踪“已报告 → 修复中 → 已关闭”的全生命周期。

七、日常 Triage:每日巡检 main 分支的测试健康度

文档 “Daily Triage” 一节给出的日常巡检方法:

使用 Buildkite Analytics 的 2 天视图(Test Suites 分析页),目标是:

  • 识别 main 分支上最近新出现的测试失败;
  • 排除 PR 上正常的测试失败(那些属于提交者自己的问题,不属于 main 的退化);
  • (可选)忽略可靠性已为 0% 的测试——它们通常已被单独跟踪。

巡检结果要与 CI Failures Dashboard 做交叉比对:新出现的失败若不在面板中,就按第二节的规范开 issue;已在面板中的失败,补充实例证据即可。

八、参考资源汇总

资源 仓库路径 用途
CI 故障处理指南(本文主体) docs/contributing/ci/failures.md 失败判断、报告、调查的完整流程
日志抓取脚本 .buildkite/scripts/ci-fetch-log.sh 按 PR/构建/单任务拉取公开日志
日志清洗脚本 .buildkite/scripts/ci-clean-log.sh 去除时间戳与 ANSI 码
循环复现脚本 .buildkite/scripts/rerun-test.sh 反复运行直至 flaky 失败复现
CI 失败 issue 模板 .github/ISSUE_TEMPLATE/450-ci-failure.yml 报告格式、历史定位建议与 CC 规范
同目录其他 CI 文档 docs/contributing/ci/ 如 nightly 构建、PyTorch 版本更新等
CI 流水线配置 .buildkite/test-pipeline.yaml 了解 CI 步骤与任务划分

以上流程的适用前提:你使用 vLLM 当前仓库的 .buildkite/scripts/ 下的脚本(依赖 bash、curl、python3;--pr 模式额外依赖 gh CLI 并已登录 GitHub)。整个体系的核心思想是:先对表(Dashboard)再行动、日志留证、循环复现、二分定位、issue 闭环——这套方法不依赖特定硬件环境,任何贡献者都可以在纯软件层面参与 CI 稳定性工作。

登录后查看全文
vllm