执行摘要

• 一句话：修复 telechat2/terratorch 的 mypy 类型错误并调整 EXCLUDE 前缀
• 推荐动作：该 PR 值得快速浏览，特别是 telechat2.py 中类型窄化与 register_parameter 的用法，可为类似 mypy 修复提供参考。若关注 mypy 基础设施演进，可关注 #48490 系列拆分。

功能与动机

作为 #48490 中按字母拆分 mypy 修复工作的一部分，本 PR 继续处理 [tT] 分组的 10 个 mypy 错误。PR body 明确指出：terratorch.py 需注解 loaded_buffers；telechat2.py 需窄化 layer.self_attn / layer.mlp 类型，因为 Module.__getattr__ 返回 Tensor | Module，导致子模块属性检查失败。同时 EXCLUDE 前缀模式 models/[tT] 会误覆盖 models/transformers 包，因此需收窄为 models/transformers 以确保全仓检查通过。

实现拆解

1. telechat2.py 类型窄化与 bias 移除重构：新增导入 LlamaAttention、LlamaMLP；在 __init__ 中，将 if not isinstance(layer, PPMissingLayer) 改为 continue 早退，然后对 self_attn 和 mlp 分支做 assert isinstance，便于 mypy 推断具体类型。bias 移除从 attribute.bias = None 改为 register_parameter("bias", None)，与 linear.py 惯例一致。对 attribute_map 赋值添加 # type: ignore[misc] 抑制误报。
2. terratorch.py 注解补充：仅将 loaded_buffers = [] 改为 loaded_buffers: list[str] = []，明确类型。
3. tools/pre_commit/mypy.py EXCLUDE 收窄：将 r"vllm/model_executor/models/[tT]" 改为 r"vllm/model_executor/models/transformers"，避免误排除 [tT] 下已修复文件，同时继续排除仍有错误的 models/transformers 包。
4. 测试与验证：未新增测试文件；通过本地运行 pre-commit run mypy-3.10/3.11/3.12/3.13 --all-files 验证 10 个错误全部消失，全仓检查通过。

关键文件：

• vllm/model_executor/models/telechat2.py（模块 模型模块；类别 source；类型 core-logic；符号 telechat2.py, LlamaAttention, LlamaMLP, TeleChat2Model.init）: 核心变更文件，修复 8 个 mypy 错误，涉及类型窄化、bias 移除方式和 attribute_map 的 ignore 注释。
• vllm/model_executor/models/terratorch.py（模块 模型模块；类别 source；类型 type-annotation；符号 terratorch.py, TerratorchForConditionalGeneration.load_weights）: 补充 loaded_buffers 的类型注解，修复 1 个 mypy 错误。
• tools/pre_commit/mypy.py（模块 类型检查；类别 infra；类型 configuration）: 调整 EXCLUDE 前缀，确保全仓 mypy 检查通过并正确覆盖 [tT] 分组。

关键符号：TeleChat2Model.init, terratorch.load_weights

关键源码片段

vllm/model_executor/models/telechat2.py

核心变更文件，修复 8 个 mypy 错误，涉及类型窄化、bias 移除方式和 attribute_map 的 ignore 注释。

# vllm/model_executor/models/telechat2.py
from .llama import LlamaAttention, LlamaDecoderLayer, LlamaMLP
​
class TeleChat2Model(LlamaModel):
    def __init__(self, *, vllm_config, prefix=""):
        # ... 初始化配置 ...
        for layer in self.layers:
            if isinstance(layer, PPMissingLayer):
                continue
            # 类型窄化：mypy 需要明确具体子类才能检查内部属性
            self_attn = layer.self_attn
            mlp = layer.mlp
            assert isinstance(self_attn, LlamaAttention)
            assert isinstance(mlp, LlamaMLP)
            # 使用 register_parameter 清除 bias，保持与 nn.Module 行为一致
            self_attn.qkv_proj.register_parameter("bias", None)
            self_attn.qkv_proj.skip_bias_add = True
            mlp.gate_up_proj.register_parameter("bias", None)
            mlp.gate_up_proj.skip_bias_add = True
​
        # attribute_map 是 PretrainedConfig 上的 ClassVar，实例级赋值是刻意的
        vllm_config.model_config.hf_config.attribute_map = { # type: ignore[misc]
            "num_hidden_layers": "n_layer",
            "num_attention_heads": "n_head",
            "intermediate_size": "ffn_hidden_size",
            "rms_norm_eps": "layer_norm_epsilon",
        }

vllm/model_executor/models/terratorch.py

补充 loaded_buffers 的类型注解，修复 1 个 mypy 错误。

# vllm/model_executor/models/terratorch.py
    def load_weights(self, weights):
        params_list = []
        model_buffers = dict(self.named_buffers())
        # 明确列表元素类型，消除 mypy 对空列表的推断歧义
        loaded_buffers: list[str] = []
        ...
        for key, value in weights:
            ...
                    if name in model_buffers:
                        ...
                        loaded_buffers.append(name)

tools/pre_commit/mypy.py

调整 EXCLUDE 前缀，确保全仓 mypy 检查通过并正确覆盖 [tT] 分组。

# tools/pre_commit/mypy.py
EXCLUDE = [
    ...
    # [tT] 分组已修复，但 transformers 包仍有错误，故单独排除
    r"vllm/model_executor/models/transformers",
    ...
]

评论区精华

reviewer yewentao256 提出两处简洁性建议：在 tools/pre_commit/mypy.py 中建议移除解释注释，直接使用 r"vllm/model_executor/models/transformers"；在 telechat2.py 中建议移除 attribute_map 的说明注释，仅保留 # type: ignore[misc]。作者已在 commit 8e3e891 中采纳这些建议，并重新验证 mypy 通过。

• mypy.py 注释简化 (style): 作者采纳，移除了注释。
• telechat2.py 注释简化 (style): 作者采纳，移除了注释。

风险与影响

• 风险：
  • 类型断言风险：telechat2.py 中新增的 assert isinstance(self_attn, LlamaAttention) 和 assert isinstance(mlp, LlamaMLP) 在运行时若类型不符会抛出 AssertionError。但 PR 已论证 TeleChat2Model 未传 layer_type，默认使用 LlamaDecoderLayer，其 attn_layer_type 默认为 LlamaAttention，mlp 恒为 LlamaMLP，因此风险较低。
  • EXCLUDE 收窄风险：将 [tT] 前缀收窄为 models/transformers 后，teleflm.py 等 [tT] 文件开始被 mypy 完整检查，若这些文件存在潜在未修复错误，可能导致未来 CI 暴露问题。但作者已验证当前通过。
  • 无测试覆盖：此 PR 未修改测试文件，但属于纯类型注解与重构，不改变运行时行为，风险可控。
  • 影响：影响范围限于 [tT] 字母分组的模型文件，主要为类型检查和构建工具配置调整，不改变模型推理行为。对维护者而言，减少 mypy 错误数量是渐进式质量改进；对下游用户无功能影响。
  • 风险标记：无测试覆盖, 类型断言运行时风险, EXCLUDE 收窄影响面

关联脉络

• PR #48490 [Mypy Fix] Split mypy work: 本 PR 是该拆分工作的延续，处理 [tT] 分组。
• PR #48977 [Mypy Fix] Mypy fix for "vllm/model_executor/models/[aA][bB]": 同一拆分系列，处理 [aA][bB] 分组。
• PR #52003 [Mypy Fix] Mypy fix for "vllm/model_executor/models/[cC][dD]": 同一拆分系列，处理 [cC][dD] 分组。
• PR #53381 [Mypy Fix] Mypy fix for "vllm/model_executor/models/[eE][fF]": 同一拆分系列，处理 [eE][fF] 分组。