Worker selection: choosing the role worker

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

The idea#

vLLM has no register API for a worker. It reads the worker class name from parallel_config.worker_cls and imports it by name (vllm:vllm/v1/worker/worker_base.py:273-277). A plugin changes the worker by setting this field. AFD does that in its config patch.

AFD must not overwrite a worker the user chose on purpose. So the rewrite runs only when the field is still "auto". When the user passed --worker-cls, AFD keeps it and checks it later instead. The right worker also depends on the role and the platform, so AFD maps the platform's default worker to the matching AFD worker.

An everyday comparison. Think of a form field set to "auto". A helper fills it only when it is still "auto"; a value you typed is left alone, but checked for fit. The comparison stops here: AFD also swaps the model runner later, inside the worker.

The picture#

Read panel 1 top to bottom as the start-up flow. Read panel 2 as the mapping used in step 3. The violet NPU row is named here only; the GPU worker is the one this site covers in depth.

In the code#

Step 1: The config patch records whether worker_cls was "auto"#

The patched create_engine_config first records whether the user left worker_cls as "auto" (afd_plugin/compat/patches/config_validation.py:60). It keeps that flag because vLLM fills the field with the platform default while it builds the config.

    # ### PATCH START: AFD config preflight
    worker_cls_was_auto = _uses_auto_worker_value(self.worker_cls)
    is_afd_npu = _apply_afd_npu_config_patches(self)
    needs_engine_args_bypass = not is_afd_npu and _should_relax_engine_args_backend(
        self
    )
    # ### PATCH END: AFD config preflight

Step 2: Rewrite only when it was "auto"#

After the config is built, the patch rewrites the worker only when the flag is set (afd_plugin/compat/patches/config_validation.py:91-93). The rewrite reads the role from the AFD config and the platform default from the field (afd_plugin/compat/patches/config_validation.py:179-197).

def _select_afd_worker_for_auto(vllm_config: VllmConfig) -> None:
    afd_config = parse_optional_afd_config(vllm_config)
    if afd_config is None:
        return

    from vllm.platforms import current_platform

    platform_worker_qualname = vllm_config.parallel_config.worker_cls
    if not isinstance(platform_worker_qualname, str):
        raise ValueError(
            "platform worker_cls must be a qualname string before AFD automatic "
            f"selection, got {type(platform_worker_qualname).__name__}",
        )
    vllm_config.parallel_config.worker_cls = afd_worker_qualname_for_platform_default(
        afd_config.role,
        platform_worker_qualname,
        is_cuda=current_platform.is_cuda(),
        device_type=current_platform.device_type,
    )

Step 3: The platform default maps to an AFD worker#

afd_worker_qualname_for_platform_default normalizes the platform default and maps it to the AFD worker for the role (afd_plugin/validation.py:280-309). The table lists the mappings.

The names are the FQCN constants at the top of the module (afd_plugin/validation.py:26-41). A CUDA default maps by role (afd_plugin/validation.py:290-291); the standard Ascend default maps to the NPU workers (afd_plugin/validation.py:292-296). The 310P and Xlite Ascend workers are rejected (afd_plugin/validation.py:297-305).

Step 4: vLLM imports the chosen class#

Later, in the worker process, vLLM imports worker_cls by its qualified name (vllm:vllm/v1/worker/worker_base.py:273-277). By then the field holds the AFD worker, so vLLM builds the AFD worker.

Step 5: The worker swaps the model runner in init_device#

The AFD worker's init_device first checks the stack, then swaps the native model runner class for the AFD one and delegates to the native init (afd_plugin/v1/worker/attention_worker.py:60-88). The FFN worker does the same with its own runner (afd_plugin/v1/worker/ffn_worker.py:81-99).

        native_runner_cls = gpu_model_runner_v2.GPUModelRunner
        gpu_model_runner_v2.GPUModelRunner = AFDAttentionModelRunnerV2
        try:
            super().init_device()
        finally:
            gpu_model_runner_v2.GPUModelRunner = native_runner_cls
        # ### PATCH END: select and directly construct the AFD runner.

Deep dive#

What can go wrong#

• Plugin loaded too late. If the config is built before the plugin runs, worker_cls stays "auto" and the stack check raises (afd_plugin/validation.py:343-348).
• Wrong explicit worker. A --worker-cls that is not the role's AFD worker is rejected with both names (afd_plugin/validation.py:357-367).
• Unsupported platform. A platform whose default worker AFD does not know raises in the mapping (afd_plugin/validation.py:306-309).
• No V2 model runner. With the V2 model runner off (VLLM_USE_V2_MODEL_RUNNER=0) the GPU check raises (afd_plugin/validation.py:90-91).

Why it matters. The two servers must run the matching role workers. AFD picks them when the field is "auto", and refuses a wrong one, so a mismatch cannot reach the model.