插件系统¶

vLLM Intel® Gaudi® 硬件插件使用标准插件架构将 Intel® Gaudi® AI 加速器与 vLLM 集成。本文档将解释插件系统的实现方式。

插件实现¶

vLLM Intel® Gaudi® 硬件插件系统在不修改核心代码库的情况下扩展了 vLLM 的功能。它使用 Python 的标准入口点机制进行插件发现和注册。有关插件系统的通用信息，请参阅 vLLM 插件系统文档。

该插件包含两个互补的组件，它们通过 setup.py 文件中的 Python 入口点机制进行注册：平台插件和通用插件。这种注册结构支持 Intel® Gaudi® 硬件的平台集成和自定义操作支持。

entry_points={
    "vllm.platform_plugins": ["hpu = vllm_gaudi:register"],
    "vllm.general_plugins": ["hpu_custom_ops = vllm_gaudi:register_ops"],
}

平台插件¶

平台插件为 Intel® Gaudi® 加速器提供核心硬件集成。它负责初始化和管理设备、分配和管理内存资源、应用平台特定配置以及选择合适的注意力后端。该插件在 Python 入口点定义中，包含以下元素：

组 vllm.platform_plugins：将入口点标识为用于硬件集成的平台插件，使 vLLM 能够自动检测到它。
名称 hpu：为 vLLM 标识 Intel® Gaudi® 硬件。
值 vllm_gaudi:register：指向 vllm_gaudi 包中的 register 函数。该函数配置并返回平台类。

在 vllm_gaudi/__init__.py 中定义的 register() 函数执行平台初始化，以配置 Intel® Gaudi® 的 torch 编译设置，并返回完全限定类名 "vllm_gaudi.platform.HpuPlatform"。

from vllm_gaudi.platform import HpuPlatform

def register():
    """Register the HPU platform"""
    HpuPlatform.set_torch_compile()
    return "vllm_gaudi.platform.HpuPlatform"

在 vllm_gaudi/platform.py 中定义的 set_torch_compile() 方法配置 Intel® Gaudi® 的 PyTorch 编译行为。

@classmethod
def set_torch_compile(cls) -> None:
    # Disable weight sharing for HPU
    os.environ['PT_HPU_WEIGHT_SHARING'] = '0'

    is_lazy = htorch.utils.internal.is_lazy()
    if is_lazy:
        # Lazy backend does not support torch.compile
        torch._dynamo.config.disable = True
        # Enable lazy collectives for multi-HPU inference
        os.environ['PT_HPU_ENABLE_LAZY_COLLECTIVES'] = 'true'
    elif os.environ.get('RUNTIME_SCALE_PATCHING') is None:
        # Enable runtime scale patching for eager mode
        os.environ['RUNTIME_SCALE_PATCHING'] = '1'

此设置确保：

根据是否激活了惰性执行或即时执行模式进行正确配置。
通过惰性集合（lazy collectives）支持多 HPU 推理。
Intel® Gaudi® 后端的正确 torch.compile 行为。

通用插件¶

通用插件为 Intel® Gaudi® 加速器注册自定义操作。它负责实现自定义内核、支持量化以及提供优化算子。该插件由以下元素组成：

组 vllm.general_plugins：将入口点标识为提供平台集成之外的附加功能的通用插件。
名称 hpu_custom_ops：标识 Intel® Gaudi® HPU 硬件自定义选项。
值 vllm_gaudi:register_ops：指向注册自定义 HPU 操作的 register_ops 函数。

在 vllm_gaudi/__init__.py 中定义的 register_ops() 函数注册所有 Intel® Gaudi® 特定的自定义操作。

def register_ops():
    """Register custom operations for the HPU platform"""
    import vllm_gaudi.v1.sample.hpu_rejection_sampler  # noqa: F401
    import vllm_gaudi.distributed.kv_transfer.kv_connector.v1.hpu_nixl_connector  # noqa: F401
    import vllm_gaudi.ops.hpu_fused_moe  # noqa: F401
    import vllm_gaudi.ops.hpu_layernorm  # noqa: F401
    import vllm_gaudi.ops.hpu_lora  # noqa: F401
    import vllm_gaudi.ops.hpu_rotary_embedding  # noqa: F401
    import vllm_gaudi.ops.hpu_compressed_tensors  # noqa: F401
    import vllm_gaudi.ops.hpu_fp8  # noqa: F401
    import vllm_gaudi.ops.hpu_gptq  # noqa: F401
    import vllm_gaudi.ops.hpu_awq  # noqa: F401
    import vllm_gaudi.ops.hpu_multihead_attn  # noqa: F401

这些自定义操作被导入（而非调用），以便与 vLLM 的操作注册表进行注册，从而可以在推理管道中跨使用。

插件发现和加载¶

vLLM 启动时，会执行以下步骤：

扫描平台插件以发现所有 vllm.platform_plugins 入口点。
执行每个插件的 register() 函数。
根据硬件和注册结果选择合适的平台。
发现并加载所有 vllm.general_plugins 入口点。
使用所有已注册的自定义操作来初始化选定的平台。

vLLM 可能会生成多个进程，例如在执行张量并行分布式推理时。插件注册机制可确保：

每个进程独立发现和加载平台插件和通用插件。
注册函数在每个工作进程中执行。
平台特定配置（如 set_torch_compile()）在每个进程中应用。
自定义操作在需要它们的每个进程中注册。

验证插件安装¶

安装 vLLM Intel® Gaudi® 硬件插件后，请验证两个插件是否已正确注册。

from importlib.metadata import entry_points

# List all vLLM platform plugins
platform_plugins = entry_points(group='vllm.platform_plugins')
for plugin in platform_plugins:
    print(f"Platform Plugin - name: {plugin.name}, value: {plugin.value}")

# List all vLLM general plugins
general_plugins = entry_points(group='vllm.general_plugins')
for plugin in general_plugins:
    print(f"General Plugin - name: {plugin.name}, value: {plugin.value}")

预期输出

Platform Plugin - name: hpu, value: vllm_gaudi:register
General Plugin - name: hpu_custom_ops, value: vllm_gaudi:register_ops

您可以通过运行以下命令来验证 vLLM 已选择哪个平台：

from vllm.platforms import current_platform
print(f"Current platform: {current_platform}")

如果检测到 Intel® Gaudi® 硬件且插件正常工作，输出应显示 HPU 平台。

参考¶

有关更多信息，请参阅：