执行摘要

• 一句话：CI 排除 KV 连接器子树，消除无关步骤扩散
• 推荐动作：建议 CI/基础设施维护者精读：本 PR 展示了「用最小 diff 解决 CI 扩散」的范式，逐文件排除语义（include 命中且 exclusion 不命中）与「外科手术式排除 vs 全量 import 白名单」的取舍都值得借鉴；KV 连接器相关开发者应了解该排除规则，确保连接器改动仍由专属 Disaggregated job 覆盖。普通功能开发者可跳过。值得关注的决策：排除语义按文件而非按目录判定、以及「模拟选择 + 典型路径回归清单」的验证方法。

功能与动机

PR body 明确指出问题根因：声明 vllm/ 或 vllm/distributed/ 宽泛 source_file_dependencies 的步骤会在这些目录下任何文件变动时执行，而 KV 连接器位于 vllm/distributed/kv_transfer/，本身已有 dedicated 的 Disaggregated job 覆盖，但一次自包含的 nixl push-connector 修复（#49221）却触发了约 70 个几乎无关的 CUDA 步骤。关联 issue vllm-project/ci-infra#450 补充了同一背景：流水线生成器的前缀匹配无法把子树从宽泛 include 中剔除，因此需要新增排除操作符。作者刻意选择「外科手术式排除」而非 #42219-42223 的 import 扫描白名单方案，以最小风险直接命中扩散问题。

实现拆解

1. 上游契约先行：vllm-project/ci-infra#450 在 _source_file_dependencies_match 中实现 "!" 前缀排除语义——匹配按「每个被改动文件」进行，文件命中任一 include 且不命中任何 exclusion 才选中步骤；无 "!" 时行为逐字节不变。本 PR 依赖该操作符，语法在 ci-infra 合入前为 inert，因此必须在其后合入。
2. 批量追加排除项：对 13 个 .buildkite/test_areas/*.yaml 中所有声明 vllm/ 或 vllm/distributed/ 宽泛依赖的步骤，统一在 include 后追加一行 - "!vllm/distributed/kv_transfer/"，共 59 行纯新增、0 删除（PR body 自述 62 行，以 diff 统计为准）。覆盖套件包括：多模态（models_multimodal.yaml，11 处）、分布式（distributed.yaml，12 处，含 AMD mirror 分支）、语言模型（models_language.yaml，7 处）、入口（entrypoints.yaml，9 处）、基础模型（models_basic.yaml，3 处）、杂项（misc.yaml，6 处）、PyTorch（pytorch.yaml，5 处），以及 engine.yaml、basic_correctness.yaml、benchmarks.yaml、expert_parallelism.yaml、rust_frontend.yaml、weight_loading.yaml 各 1 处。
3. 边界语义保持：排除按文件逐条判定——同时改动连接器子树与其他路径的混合 PR 仍会触发这些步骤；而直接列出 vllm/distributed/kv_transfer/... 或 tests/v1/kv_connector/unit 的 dedicated 步骤（如 misc.yaml 中 Extract Hidden States Integration、V1 Core + KV + Metrics）不受影响，因为 include 精确匹配子树路径仍然生效，保证连接器回归覆盖不丢失。
4. 验证配套：ci-infra 侧单元测试 63 项通过；本仓库 13 个 YAML 全部可解析、pre-commit 干净；作者模拟生成器的前缀加排除匹配逻辑，用 #49221 的改动集验证步骤从约 70 降至 18（15 个 nixl 门控 Disaggregated job + 执行被改测试的 v1/kv_connector/unit 运行器），并回归验证 vllm/model_executor/*、vllm/multimodal/*、vllm/entrypoints/*、vllm/distributed/parallel_state.py 等非连接器改动仍触发对应套件，确认无过排除。

关键文件：

• .buildkite/test_areas/models_multimodal.yaml（模块 CI 配置；类别 config；类型 configuration）: 多模态矩阵是扩散重灾区之一，11 处 vllm/ 宽泛依赖全部追加排除项，是本次改动量最大的文件。
• .buildkite/test_areas/models_language.yaml（模块 CI 配置；类别 config；类型 configuration）: 语言模型套件 7 处宽泛依赖首批收窄，是 vllm/ 排除范式的代表性样本。
• .buildkite/test_areas/distributed.yaml（模块 CI 配置；类别 config；类型 configuration）: 同时覆盖 vllm/distributed/ 与 vllm/ 两种宽泛依赖（12 处，含 AMD mirror），是连接器的直接父目录，排除语义最关键。
• .buildkite/test_areas/entrypoints.yaml（模块 CI 配置；类别 config；类型 configuration）: 9 处入口集成套件（LLM、API Server、OpenAI、Responses 等）免除连接器改动触发的无关回归。
• .buildkite/test_areas/models_basic.yaml（模块 CI 配置；类别 config；类型 configuration）: 基础模型初始化与基础用例套件 3 处排除，避免连接器改动触发全量模型初始化测试。
• .buildkite/test_areas/misc.yaml（模块 CI 配置；类别 config；类型 configuration）: 6 处宽泛依赖收窄，同时文件内保留了 dedicated 的 v1/kv_connector/unit 步骤，是「排除与专属并存」边界语义的典型案例。
• .buildkite/test_areas/pytorch.yaml（模块 CI 配置；类别 config；类型 configuration）: PyTorch 相关 5 处宽泛依赖收窄，连接器改动不再触发 torch 相关套件。
• .buildkite/test_areas/engine.yaml（模块 CI 配置；类别 config；类型 configuration）: engine 套件 1 处宽泛依赖收窄，防止连接器改动触发引擎级集成测试。
• .buildkite/test_areas/basic_correctness.yaml（模块 CI 配置；类别 config；类型 configuration）: 基础正确性矩阵是 PR body 明确点名的扩散目标之一，1 处排除。
• .buildkite/test_areas/benchmarks.yaml（模块 CI 配置；类别 config；类型 configuration）: 基准测试套件 1 处收窄，连接器改动不再触发性能基准。
• .buildkite/test_areas/expert_parallelism.yaml（模块 CI 配置；类别 config；类型 configuration）: 专家并行套件 1 处收窄，保持排除规则覆盖的一致性。
• .buildkite/test_areas/rust_frontend.yaml（模块 CI 配置；类别 config；类型 configuration）: Rust 前端套件 1 处收窄，连接器改动不再触发 Rust 前端 CI。
• .buildkite/test_areas/weight_loading.yaml（模块 CI 配置；类别 config；类型 configuration）: 权重加载套件 1 处收窄，完成 13 个分区的全覆盖。

关键符号：_source_file_dependencies_match, _matches_source_dependency

评论区精华

本 PR 没有实质 review 评论：claude[bot] 因 fork 而禁用自动评审，khluu 直接 APPROVED。核心设计讨论集中在 PR body 与关联 issue vllm-project/ci-infra#450 中：一是合入顺序约束——"!" 语法在 ci-infra#450 合入前无效，必须在其后落地；二是与 #42219-42223 逐文件收窄方案的取舍——作者明确选择只排除连接器子树的低风险方案，而非需要随顶层包新增不断维护的 import 扫描白名单。

• 与逐文件收窄方案（#42219-42223）的取舍 (design): 作者选择外科手术式排除方案，khluu 无异议并批准合并；#42219-42223 由作者后续协调关联。
• 合入顺序依赖 ci-infra#450 (question): 作为明确的合入顺序约束被记录；ci-infra#450 已处于 closed 状态，前置条件满足。

风险与影响

• 风险：
  1. 前置依赖顺序风险："!" 语法在 ci-infra#450 合入前为 inert，若顺序颠倒，排除会静默失效、收益消失且无任何报错，且该语义无法在本仓库内单独测试，需跨仓库协调。
  2. 潜在过排除风险：未来若 KV 连接器代码被 vllm/ 下其他模块（如 engine、model_executor）间接引用，纯连接器改动将不再触发这些广套件（如 basic_correctness.yaml、engine.yaml），可能漏掉间接回归；当前依赖 Disaggregated job 与 tests/v1/kv_connector/unit 的覆盖，新增连接器用例需确认纳入这些专属路径。
  3. 配置漂移风险：排除项分散在 13 个 YAML 文件，后续新增宽泛 deps 步骤时容易漏加同一行，导致扩散问题在局部复现；可考虑将来在生成器中集中管理排除规则。
  4. 非风险项：纯 CI 配置变更，不涉及模型输出、精度与 serving 行为；对非连接器改动的步骤选择无任何变化（作者已对 4 类典型路径做回归验证）。
• 影响：
  1. 对 KV 连接器贡献者：单次连接器改动触发的 CI 步骤从约 70 个降至 18 个，排队与等待时间显著下降，nixl 等连接器迭代节奏加快。
  2. 对 CI 基础设施：每次连接器改动释放约 52 个 CUDA 步骤资源，缓解 GPU 队列压力，间接缩短全仓库 CI 等待。
  3. 对非连接器改动：零影响，覆盖语义完全不变，不存在静默的测试覆盖缩减。
  4. 对团队：59 行纯新增配置、13 个文件，review 成本低；但后续维护需遵守「宽泛 deps 必须同步加排除」的惯例，否则扩散问题会局部复现。
     - 风险标记：前置依赖合入顺序, 排除项分散 13 文件易漂移, 潜在间接回归漏检, 纯 CI 配置无运行时风险

关联脉络

• PR #49221 [PD][NixlPush][Bugfix] Fix blocking handshake call on writer thread: 本 PR 的直接导火索：该 nixl 连接器修复触发约 70 个无关 CUDA 步骤，作者用它作为选择模拟验证的样例（约 70 → 18 步）。
• PR #51271 [CI] Run basic fullgraph correctness on one GPU: 与本次改动共享 .buildkite/test_areas/distributed.yaml 文件，属于同一测试分区的 CI 持续演进。