Vllm Metax Model Upgrade

vLLM-MetaX Model Upgrade

Preserve the target upstream structure while implementing the verified MACA execution contract. A successful upgrade includes the model's reachable dependencies, not just its top-level Python file. Upstream support declarations and comments are evidence to investigate, not proof of support on MetaX.

Scope and environment

• Cover the requested models under vllm_metax/models/, their registration and configuration, and recursively their required attention, cache, compressor, indexer, projection, MTP/draft, MoE and kernel wrappers. Keep unrelated components out of scope.
• Keep review-only requests read-only. Establish whether the subject is the index, worktree, installed package or specified revision. Preserve staged/unstaged changes; do not stage, commit, reinstall dependencies or edit upstream/site-packages unless authorized. For staged validation, export and import the index snapshot explicitly.
• Read applicable repository instructions.
• Read and apply vllm-metax-upgrade-common before compatibility decisions. It owns environment/source discovery, the shared read-only probe, one-time target confirmation and verification evidence rules. Reuse the same established environment record across upgrade skills; do not ask again for an unchanged mapping. Keep the domain-specific workflow below.
• Apart from the common prerequisite above, do not automatically invoke patch, attention or registry skills just because the model calls those modules. Apply a separately requested specialist workflow only to its relevant portion. No monkey-patch headers or patch audit files are required for model adaptations.

Diff the source and audit the upgrade range first

• Identify the last upstream version represented by the local models and the confirmed target revision. Before editing, diff each local model file against its exact target-upstream counterpart, including explicit mappings between platform directories. Inspect target-only, local-only, changed and removed files; a matching class name does not establish matching behavior.
• Review every upstream commit in the version range that touches those model files. Read the patch for each commit, then inspect any other production modules changed by that commit and the model's direct callers/dependencies. Decide whether the behavior is inherited from vllm, needs a MetaX merge, needs a coordinated dependency change, is intentionally platform-specific, or belongs to a new unsupported architecture. Do not infer the answer from a commit title or from the final two-tree diff alone.
• Keep a compact file/commit disposition record with the affected interface, dependent MetaX symbols, chosen action and evidence. Include commits that require no local edit, so a missed upstream change remains visible. Recheck the complete local-vs-target diff after edits for unaccounted differences.
• When this skill runs before other MetaX upgrade skills, treat the confirmed target vllm source as the reliable API contract. A referenced MetaX module may still raise import or attribute errors because its own upgrade is pending. Record that boundary, continue source comparison and isolated checks, and do not misclassify the unrelated failure as a model regression. Still adapt a dependency when the requested model's changed logic requires it.

First establish the MACA/upstream differences

Before deciding what to copy or remove, build an evidence-backed difference matrix for each requested model family. Include the effective configuration after platform and speculative-decoding rewrites, not only the original HF config.

• Inspect the official config.json for the exact checkpoint variant and revision before reasoning about its layer layout. Record backbone and MTP/draft counts separately, count layer-indexed arrays (for example layer_types, rope_theta, partial_rotary_factors), and map zero-based checkpoint layer IDs to each part. Do not substitute config-class defaults or mistake the highest layer ID for the number of layers. If the official config is unavailable, state the evidence gap.
• Verify which config class the target vLLM actually loads and compare the raw checkpoint values with the constructed config after overrides and rewrites. Check whether constructors truncate or transform layer-indexed arrays before model and MTP code indexes them.

Separate intentional MetaX differences, inherited upstream behavior, obsolete overrides, adaptation defects and unverified assumptions. State unknowns explicitly. Inspect actual APIs, wrapper bodies and executable capability checks; challenge existing comments. A dtype name, matching signature or NVIDIA architecture predicate is not a MACA contract. Do not overwrite a necessary BF16/INT8 path with upstream FP8/FP4 behavior merely to reduce the diff. Structural alignment must preserve the established MACA semantics.

Recursively inventory and update dependencies

Trace from model registration through config rewriting, layer construction, weight loading, execution dispatch and kernels. Maintain a visited dependency inventory with: local symbol/file, target upstream counterpart, callers, relevant upstream delta, MetaX difference, action and validation evidence.

For each changed upstream model interface or behavior:

1. Inspect direct dependencies and their upstream changes.
2. Follow their dependencies until reaching a verified stable interface or an installed component boundary; record that boundary and why no further local change is needed.
3. Update affected local dependencies and callers together. Include model-private attention (such as DeepSeek V4 attention/compressor/FlashMLA code) even when it lives outside the main model file or a generic attention directory.
4. Inspect transitive consumers of shared helpers before changing their contracts. For external binary components, verify the installed API instead of silently upgrading or modifying the component.

Account for unchanged, removed, conditional and inactive files. Report blocked paths rather than claiming completion from successful imports of a subset. Read review-cases.md for relevant model-specific checks; its examples are investigation prompts, not permanent support restrictions.