mindspeed-fsdp2-model-migration

MindSpeed FSDP2 Model Migration

Objective

Under the premise of satisfying the framework contract, migrate the model layer to MindSpeed-MM FSDP2 while preserving the source model semantics.

Applicable Scenarios

• The migration task requires creating a model plugin under mindspeed_mm/fsdp/models/ .
• Need to add or fix model_id registration and ModelHub compatibility.
• Need to adapt the model loading signature (from_pretrained、_from_config）。

Inapplicable Scenarios

• The task is data preprocessing or dataloader behavior adjustment.
• The task involves only YAML mapping.
• The task is only validation-phase issue triage.

Input

• Source model entry file
• Target model_id
• Required special token behavior
• FSDP2 constraints in the target configuration
• runtime_assets.model_path

Output

• Model plugin implementation
• Model migration checklist with pass/fail status
• Rationale for each "non-reuse change"

Required Check Items

1. Registration contract:
   • @model_register.register("<model_id>")
2. Construction contract:
   • from_pretrained and ModelArguments call chain compatible
   • _from_config path valid
3. Semantic contract:
   • When the source model requires special tokens, its processing flow must be preserved
   • Perform embedding resize/init only when necessary
4. Training contract:
   • The forward path can receive trainer input and return .loss

Anti-Deviation Execution Protocol

1. Must be completed before implementation:
   • Verify that runtime_assets.model_path exists and is readable
   • Extract the signature pattern by comparing with the most similar case
2. Must be produced after implementation:
   • model_contract_checklist.md
   • signature_compat_report.md
3. Stop on failure:
   • from_pretrained or _from_config If either is incompatible, subsequent stages are prohibited from continuing

Prohibited Actions

• Prohibited to write from_pretrained as a single-parameter signature only
• Prohibited to determine compatibility solely by "reading the code"; call evidence must be provided
• Prohibited to modify token constants when token-id alignment has not been confirmed
• Prohibited to delete key post-processing logic of the source model without providing an equivalent replacement

Implementation Rules

• Prioritize reuse of source logic; adapt only when the framework contract is incompatible.
• The modification scope is limited to the model plugin area.
• Do not introduce external hard dependencies on the source repository package paths.
• Record the precise reason for each adaptation.

Exit Criteria

• The model can be constructed via ModelHub according to the target model_id .
• Loading signature conflicts have been resolved.
• All model-side checklist conclusions are supported by evidence.

Progressive Resources

• checks/model-acceptance.md
• checks/model-contract-gates.md
• errors/model-error-dictionary.md
• errors/triage-severity.md
• examples/minimal-io.md

Read these files only when detailed criteria are needed for acceptance or error triage.