[3/N][Attention] Move AttentionMetadata-related code from utils.py to backend.py

[MatthewBonanni]

Purpose

Step 3 of #31919. Moves chunks of code from utils.py to backend.py (unchanged) and updates imports accordingly. The following objects are moved:

• CommonAttentionMetadata
• AttentionMetadataBuilder
• AttentionCGSupport

Test Plan

CI (run all tests)

Test Result

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.
• (Optional) Release notes update. If your change is user facing, please update the release notes draft in the Google Doc.

---

Note

Consolidates attention metadata types into vllm.v1.attention.backend for clearer ownership and reuse.

• Moves CommonAttentionMetadata, AttentionMetadataBuilder, and AttentionCGSupport from backends/utils.py to backend.py (definitions unchanged)
• Updates imports across attention backends, layers, worker code, spec-decode, and tests to reference vllm.v1.attention.backend
• Removes the duplicated definitions from backends/utils.py; retains other utilities there
• No functional behavior changes expected; CI covers broad backend paths

^{Written by Cursor Bugbot for commit 9d6dca7. This will update automatically on new commits. Configure here.}

---

Note

Centralizes attention metadata definitions for clearer ownership and reuse.

• Moves CommonAttentionMetadata, AttentionMetadataBuilder, and AttentionCGSupport to v1/attention/backend.py (definitions unchanged)
• Updates imports across attention backends, model layers, worker/runtime code, spec-decode, and tests to reference v1/attention/backend
• Removes duplicated definitions from v1/attention/backends/utils.py; retains other utilities there
• No functional behavior changes expected

^{Written by Cursor Bugbot for commit 0aa31af. This will update automatically on new commits. Configure here.}

---

Note

Centralizes attention metadata definitions for clearer ownership and reuse.

• Moves CommonAttentionMetadata, AttentionMetadataBuilder, and AttentionCGSupport to v1/attention/backend.py (definitions unchanged)
• Removes duplicated definitions from v1/attention/backends/utils.py; retains other utilities
• Updates imports across attention backends, model layers, worker/runtime code, spec-decode, and tests to reference v1/attention/backend
• No behavioral changes expected; CI covers affected paths

^{Written by Cursor Bugbot for commit 03883ba. This will update automatically on new commits. Configure here.}

---

Note

Consolidates attention metadata types and CUDA Graphs support into vllm.v1.attention.backend without changing behavior.

• Moves CommonAttentionMetadata, AttentionMetadataBuilder, and AttentionCGSupport from v1/attention/backends/utils.py to v1/attention/backend.py
• Updates imports across attention backends, model layers, worker code, spec-decode, tests, and docs (fixes reference in docs/design/cuda_graphs.md)
• Removes duplicated definitions from backends/utils.py; retains other utilities
• No functional changes expected; CI tests updated/use new imports

^{Written by Cursor Bugbot for commit a85395e. This will update automatically on new commits. Configure here.}

---

Note

Consolidates attention metadata and CUDA Graphs support types into vllm.v1.attention.backend for clearer ownership.

• Moves CommonAttentionMetadata, AttentionMetadataBuilder, and AttentionCGSupport from backends/utils.py to backend.py (definitions unchanged)
• Updates imports across attention backends, model layers, worker/runtime code, spec-decode, tests, and fixes doc reference in docs/design/cuda_graphs.md
• Removes duplicated definitions from backends/utils.py; retains other utilities
• No functional behavior changes expected; CI covers affected paths

^{Written by Cursor Bugbot for commit 516b5f6. This will update automatically on new commits. Configure here.}

[gemini-code-assist]

Code Review

This pull request aims to move AttentionMetadata-related code from utils.py to backend.py. Specifically, AttentionCGSupport and AttentionMetadataBuilder are moved. The PR description also mentions moving CommonAttentionMetadata, but this class remains in utils.py. This discrepancy might be unintentional.

I've found two critical issues with this refactoring that will cause runtime errors:

1. The destination file vllm/v1/attention/backend.py is missing several imports required by the moved code.
2. The source file vllm/v1/attention/backends/utils.py now has undefined name errors because it still references the moved classes without importing them.

I've added comments to address these issues. Please ensure all dependencies are correctly handled after the move.

[mergify]

Documentation preview: https://vllm--32054.org.readthedocs.build/en/32054/