The plugin entry point: register_afd

Code version: afd-plugin @ 7452d52 · 2026-10-27 · vLLM @ ced6857

The idea#

afd-plugin is one general plugin. vLLM calls its entry function, register_afd, once in each process that loads plugins. The function installs the compat patches, the routing strategy, the DBO custom op and the model wrappers. Then it stops; it runs no model.

Two facts shape the function. First, vLLM calls it in many processes, and the vLLM guard resets in each new process. So the function must be idempotent: safe to run again with no change. Second, the package must import on a machine with no vLLM, so local tests work. The function handles both with guards and early returns.

An everyday comparison. Think of a self-check at the start of a shift. You run it once; if someone runs it again, it sees the ticks and stops. The comparison stops here: each new process starts with an empty checklist, so the plugin runs the whole check again.

The picture#

Read panel 1 as the two guards: one in vLLM, one in the plugin. Read panel 2 as the three checks at the top of the function. The version check warns and continues; the other two return.

In the code#

Step 1: Two guards make it idempotent#

vLLM keeps a module flag, plugins_loaded, so load_general_plugins runs the plugins at most once per process (vllm:vllm/plugins/__init__.py:82-85). The plugin adds its own flag, _registered. A second call to register_afd in the same process returns at once (afd_plugin/__init__.py:150-153).

    global _registered
    if _registered:
        _logger.debug("AFD plugin: register_afd() already completed")
        return

Step 2: Import safety without vLLM#

The function returns early when vLLM is not importable. It sets _registered first, so a later call does not retry (afd_plugin/__init__.py:157-160). So importing afd_plugin stays safe on a machine with no vLLM.

    if importlib.util.find_spec("vllm") is None:
        _logger.debug("AFD plugin: vLLM not found, skipping runtime registration")
        _registered = True
        return

Step 3: The version gate warns, it does not stop#

The function checks the vLLM version with strict=False. A mismatch gives a warning, not an error (afd_plugin/__init__.py:162-165). The helper raises only when strict is true; otherwise it calls warnings.warn (afd_plugin/compat/vllm.py:38-50).

def assert_vllm_version_supported(*, strict: bool = True) -> None:
    installed_version = get_installed_vllm_version()
    if is_vllm_version_supported(installed_version):
        return

    message = (
        "AFD plugin currently supports exactly vLLM "
        f"{TARGET_VLLM_VERSION}; installed vLLM version is "
        f"{installed_version or 'not installed'}"
    )
    if strict:
        raise RuntimeError(message)
    warnings.warn(message, RuntimeWarning, stacklevel=2)

Step 4: What it registers, and in which order#

After the checks, the function runs these steps in order. Each is one or a few lines; the afd_plugin/__init__.py: the plugin entry module page reads them line by line.

1. Import the four patch modules. Importing a patch module applies it (afd_plugin/__init__.py:172-176).
2. Register the AFD routing strategy (afd_plugin/__init__.py:183-187).
3. Register the DBO yield custom op (afd_plugin/__init__.py:189-192).
4. NPU only: apply the Ascend config patch, when the device type is "npu" (afd_plugin/__init__.py:202-209).
5. Register each model under its AFD<arch> name (afd_plugin/__init__.py:211-214).
6. Set _registered = True (afd_plugin/__init__.py:216).

Step 5: Which steps are wrapped in try/except#

Three steps swallow their own errors; three do not. A wrapped step logs at debug and lets the rest go on. An unwrapped step lets its error propagate and stop the process.

Deep dive#

What can go wrong#

• Wrong vLLM version. The explicit check only warns (afd_plugin/compat/vllm.py:48-50). The patches then skip install, so AFD does not activate even though the process keeps running (afd_plugin/compat/patches/config_validation.py:235-261).
• A failing patch import. The four patch imports are wrapped, so a failure is logged and the rest continue (afd_plugin/__init__.py:172-181). A missing patch can leave the stack half-installed.
• A failing routing or model step. These are not wrapped, so their error stops the process (afd_plugin/__init__.py:183-187, afd_plugin/__init__.py:211-214).

Why it matters. AFD is installed only by this function. A warning that the version does not match is the one sign that the patches did not install and AFD is off.