vLLM Main2main Interface Analyzer

用静态分析回答一个具体问题：当 vLLM 从 old commit 升级到 new commit 时，固定版本的 vllm-ascend 是否会新增接口或 import break？

工具从下游源码动态发现依赖，不依赖手工维护的接口清单。它分析 monkey patch、继承与 MRO、override、direct import、精确 direct call、Triton kernel[grid](...) 调用，以及一部分可静态证明的返回协议变化。整个过程不会 import vLLM 或 vllm-ascend，也不需要 GPU/NPU。

Project status: alpha. 结果适合作为升级适配和 CI 的高信号输入，不等价于运行时测试。分析无法证明时会 fail closed，输出 review 或 analysis_unresolved，不会猜测成 break。

适合什么场景

• main2main 升级分析：用当前 vllm-ascend main，对比一段完整的 vLLM old → new 区间。
• 上游 PR CI：用 PR base/head 判断这个 PR 是否新引入下游可执行 break。
• 当前契约体检：不做区间归因，只检查当前 vLLM 与 vllm-ascend 的精确调用/返回契约。
• 依赖映射生成：输出带源码证据的 JSONL，供审计、二次处理或 golden mapping 对比。

当前支持范围

关系/契约	能力
Monkey patch	赋值 patch、字面量 setattr、函数内 patch、别名解析；目标删除会保留为风险证据
Inheritance / MRO	解析上下游组合 C3 MRO；MRO 不完整时不猜测
Override	验证实际 override owner，比较替换签名，并展开可证明的下游二级/多级子类影响
Direct import	检测模块、符号删除/移动及可证明的绑定变化
Direct call	将下游调用实参与 old/new 上游签名绑定，识别新增必需参数、删参、目标删除等
Triton launch	精确识别带 vllm.triton_utils.triton.jit 的 kernel[grid](...) 调用
Return protocol	覆盖固定/可变 tuple、解包/索引等窄规则，以及透明 return super().same_method(...)
Optional parameters	默认保留为 review；只有同时证明上游传参与分派路径时才提升为可执行修改项

更精确的边界和已知限制见 能力与边界。

5 分钟开始

1. 准备环境

要求：Python 3.11+、Git，以及三个本地目录：本工具、vLLM、vllm-ascend。

git clone https://github.com/zhao-stack/vllm-main2main-interface-analyzer.git
cd vllm-main2main-interface-analyzer
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

git clone https://github.com/vllm-project/vllm.git ../vllm
git clone https://github.com/vllm-project/vllm-ascend.git ../vllm-ascend

Windows PowerShell 激活虚拟环境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

2. 确认分析节点

vllm 必须已经 fetch 到 old/new，且工作区 HEAD 必须正好是 new。vllm-ascend 可以固定在任意待验证 commit，但命令必须显式传入它的 HEAD，防止无意中分析错版本。

git -C ../vllm fetch origin
git -C ../vllm checkout <VLLM_NEW_SHA>
git -C ../vllm-ascend checkout <ASCEND_SHA>
git -C ../vllm-ascend rev-parse HEAD

3. 运行完整 main2main 分析

vllm-main2main analyze-range \
  --vllm-root ../vllm \
  --ascend-root ../vllm-ascend \
  --old <VLLM_OLD_SHA> \
  --new <VLLM_NEW_SHA> \
  --expect-ascend-sha <ASCEND_SHA> \
  --scenario main2main \
  --profile exact-contracts \
  --fail-on introduced \
  --output-dir reports/main2main

不安装包也可以在仓库根目录运行：

python -m tools.vllm_interface_contracts analyze-range ...

报告目录包含：

• main2main-range-report.md：给人阅读的完整结论；
• main2main-introduced-breaks.csv：本区间新引入、建议修改下游的结果；
• main2main-all-findings.csv：包括 review、preexisting 和 unresolved；
• main2main-range-report.json：完整机器可读证据和版本元数据。

先看 introduced-breaks.csv，再回到 JSON/源码确认。不要把 review 直接当成真实 break。

上游 PR CI 模式

上游 PR 只关心这个 PR 新引入的直接影响，使用较窄的 vllm-interface 场景：

vllm-main2main analyze-range \
  --vllm-root ../vllm \
  --ascend-root ../vllm-ascend \
  --old <PR_BASE_SHA> \
  --new <PR_HEAD_SHA> \
  --expect-ascend-sha <PINNED_ASCEND_SHA> \
  --scenario vllm-interface \
  --fail-on introduced \
  --output-dir reports/pr

这个场景分析 override、direct import 和精确 direct call；继承/MRO 仅作为 override 解析前置条件，monkey patch 和 generator review 有意不进入 PR 门禁。输出文件适合直接用作 CI Annotation 和 Artifacts。完整示例见 CI 集成。

其他命令

检查当前两个 HEAD 的实时契约：

vllm-main2main validate \
  --vllm-root ../vllm \
  --ascend-root ../vllm-ascend \
  --expect-ascend-sha <ASCEND_SHA> \
  --scenario main2main \
  --output reports/current-validation.json

只生成当前源码对的关系映射：

vllm-main2main generate \
  --vllm-root ../vllm \
  --ascend-root ../vllm-ascend \
  --expect-vllm-sha <VLLM_SHA> \
  --expect-ascend-sha <ASCEND_SHA> \
  --output reports/interface-boundaries.jsonl \
  --unresolved-output reports/interface-boundaries.unresolved.jsonl \
  --report reports/interface-boundaries.report.json

所有用法、外部 package、退出码和 Windows/Linux 示例见 完整使用手册。AI Agent 应先读 AGENTS.md 和 AI 分析手册。

设计原则

• Consumer first：先从下游发现“它依赖什么”，再分别去 old/new 上游解析。上游 new 删除了方法时，依赖不会因为 new 索引缺失而静默消失。
• Exact evidence：只在导入、绑定、MRO、签名和调用形态可证明时给出高置信度结论。
• Range attribution：区分 introduced_break、preexisting 与 analysis_unresolved，避免把历史问题归因给当前升级。
• Reproducible inputs：报告记录所有 SHA、引擎版本、场景和耗时；--expect-*-sha 防止分析节点漂移。
• No runtime import：基于 Python AST 和 Git snapshot，不执行被分析项目代码。

架构说明见 ARCHITECTURE.md，规则演进与验证记录见 ENGINE_HISTORY.md。

开发与验证

python -m pip install -e ".[dev]"
ruff check tools tests
pytest

项目采用 Apache-2.0 许可证。部分初始实现从 vllm-project/vllm-ascend 的接口契约分析工作中提取并继续维护，原始版权声明保留在源码中；见 NOTICE。