[AlejandroParedesLT]

Overview

Next slice of #61024's "Migrate speculative model code to Flat Model" bullet (RFC #44219). Moves the HY V3 model and its MTP drafter from the legacy vllm/model_executor/models/ layout into the new vllm/models/<name>/<hw>/ layout.

Claims

• Moves vllm/model_executor/models/hy_v3.py and hy_v3_mtp.py to vllm/models/hy_v3/common/{model,mtp}.py, repointing the HYV3ForCausalLM and HYV3MTPModel registry entries to vllm.models.hy_v3.
• No logic change. The only diff inside the moved files is fixing imports that crossed the old package boundary (.utils, .interfaces → vllm.model_executor.models.{utils,interfaces}, and the MTP file's from .hy_v3 import HYV3DecoderLayer → from .model import HYV3DecoderLayer), verified by diffing old vs. new file content.
• HY V3 needs only a common/ directory, no nvidia/amd/cpu/xpu split: zero custom kernels, and zero platform-conditional code (grep -c "is_rocm\|is_cuda\|sm90\|sm100" → 0). HY V4 (vllm.models.hy_v4), by contrast, needed a real nvidia/amd split for flashmla_sparse/triton_ihc -- V3 predates those optimizations.
• Unlike every other remaining legacy drafter, hy_v3.py/hy_v3_mtp.py have zero dependency on any other model file -- confirmed by grep across the whole tree, they're the only two files that reference each other. That made this pair the next candidate after Medusa.

Validation

.venv/bin/python -m pytest tests/models/test_registry.py -q -k HYV3
# 2 passed

pre-commit run --files vllm/model_executor/models/registry.py vllm/models/hy_v3/__init__.py vllm/models/hy_v3/common/__init__.py vllm/models/hy_v3/common/model.py vllm/models/hy_v3/common/mtp.py
# all hooks passed (ruff check/format, mypy, SPDX headers, etc.)

No e2e acceptance-rate test exists for HY V3 under tests/v1/e2e/spec_decode/acceptance_rates/ (unlike Medusa, which had one) and I don't have a validated local checkpoint-loading path for it on this change, so the above is the available coverage. tests/models/registry.py lists tencent/Hy3-preview as the example checkpoint if a reviewer wants to validate a real weight load.

Details

Why HY V3 and not another drafter: every remaining legacy drafter (EAGLE/EAGLE3 variants, the other MTP variants, DFlash) imports its base model's decoder-layer class directly from a still-legacy file (llama, qwen2, qwen3, deepseek_v2, etc.), so migrating any of them means migrating a shared, heavily-reused base model too -- a much bigger, higher-blast-radius change. HY V3 is the one pair with zero such entanglement.

Previous attempt: #61357 targeted Medusa as the first migration in this series, but Medusa was removed from vLLM entirely in #61701 while that PR was in flight ("Medusa is not supported by Model Runner V2, and EAGLE/MTP/DFlash/DSpark cover its use case"). Closed #61357 as superseded by that removal rather than resurrect deleted code.

Duplicate-work check: searched open issues/PRs for existing HY V3 Flat Model migration work; found none.

Scope: this PR only moves HY V3 + its MTP drafter. The remaining legacy drafters are out of scope here and need their base model migrated alongside them, which is a larger, separate decision per model family.

---

Pull Request Checklist

• I used vLLM's /pr-checklist skill. (Mandatory for agents, optional for humans).

• AI assistance was used during the creation of this PR.

• Design Fit: Minimizes impact on core components, reuses existing functionality, and justifies added complexity.

• Testing and Validation: Validates the change and ensures any added tests are meaningful and reliable, with CI coverage or documented CI resource constraints and validation performed outside CI.

• Code Quality and Style: Keeps code and comments clear and concise, and updates relevant documentation and examples.

• Pull Request Contents: Includes a brief summary and relevant links, supports claims with evidence, explains root causes and implementation trade-offs, and follows the contributing guide.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S7agbtPNuVe9pxACkqbitP

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[AlejandroParedesLT]

Hey @WoosukKwon, could you please take a look when you get a chance? Thanks!