PR 提交说明

提交前请阅读 贡献指南，开发者文档：模型接入指南

PR 标题前缀：[Feature]、[Bugfix]、[Doc]、[Test]（与 CONTRIBUTING 一致）

1. 影响面评估

接口变更（按需）： 新增能力（兼容扩展）

• 新增模型类型 Kimi-K3 及适配器入口（config/config.ini → msmodelslim.model.kimi_k3）
• 新增实践配置 lab_practice/kimi_k3/kimi_k3_w4a8.yaml 与示例文档

输出件变更（按需）： 无

非兼容变更（按需）： 无

SIG 评审结论（按需）： 无

2. 修改描述

修改背景：

Kimi-K3 为原生多模态大模型（混合注意力 KDA/MLA + Latent MoE），权重以 compressed-tensors MXFP4 存储，体量大、结构复杂。社区此前缺少对应模型适配器与 W4A8 实践配置

修改目的：

接入 Kimi-K3 模型适配器，支持语言侧 Decoder 的 W4A8 混合量化（含 MXFP4 加载反量化、EP、QuaRot、FA3）；并让 VLM 量化服务支持 auto / dp_layer_wise，与 LLM 侧调度对齐，便于多卡加速。

修改内容：

• msmodelslim/model/kimi_k3
  • 新增 KimiK3ModelAdapter：layer-wise 加载、多模态校准数据（image+text）、IterSmooth 子图配置（KDA/MLA/FFN）
  • convert_mxfp4_to_bf16：compressed-tensors MXFP4（weight_packed + E8M0 scale）反量化为 BF16 nn.Linear
  • ep_patches：对权重目录内 KimiSparseMoeBlock 做 EP monkey-patch（本地 expert 分片 + DP gather / all_reduce），不改权重仓 modeling_*.py
  • quarot：离线 QuaRot 的 ln fuse / rotate map（含 EP 本地 expert 的 rot_latent）
  • runtime_patches：NPU 上用纯 PyTorch 路径替换易超时的 FLA KDA Triton 核
  • FA3：在 KimiMLAAttention（absorb MLA）注入 placeholder，对接 Ascend MLA FA
• msmodelslim/model/common/utils.py：抽取 resolve_expert_ep_range，统一 EP expert 范围计算
• config/config.ini：注册 kimi_k3
• lab_practice/kimi_k3/kimi_k3_w4a8.yaml：新增 W4A8 实践配置
• example/multimodal_vlm/Kimi-K3/README.md、docs/zh/knowledge_base/model/README.md、docs/zh/user_guide/usage_quick_quantization.md：补充 Kimi-K3 与 VLM DP 说明
• test/cases/model/kimi_k3/*、test/cases/core/quant_service/multimodal_vlm_v1/、test/cases/utils/test_distributed.py：补充 UT

3. 功能验证

冒烟由 CI 门禁检查，无需填写「冒烟是否通过」。

• 功能自验
• 本地自验用例截图（请勿包含个人信息；可附复现命令）

复现步骤（可选）：

# 依赖
pip install transformers==4.57.6 compressed-tensors==0.13.0
pip install -U fla-core

# Kimi-K3 W4A8 一键量化（推荐多卡；runner 默认 auto）
msmodelslim quant \
    --model_path ${model_path} \
    --save_path ${save_path} \
    --device npu:0,1,2,3,4,5,6,7 \
    --model_type Kimi-K3 \
    --quant_type w4a8 \
    --trust_remote_code True

说明：实践配置见 lab_practice/kimi_k3/kimi_k3_w4a8.yaml（expert W4A8 + latent/shared W8A8）；校准数据需同时包含 image 与 text。EP 由适配器侧处理，与 runner DP 相互独立、可叠加；使用 DP 时配置中的处理器/算法需支持分布式执行。

4. 自检（请逐项确认，不适用标 N/A）

典型安全编码问题

• 是否已校验外部数据（模型路径 / runner / offload_device / expert 数与 world_size 整除校验等）
• 是否未采集或打印敏感信息
• N/A 是否已正确设置文件权限
• N/A 是否充分考虑浮点运算溢出、除零等异常场景
• N/A 是否已对正则表达式做 ReDos 检查

DT

• 是否具备 UT 测试用例看护（路径：test/cases/model/kimi_k3/、test/cases/core/quant_service/multimodal_vlm_v1/test_multimodal_vlm_modelslim_v1_quant_service.py、test/cases/utils/test_distributed.py）
• 是否需要添加冒烟：否