vLLM CI 故障排查完全指南:从判断失败原因到定位根因的完整工作流
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 标签)。从模板源码看,除了必填的“失败测试全名”和“失败描述”外,还要求提供两部分信息:
- 基础信息勾选框:是否为 Flaky test、是否可在本地复现、是否由外部库(如
transformers)引入; - 失败历史:测试从何时开始失败?模板中明确建议三种定位手段——
- 用 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
从源码看,清洗包含三类替换:
- 去掉行首的 ISO 时间戳(形如
[2024-01-01T00:00:00Z]); - 去掉 Buildkite 的内联时间戳标记(
ESC _bk;t=<ms> BEL序列); - 去掉 ANSI 颜色/光标控制序列。
清洗后的日志更适合粘贴进 issue 或做 diff 对比——这也呼应了第一部分“附上日志”时为什么日志里不应有时间和颜色噪声。
3.3 快速复制:配合 wl-clipboard
文档建议安装 wl-clipboard(开源工具,用于无头 Linux 环境的剪贴板操作),快速复制日志末尾的关键段落:
tail -525 ci_build.log | wl-copy
四、调查失败:二分定位首个出问题的构建
调查一个 CI 失败的标准步骤(对应文档 “Investigating a CI Test Failure” 一节):
- 打开 Buildkite 的 main 分支构建列表,按时间倒序浏览;
- 二分(bisect) 找到第一个出现该问题的构建;
- 把你的调查结论补充到对应 GitHub issue 中;
- 如果找到了强候选 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 稳定性工作。