👋 您好，欢迎向 MindSpeed MM 提交 Issue！

我们已收到您的反馈，感谢你对开源社区的支持。🎉

📅 处理时效： 维护团队将在 24 小时内 查看并回复您的问题（工作日）。

🚨 紧急联系： 如果您的问题非常紧急，可通过以下方式联系我们：

💬 微信：

请确保 Issue 描述清晰，包含复现步骤和日志，这将帮助我们更快定位问题。谢谢！

/label add good-first-issue

你好 我想认领这个任务

你好 我想认领这个任务

@weixin_51804216

欢迎参加昇腾社区贡献，我会进行登记

你好 我想认领这个任务

@weixin_51804216

欢迎认领任务，请参考https://gitcode.com/Ascend/MindSpeed-MM/issues/356 社区任务池明确该任务的：

• 完成的截止日期
• 开发进展反馈
• 微信答疑群
• 任务交付注意事项

等信息。如果您同时认领了多项任务，但无法都能进行投入，可以在部分任务中回复退出.

麻烦您加入到对应微信群，群备注名修改为"社区任务+您的gitcode账号", 后续有相关消息和问题都可以在微信群咨询答疑。 等您加入到微信群后，我这边会在社区任务池里面登记任务责任人。

你好 我想认领这个任务

@weixin_51804216

关于任务进展反馈的要求，您这边的开始时间可以从今天开始算，因为之前您认领任务时，这块细节还没敲定。

UT/ST应该可以补充不同的特性或模型吧，同认领一下

@yuehengbb

欢迎您参加昇腾社区贡献，你要是贡献其他UT，我们是欢迎的，但对于这里指定的悬赏任务https://gitcode.com/org/Ascend/discussions/4，一个任务只能分配一个开发进行验收，或者您可以选择认领其他任务。

认领这个任务

已补充mindspeed_mm/data/data_utils/bucket.py 的 Bucket 类的UT并提交了pr，请问需要编写多少单元测试代码呢？

已补充mindspeed_mm/data/data_utils/bucket.py 的 Bucket 类的UT并提交了pr，请问需要编写多少单元测试代码呢？

@weixin_51804216

PR中跟maintainer沟通反馈

开发者您好，MindSpeed-MM目前正聚焦FSDP2后端，鼓励补充FSDP2后端代码的UT和ST用例，FSDP2和非FSDP2后端（如Megatron后端）代码的一个重要区分是：FSDP2后端代码在mindspeed_mm/fsdp2/路径下，FSDP2后端的UT用例补充在tests\ut_fsdp路径下；对于ST用例，可以针对examples下的模型运行脚本针对模型训练跑测进行开发，其中v1结尾的脚本为纯FSDP2后端模型脚本（如examples\qwen3vl\finetune_qwen3vl_30B_v1.sh），qwen3_5、kimi_k3/2_5均为fsdp2后端脚本

实践文档

FSDP2 后端 LoRA 相关单元测试补充实践

一、背景与动机

MindSpeed-MM 当前聚焦 FSDP2 后端(源码位于 mindspeed_mm/fsdp/,UT 用例位于
tests/ut_fsdp/)。为提升 FSDP2 后端核心路径的测试覆盖度,本次实践针对 LoRA
(Low-Rank Adaptation)微调 及其相关的数据模板、配置校验模块补充了单元测试。

选择 LoRA 方向的原因:

1. LoRA 是 FSDP2 后端高频使用的高效微调能力,被训练主流程
   (mindspeed_mm/fsdp/train/trainer.py、train_engine.py)直接依赖;
2. 相关工具模块此前 零测试覆盖(在 tests/ut_fsdp/ 中检索无任何引用);
3. 主要逻辑为纯 torch + 标准库 / pydantic,可在无昇腾 NPU 的开发机(CPU)上
   完成逻辑自验,便于快速迭代,硬件相关路径交由 CI 门禁在昇腾环境验证。

二、覆盖的模块与用例

本次新增 3 个测试文件,合计 93 个用例(CPU 本地 90 通过 + 3 依赖 peft/
safetensors,本地按需跳过、CI 环境真实执行)。

测试文件	被测源码	说明
tests/ut_fsdp/utils/test_lora_utils.py	mindspeed_mm/fsdp/utils/lora_utils.py	LoRA 配置校验、目标模块通配符匹配、参数冻结与统计、state_dict 读取
tests/ut_fsdp/data/test_formatters.py	mindspeed_mm/fsdp/data/data_utils/func_utils/formatters.py	对话模板 slot 格式化器 EmptyFormatter/StringFormatter
tests/ut_fsdp/params/test_lora_args.py	mindspeed_mm/fsdp/params/lora_args.py	LoraArguments(pydantic)配置校验,enable=True 时触发

2.1 test_lora_utils.py

覆盖 lora_utils.py 的以下函数:

• validate_lora_config:rank/alpha 正数校验、target_modules 非空、dropout
  取值域 [0,1)、init_lora_weights 各合法字符串方法与 pissa_niter_N 正则分支、
  非法字符串与非 bool/str 类型的拒绝;
• is_pattern_match / match_target_modules:精确匹配、. 边界的后缀匹配、
  {*} 通配符匹配与非匹配、多模式命中去重;
• freeze_parameters:全部参数 requires_grad=False,且函数末尾 train() 使模型
  停留在训练态;
• get_lora_trainable_params:LoRA 参数与基座参数的统计拆分、可训练比例、空模型
  比例为 0 的保护分支;
• load_state_dict / load_state_dict_from_bin:.bin/.pt 存取往返与 dtype
  转换,以及 load_state_dict 对非 safetensors 后缀的分发;
• load_state_dict_from_safetensors、add_lora_to_model:分别以
  pytest.importorskip("safetensors") / ("peft") 门控;
• print_lora_config:日志输出与 total_params==0 分支。

2.2 test_formatters.py

• EmptyFormatter:含占位符时报错、纯文本正常构造、apply() 原样返回;
• StringFormatter:缺占位符报错、{{name}} 替换、dict/set slot 透传、非字符串
  入参报错;
• 特别覆盖 str.replace(..., 1) 只替换首次占位符出现的边界行为;
• FunctionCall namedtuple 字段。

2.3 test_lora_args.py

• 默认配置(enable=False)各字段默认值;
• 校验仅在 enable=True 时触发:enable=False 下非法 rank 也不报错;
• enable=True 下 rank/alpha/target_modules/dropout/init_lora_weights 的合法与
  非法分支。

三、本地验证方法(无 NPU 开发机)

开发机为 macOS,仅有 CPU、无昇腾 NPU,且未安装 megatron。直接
import mindspeed_mm 会因包 __init__.py 导入 megatron 而失败。为在本地验证测试
逻辑正确性,采用如下方式(仅本地临时使用,不进入仓库):

1. 通过 importlib.util.spec_from_file_location 以完全限定名直接加载被测源码模块,
   并在 sys.modules 中预置 mindspeed_mm 等占位父包,绕过会引入 megatron 的包
   __init__;
2. 对 lora_args.py 依赖的 base_args.py(pydantic)按同样方式以限定名先行加载;
3. 在此环境下 pytest.main([...]) 运行三个测试文件。

验证结果:90 passed, 3 skipped(3 项为 peft/safetensors 门控用例)。

提交仓库的测试文件均使用标准 from mindspeed_mm.fsdp... import 导入,与
tests/ut_fsdp/ 现有用例一致。上述绕过仅用于本地无 megatron 环境的逻辑自验;
CI 门禁在昇腾环境安装完整依赖后,导入可正常解析,全部用例(含 3 个门控用例)真实
执行。

四、CI 验证

PR 提交后,由 ci/run_ci.sh → ci/access_control_test.py 在昇腾服务器自动执行:

• pytest -x tests/ut(非 FSDP2 UT)
• pytest -x tests/ut_fsdp(FSDP2 UT,本次新增用例在此收集运行)
• ST 系统测试

其中 -x 表示任一用例失败即中断,因此本次提交前已在本地完成可验证部分的自检。

五、遇到的问题与结论

1. 反馈路径澄清:评审反馈提到的 mindspeed_mm/fsdp2/ 目录实际不存在;FSDP2 为
   技术特性名,承载其代码的目录为 mindspeed_mm/fsdp/,测试目录 tests/ut_fsdp/
   正确。本次用例均落在 tests/ut_fsdp/。
2. pydantic 校验行为:LoraArguments 基于 pydantic,非法配置抛出的是
   pydantic.ValidationError(为 ValueError 子类,pytest.raises(ValueError)
   仍可捕获);其字段级 Literal 校验会先于 model_post_init 执行。测试仅断言稳定
   契约,不绑定该实现细节。
3. 占位符替换边界:StringFormatter 使用 replace(..., 1),同名占位符多次出现
   时仅替换第一处,已用独立用例固化该行为。

您好！

MindSpeed-MM 邀请您参加 2026-08-20 16:00 召开的WeLink会议

会议主题：MindSpeed MM 社区例会

会议内容：
1.社区关键issue解答
2.代码合入评审

会议链接：https://meeting.huaweicloud.com:36443/#/j/980887584

会议纪要&签到链接：https://etherpad.ascend.osinfra.cn/p/sig-MindSpeed-MM