vllm-ascend 与 vllm 的关系

一句话总结：vllm-ascend 是 vllm 的硬件插件（out-of-tree platform plugin），通过 Python entry_points 机制注入，覆盖 GPU 相关的算子/调度/通信层，复用 vllm 的 API 服务、模型定义、请求管理等上层逻辑。

各模块的职责分工

三大集成机制

1. Entry Point 注册（主要机制）

setup.py 声明了入口点：

1
2

"vllm.platform_plugins": ["ascend = vllm_ascend:register"]
"vllm.general_plugins": ["ascend_kv_connector = ...", "ascend_model_loader = ...", ...]

vllm 启动时通过 importlib.metadata.entry_points() 自动发现，调用 register() 返回 "vllm_ascend.platform.NPUPlatform"，实例化为 current_platform。之后所有设备相关行为都通过 NPUPlatform 的方法覆盖路由到 vllm-ascend 的实现。

2. 配置字符串覆盖

NPUPlatform.check_and_update_config() 设置关键类路径：

• parallel_config.worker_cls = "vllm_ascend.worker.worker.NPUWorker"
• scheduler_config.scheduler_cls = "vllm_ascend.core.scheduler_dynamic_batch.SchedulerDynamicBatch"（可选）
• Attention backend、communicator、graph wrapper 等同理

vllm 通过 resolve_obj_by_qualname() 动态导入这些类。

3. Monkey-Patch（补充机制）

对于 vllm 没有提供插桩接口的地方（特定模型的 forward、triton ops、分布式 ops 等），vllm-ascend 通过 patch/ 目录的猴子补丁修改：

• patch/platform/：启动时全局应用（29个文件）
• patch/worker/：每个 worker 初始化时应用（25+个文件）

启动流程

1
2
3
4
5
6
7
8
9
10

用户: vllm serve <model>
  → vllm CLI (entrypoints/cli/main.py)
    → 加载 general_plugins (注册 KV connector、model loader 等)
    → 访问 current_platform → 触发平台发现 → 实例化 NPUPlatform
    → 构建 VllmConfig → NPUPlatform.check_and_update_config()
      → 设置 worker_cls、attn_backend、scheduler_cls 等
    → Executor 创建 WorkerWrapperBase
      → 动态导入 NPUWorker → 初始化 torch.npu 设备
        → 创建 NPUModelRunner → 执行模型推理
    → 启动 uvicorn HTTP 服务 (OpenAI API)

如何学习这两个代码库

第一步：理解 vllm 的核心流程（建议按以下顺序）

1. API 层：vllm/entrypoints/openai/api_server.py — 看请求怎么进来的
2. Engine 层：vllm/v1/engine/ — AsyncLLM 如何协调 scheduler 和 executor
3. Scheduler：vllm/v1/core/sched/scheduler.py — 请求排队、prefill/decode 调度、KV cache 管理
4. Executor：vllm/v1/executor/ — 如何创建和管理 worker 进程
5. Worker：vllm/v1/worker/gpu_worker.py + gpu_model_runner.py — 模型加载和执行
6. Platform 抽象：vllm/platforms/interface.py — 理解 Platform 基类的所有方法

第二步：理解 vllm-ascend 的注入点

1. vllm_ascend/__init__.py — register() 函数，入口
2. vllm_ascend/platform.py — 最重要的文件，NPUPlatform 的每个方法都是一个注入点，看它改了什么配置
3. vllm_ascend/worker/worker.py — NPUWorker，对比 GPUWorker 看差异
4. vllm_ascend/worker/model_runner_v1.py — NPUModelRunner，对比 GPUModelRunner
5. vllm_ascend/ops/ — 算子替换，这是性能关键
6. vllm_ascend/patch/ — 最后看，理解哪些地方不得不 monkey-patch

第三步：对比阅读法

对于每个模块，先读 vllm 的 GPU 版本，再读 vllm-ascend 的 NPU 版本，关注：

• 哪些方法是直接覆盖的（override）
• 哪些是通过配置字符串替换的
• 哪些是通过 monkey-patch 修改的
• 这三种方式中，配置字符串 > 方法覆盖 > monkey-patch，优先级递减

关键文件速查：