PR #40065: feat: support passing configuration to custom attention backends

• Repository: vllm-project/vllm
• Author: ianliuy
• State: open | merged: False
• Link: https://github.com/vllm-project/vllm/pull/40065

Description (problem / solution / changelog)

What's broken?

Custom attention backends registered via register_backend() have no way to receive configuration. The vllm.general_plugins entry points are zero-argument callables, and AttentionImpl.__init__ has a fixed constructor signature — there is no sanctioned injection point for plugin authors to pass config to their custom backends.

Workarounds like class-level attributes are fragile and not discoverable.

Ref: #40051

Who is affected?

Anyone building custom attention backends (e.g. observability tools like glassbox) that need runtime configuration. Existing built-in backends and users not passing backend_config are not affected — this is fully backward-compatible.

How did we fix it?

Added a backend_config: Any = None parameter to register_backend() in vllm/v1/attention/backends/registry.py. The value is stored in new module-level dicts (_ATTN_BACKEND_CONFIGS / _MAMBA_ATTN_BACKEND_CONFIGS) alongside the existing _ATTN_OVERRIDES.

New public API surface:

• register_backend(..., backend_config={"key": "value"}) — store config at registration time
• backend.get_config() — enum method to retrieve config (returns None if not set)
• backend.clear_config() — enum method to clear stored config
• get_backend_config(backend) — module-level function (equivalent to backend.get_config())

Usage example:

# In your plugin's entry point:
from vllm.v1.attention.backends.registry import (
    AttentionBackendEnum, register_backend
)

register_backend(
    AttentionBackendEnum.CUSTOM,
    "my.module.MyObservabilityBackend",
    backend_config={"log_level": "debug", "sample_rate": 0.1},
)

# In your backend class:
from vllm.v1.attention.backends.registry import get_backend_config, AttentionBackendEnum

class MyObservabilityBackend(AttentionBackend):
    def __init__(self, ...):
        config = get_backend_config(AttentionBackendEnum.CUSTOM)
        # config == {"log_level": "debug", "sample_rate": 0.1}

Design choices:

• Pull-based pattern (backend reads config at init time) — matches how _ATTN_OVERRIDES already works
• No changes to AttentionImpl.__init__ signature — zero disruption to existing backends
• Config is set per-process when the plugin loads — matches subprocess behavior documented in plugin docs
• Works with both decorator and direct-registration forms of register_backend()

How do we know it works?

• 5 new unit tests added to tests/test_attention_backend_registry.py:
  • test_register_backend_config_with_class_path — config via direct registration
  • test_register_backend_config_with_decorator — config via @register_backend decorator
  • test_register_mamba_backend_config — config for MambaAttentionBackendEnum
  • test_backend_config_defaults_to_none — backward compat: no config = None
  • test_backend_config_clear — clear_config() removes stored config
• All existing tests continue to pass unchanged
• ruff check and ruff format --check pass

Changes

• vllm/v1/attention/backends/registry.py: Added backend_config param, config storage dicts, get_config()/clear_config() enum methods, get_backend_config() function
• tests/test_attention_backend_registry.py: 5 new tests covering the config mechanism

Changed files

• tests/test_attention_backend_registry.py (modified, +96/-0)
• vllm/v1/attention/backends/registry.py (modified, +63/-3)