执行摘要

• 一句话：提取公共权重处理函数，批量移除 44 个模型的 load_weights
• 推荐动作：此 PR 是一次高质量的重构，值得深入阅读以理解如何通过 WeightsMapper 和 AutoWeightsLoader 标准化权重加载流程。建议在 Review 时重点关注：
  1. 各模型的 hf_to_vllm_mapper 定义是否完整覆盖所有参数重命名；
  2. 保留的自定义回调（如 _slice_sink）是否正确处理了特殊逻辑；
  3. 是否有遗漏的模型文件未改造。

功能与动机

PR 作者指出，多个模型重复实现了相同的权重过滤逻辑（如专家融合的 fuse_shared_experts 和跳过 spec 层的 get_spec_layer_idx_from_weight_name）。本 PR 旨在将这些公共代码提取到一处，消除样板代码，降低维护成本。

实现拆解

1. 定义通用工具函数：在 vllm/model_executor/models/utils.py 中新增 maybe_fuse_shared_experts、get_spec_layer_idx_from_weight_name、skip_spec_layers，分别处理 AITER 融合共享专家优化、spec 层索引提取和 spec 层权重过滤。
2. 拆分模型特定的权重预处理：对存在额外数据变换的模型（如 Param2MoE），将权重名称翻译（HF→vLLM）拆分为 WeightsMapper 声明（纯映射）和独立的张量处理函数（如 _normalize_expert_bias），因为 WeightsMapper 无法修改张量值。
3. 逐个改造模型类：共修改 44 个模型文件，每个模型类中：
   • 删除原有的 load_weights 方法（含 stacked_params_mapping、expert_params_mapping、手动迭代 params_dict 等）。
   • 添加类属性 hf_to_vllm_mapper = WeightsMapper(...) 描述权重重命名规则。
   • 将 load_weights 精简为一行委托调用：AutoWeightsLoader(self, ...).load_weights(weights, mapper=self.hf_to_vllm_mapper)。
   • 对需要额外预处理权重的模型（如 Laguna 的 KV 缓存缩放、Laguna 的 _slice_sink），保留自定义回调并在 AutoWeightsLoader 初始化时传入。
4. 清理无用代码：移除不再需要的导入（如 default_weight_loader、maybe_remap_kv_scale_name、is_pp_missing_parameter）和废弃的类（如 AriaRoutedExperts）。
5. 测试与配置：本 PR 未引入新测试，依赖现有 CI 覆盖；运行时行为不变，因此不涉及配置变更。

关键文件：

• vllm/model_executor/models/utils.py（模块 工具函数；类别 source；类型 data-contract；符号 maybe_fuse_shared_experts, get_spec_layer_idx_from_weight_name, skip_spec_layers）: 新增三个通用权重处理函数，是整个重构的公共基础设施。
• vllm/model_executor/models/aria.py（模块 Aria模型；类别 source；类型 data-contract；符号 AriaModel.hf_to_vllm_mapper, AriaModel.load_weights, AriaRoutedExperts）: 典型示例，完整展示了从自定义 load_weights 到 AutoWeightsLoader + WeightsMapper 的转换。
• vllm/model_executor/models/param2moe.py（模块 Param2MoE模型；类别 source；类型 data-contract；符号 _normalize_expert_bias, hf_to_vllm_mapper, _rename_and_normalize_weights）: 展示了 WeightsMapper 与数据变换函数的拆分：重命名由 mapper 处理，零均值化保留为单独函数。
• vllm/model_executor/models/openpangu.py（模块 盘古模型；类别 source；类型 data-contract；符号 load_attn_mlp_weight, load_expert_weight, load_weights, _filter_spec_layers）: 删除代码最多（152 行），展示大规模移除冗 long 权重加载方法。
• vllm/model_executor/models/glm4_moe.py（模块 GLM4模型；类别 source；类型 data-contract；符号 get_expert_mapping, get_spec_layer_idx_from_weight_name, hf_to_vllm_mapper, load_weights）: 使用了新增的 maybe_fuse_shared_experts 和 skip_spec_layers 通用函数。

关键符号：maybe_fuse_shared_experts, get_spec_layer_idx_from_weight_name, skip_spec_layers, _normalize_expert_bias, _slice_sink, _preprocess, hf_to_vllm_mapper

关键源码片段

vllm/model_executor/models/aria.py

典型示例，完整展示了从自定义 load_weights 到 AutoWeightsLoader + WeightsMapper 的转换。

class AriaModel(nn.Module):
    # ... 其他成员 ...
​
    # 定义权重名称重映射：将 HuggingFace 的命名映射到 vLLM 内部命名
    hf_to_vllm_mapper = WeightsMapper(
        orig_to_new_stacked={
            ".q_proj": (".qkv_proj", "q"), # Q 投影
            ".k_proj": (".qkv_proj", "k"), # K 投影
            ".v_proj": (".qkv_proj", "v"), # V 投影
        }
    )
​
    def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
        # NOTE: post_layernorm 在 Aria 中未使用，跳过它
        loader = AutoWeightsLoader(self, skip_substrs=["post_layernorm"])
        return loader.load_weights(weights, mapper=self.hf_to_vllm_mapper)

评论区精华

PR 无人工 Review 讨论。Mergify 曾提示合并冲突和 pre-commit 失败，作者已通过后续提交解决。

• 合并冲突和 pre-commit 问题 (other): 作者通过 rebase 和修复 pre-commit 解决。

风险与影响

• 风险：大规模跨模型重构风险较高：44 个模型文件均修改了权重加载路径，虽然功能等价，但任何模型特有的加载逻辑（如非标准参数命名、特殊量化处理）若未被通用函数覆盖，可能导致加载失败。新引入的 WeightsMapper 依赖假设 HF 命名规范与 vLLM 内部命名的对应关系，若某模型有例外，可能引入 bug。当前没有新增回归测试，仅依赖现有 CI 覆盖，风险中等。
• 影响：对用户：无直接影响，运行时行为不变。对系统：统一权重加载路径，便于未来维护和扩展，减少重复代码。对团队：后续新增模型可复用通用工具函数，降低开发成本。
• 风险标记：大规模跨模型重构, 缺乏测试覆盖, 核心路径变更

关联脉络

• PR #48780 [Refactor] Remove deepseek dead code: 同为模型文件清理，删除了 DeepSeek 编码器中的死代码与冗余预热逻辑，与本 PR 的去重方向一致。