mindspeed-fsdp2-config-migration

MindSpeed FSDP2 Configuration Migration

Objectives

Convert source training/configuration semantics into valid MindSpeed-MM FSDP2 YAML, and ensure registration associations are correct and field layering is safe.

Applicable Scenarios

• The migration task requires creating or fixing examples/fsdp2/*_config.yaml。
• model_id、dataset_type、training.plugin mapping is missing or inconsistent.
• Data parameter layering errors cause dataclass strict-field errors.

Inapplicable Scenarios

• The task is model code adaptation.
• The task is data preprocessing implementation.
• The task is final test execution and report generation.

Inputs

• Source training parameters or scripts
• Target model/data registration id
• Required parallelism/FSDP2 module matching patterns
• runtime_assets(at least including model_path、dataset_path）

Outputs

• YAML configuration draft/update
• Mapping table (source parameter -> target YAML field)
• Configuration migration checklist with pass/fail status

Mandatory Checks

1. Registration associations:
   • model.model_id is consistent with the model registration
   • data.dataset_param.dataset_type is consistent with the data registration
   • training.plugin can import the model and data plugin packages
2. Field layering:
   • strict dataclass fields are kept in basic_parameters
   • custom extension fields are placed in *_extra
3. Parallelism configuration sanity:
   • parallel.fsdp_plan.apply_modules points to a valid module
   • dtype/recompute option syntax is valid
4. Configuration mandatory field completeness:
   • model.model_id、model.model_name_or_path
   • data.dataset_param.dataset_type
   • data.dataset_param.basic_parameters.dataset
   • data.dataset_param.preprocess_parameters.model_name_or_path
   • data.dataloader_param under dataloader_mode、sampler_type、shuffle、drop_last、pin_memory、collate_param
   • data.dataloader_param.collate_param.model_name
   • training.lr、training.micro_batch_size、training.train_iters

Anti-Deviation Execution Protocol

1. Before implementation, the following must be completed:
   • model_id、dataset_type、training.plugin the triple target values are frozen
   • Real runtime assets (model/dataset) are mapped to configuration fields
2. After implementation, the following must be produced:
   • config_mapping_table.md
   • linkage_check_report.md
3. Stop on failure:
   • When any registration association fails, entering the verification phase is prohibited

Prohibited Actions

• Writing extension fields into the strict dataclass block is prohibited
• Prohibited: training.plugin writing only the model plugin and not the data plugin
• Prohibited: apply_modules using hardcoded patterns unrelated to the model structure
• Directly reusing another model's apply_modules list without matching verification is prohibited
• Omitting mandatory fields and relying on implicit default values is prohibited
• Claiming the configuration is usable without running parse checks is prohibited

Implementation Rules

• First preserve the source configuration semantics, then adapt the configuration form.
• Custom fields must not be placed into strict schema blocks.
• Configuration changes must be explicit and traceable.
• Every non-trivial mapping decision must be justified.

Exit Criteria

• YAML is parseable and registration associations are consistent.
• Configuration layering does not introduce strict-field schema errors.
• All configuration-side checklist conclusions are supported by evidence.

Progressive Resources

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

Only read these files when detailed criteria are needed for field layering checks or configuration error triage.