v1/worker: the attention worker and runner

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

Purpose#

These three files add the connector and control plane to the attention side without rewriting native vLLM. The concept behind them is on The attention runtime: a seam over Model Runner V2; this page maps the files.

Where it sits#

Who calls it#

The AFD config patch rewrites worker_cls to AFDAttentionWorker when the role is attention (afd_plugin/validation.py:280-291). vLLM then builds this worker like any other. The worker builds the runner inside init_device.

What it calls#

The worker delegates device setup to native Worker.init_device, which local-imports and builds GPUModelRunner (vllm:vllm/v1/worker/gpu_worker.py:469-482). The runner builds the connector through the factory (afd_plugin/connectors/factory.py:49-68) and reads the model wrapper.

Key classes and functions#

Walk through the main methods#

AFDAttentionWorker.init_device: swap the runner class#

vLLM 0.30.0 builds its runner from a module symbol inside Worker.init_device, with no injection hook. The worker replaces that symbol for the native construction window, then restores it (afd_plugin/v1/worker/attention_worker.py:60-90).

        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.

        torch.accelerator.empty_cache()

1. Line 82. Save the native runner class.
2. Line 83. Point the module symbol at AFDAttentionModelRunnerV2.
3. Line 85. Native init_device local-imports and builds the runner, now the AFD class.
4. Lines 86-87. Restore the native class in a finally, so the patch is scoped to the window.

Before the swap, the worker asserts the AFD stack and validates the V2 config (afd_plugin/v1/worker/attention_worker.py:64-73).

execute_model: scope the context, then delegate#

The runner adds nothing to the forward itself. It opens the AFD context and calls super (afd_plugin/v1/worker/attention_model_runner_v2.py:580-595).

        # ### PATCH START: scope AFD metadata provider/replay and profiler step.
        step_afd_gpu_profiler(self.prof)
        with _use_afd_execution_context(
            self,
            int(scheduler_output.total_num_scheduled_tokens),
        ):
            return super().execute_model(
                scheduler_output,
                intermediate_tensors,
                dummy_run=dummy_run,
                skip_attn_for_dummy_run=skip_attn_for_dummy_run,
                is_profile=is_profile,
                context_len=context_len,
                valid_dummy_state_slots=valid_dummy_state_slots,
            )
        # ### PATCH END: scope AFD metadata provider/replay and profiler step.

send_dp_metadata: publish one control payload#

The mixin builds one payload with the per-stage DP metadata and the graph flags, updates the connector state, then sends (afd_plugin/v1/worker/attention_metadata.py:75-116).

        payload = AFDControlPayload(
            dp_metadata_list=dp_metadata_list,
            is_graph_capturing=is_graph_capturing,
            is_warmup=is_warmup,
            is_graph_replaying=is_graph_replaying,
            is_profile=self._afd_is_profile,
        )
        self.connector.control_plane.update_state_from_dp_metadata(payload)
        self.connector.control_plane.send_dp_metadata_list(payload)

1. Lines 108-114. Build the AFDControlPayload with the DP metadata and the warm-up/capture/replay flags.
2. Line 115. update_state_from_dp_metadata pre-allocates the wire buffers.
3. Line 116. send_dp_metadata_list sends on the designated sender ranks.

Deep dive#

Related concepts#

• The attention runtime: a seam over Model Runner V2 — the seam and the two publish paths.
• The control plane: DP metadata once per step — the DP-metadata path.
• v1/worker: the FFN worker and runner — the FFN side.
• model_executor/models/deepseek_v2.py: the DeepSeek wrapper — the model split the runner drives.