vLLM Ascend补丁说明

vLLM Ascend补丁说明#

vLLM Ascend 是 vLLM 的一个平台插件。由于 vLLM 与 vLLM Ascend 的发布周期存在差异，且存在硬件限制，我们需要对 vLLM 的部分代码进行补丁，以使其与 vLLM Ascend 兼容。

在 vLLM Ascend 代码中，我们提供了一个补丁模块 vllm_ascend/patch 以应对 vLLM 的变更。

基本原则#

我们必须明确，补丁并非实现 vLLM Ascend 兼容性的最佳方案，它只是一个临时解决方案。最佳途径是将修改贡献至 vLLM 项目，使其原生支持 vLLM Ascend。在 vLLM Ascend 中，我们遵循以下补丁策略基本原则：

  1. 少即是多。除非当前别无他法，否则请勿使用补丁。

  2. 一旦添加补丁，必须说明未来移除该补丁的计划。

  3. 随时欢迎清理补丁代码。

工作机制#

在 vllm_ascend/patch 目录中，可看到如下代码结构：

vllm_ascend
├── patch
│   ├── platform
│   │   ├── patch_xxx.py
│   ├── worker
│   │   ├── patch_yyy.py
└───────────

  • platform：此目录下的补丁代码用于修补 vLLM 主进程中的代码。vLLM 初始化时，会由 vllm_ascend/platform::NPUPlatform::pre_register_and_update 在极早期调用。

    • 对于在线模式，vLLM 进程在解析命令行参数时，会于 vllm/vllm/engine/arg_utils.py::AsyncEngineArgs.add_cli_args 处调用平台补丁。

    • 对于离线模式，vLLM 进程在解析输入参数时，会于 vllm/vllm/engine/arg_utils.py::EngineArgs.create_engine_config 处调用平台补丁。

  • worker：此目录中的补丁代码用于修补 vLLM worker 进程中的代码。vLLM worker 进程初始化时，由 vllm_ascend/worker/worker::NPUWorker::__init__ 调用。

    • 无论在线还是离线模式，vLLM 引擎核心进程在初始化 worker 进程时，都会在 vllm/vllm/worker/worker_base.py::WorkerWrapperBase.init_worker 处调用 worker 补丁。

如何编写补丁#

编写补丁前，应遵循上述原则，力求修改最少的代码。若确有必要，可在 platform 或 worker 目录中进行补丁。以下以修补 vLLM 中 distributed 模块为例。

  1. 确定需要修补的 vLLM 版本。例如，经分析后，我们决定同时为 vLLM 的 0.10.0 版本和 main 分支编写补丁。

  2. 确定需要修补的进程。例如，此处 distributed 模块属于 vLLM 主进程，因此应选择 platform 目录。

  3. 在正确的文件夹中创建补丁文件。文件应命名为 patch_{模块名}.py。本例中为 vllm_ascend/patch/platform/patch_distributed.py。

  4. 在新文件中编写补丁代码。示例如下：

    import vllm

def patch_destroy_model_parallel():
    # your patch code
    ...

vllm.distributed.parallel_state.destroy_model_parallel = patch_destroy_model_parallel

  5. 在 __init__.py 中导入补丁文件。此例中，需将 import vllm_ascend.patch.platform.patch_distributed 添加至 vllm_ascend/patch/platform/__init__.py。

  6. 在 vllm_ascend/patch/__init__.py 中添加补丁描述。描述格式如下：

    # ** File: <The patch file name> **
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#   1. `<The target patch module in vLLM>`
#    Why:
#       <Describe the reason why we need to patch>
#    How：
#       <Describe the way to patch>
#    Related PR (if no, explain why):
#       <Add a link to the related PR in vLLM. If there is no related PR, explain why>
#    Future Plan:
#       <Describe the future plan to remove the patch>

  7. 添加单元测试与端到端（E2E）测试。vLLM Ascend 中新增的任何代码均应包含单元测试和 E2E 测试。更多详情请参阅测试指南。

限制条件#

  1. 在 V1 引擎中，vLLM 会启动三类进程：主进程、EngineCore 进程和 Worker 进程。目前 vLLM Ascend 默认仅支持为主进程和 Worker 进程的代码打补丁。若需为 EngineCore 进程中的代码打补丁，则需在设置阶段对整个 EngineCore 进程进行修补。完整代码位于 vllm.v1.engine.core 中。请完整重写 EngineCoreProc 和 DPEngineCoreProc。

  2. 如果您运行的是经过编辑的 vLLM 代码，vLLM 的版本可能会被自动更改。例如，若您基于 v0.9.n 版本运行了编辑后的 vLLM，vLLM 版本可能会变为 v0.9.nxxx。此时，vLLM Ascend 中针对 v0.9.n 的补丁将无法正常工作，因为 vLLM Ascend 无法准确识别您正在使用的 vLLM 版本。这种情况下，您可以通过设置环境变量 VLLM_VERSION 来明确指定所使用的 vLLM 版本，随后针对 v0.10.0 的补丁即可生效。