执行摘要

• 一句话：为包式后端恢复 ModelInfo 缓存，修复启动性能回归
• 推荐动作：值得精读，尤其关注 inspect_model_cls 的路径解析逻辑变更，以及缓存命中对启动性能的影响。设计上回退到 find_spec 是合理的，但需注意对不同模块布局的兼容性。

功能与动机

根据 PR body 说明，自 #26906 将 Transformers 后端从 transformers.py 转为包后，ModelInfo 缓存继续寻找已删除的文件，导致 module_hash 始终为 None，缓存读写被跳过。此 PR 旨在恢复包后端的缓存能力，但不解决整体启动时间差距，相关问题记录在 #50128。

实现拆解

1. 修改 registry.py 中的 inspect_model_cls 方法，增加 model_path 初始化为 None，当模块名以 vllm.model_executor.models. 开头时尝试拼接扁平文件路径，若不存在或为空则使用 find_spec 查找模块 spec 并获取 origin 路径。
2. 修改测试文件 tests/models/test_registry.py，新增 test_lazy_modelinfo_package_attempts_cache_load 测试，模拟包后端场景，验证缓存加载路径被调用且返回缓存结果，并通过 monkeypatch 设置 _run_in_subprocess 为失败断言，确保缓存路径正确使用。

关键文件：

• vllm/model_executor/models/registry.py（模块 模型注册器；类别 source；类型 core-logic；符号 inspect_model_cls）: 核心变更，修改了 inspect_model_cls 的模块路径解析逻辑，恢复包后端缓存。
• tests/models/test_registry.py（模块 注册表测试；类别 test；类型 test-coverage；符号 test_lazy_modelinfo_package_attempts_cache_load, fake_load_cache）: 新增测试覆盖包后端缓存行为，确保回退逻辑正确且不误用子进程加载。

关键符号：inspect_model_cls, _get_modelinfo_module_hash, _load_modelinfo_from_cache

关键源码片段

vllm/model_executor/models/registry.py

核心变更，修改了 inspect_model_cls 的模块路径解析逻辑，恢复包后端缓存。

# 关键方法：inspect_model_cls
# 在检查模型类时，优先尝试定位模块对应的源码文件路径，
# 以便计算 file hash 用于缓存判断。
@logtime(logger=logger, msg="Registry inspect model class")
def inspect_model_cls(self) -> _ModelInfo:
    # 初始化为 None，若找不到文件路径则跳过缓存逻辑
    model_path: Path | None = None
    # 对标准模型布局，直接拼接相对路径（扁平 .py 文件）
    if self.module_name.startswith("vllm.model_executor.models."):
        model_path = Path(__file__).parent / f"{self.module_name.split('.')[-1]}.py"
    # 若未找到（如包结构没有同名 .py），则回退到 find_spec 解析包入口
    if model_path is None or not model_path.exists():
        try:
            spec = importlib.util.find_spec(self.module_name)
        except (ImportError, ValueError):
            spec = None
        # 使用包 __init__ 或模块文件的真实路径
        model_path = Path(spec.origin) if spec is not None and spec.origin else None
    module_hash = None
​
    # 只有拿到有效路径才尝试缓存读。
    # 之前包后端因路径为 None 跳过缓存，导致每次启动都重新检查。
    if model_path is not None and model_path.exists():
        module_hash = self._get_modelinfo_module_hash(model_path)
​
        mi = self._load_modelinfo_from_cache(module_hash)
        if mi is not None:
            logger.debug("Loaded model info for class %s.%s from cache", self.module_name, self.class_name)
            return mi
        else:
            logger.debug("Cache model info for class %s.%s miss. Loading model instead.", self.module_name, self.class_name)
​
    # 缓存未命中时，在子进程中加载模型，避免初始化 CUDA
    mi = _run_in_subprocess(lambda: _ModelInfo.from_model_cls(self.load_model_cls()))
    logger.debug("Loaded model info for class %s.%s", self.module_name, self.class_name)
    if module_hash is not None:
        self._save_modelinfo_to_cache(mi, module_hash)
    return mi

tests/models/test_registry.py

新增测试覆盖包后端缓存行为，确保回退逻辑正确且不误用子进程加载。

# 新增测试：验证包后端能够通过缓存路径获取 ModelInfo，
# 而不是退回子进程加载。
def test_lazy_modelinfo_package_attempts_cache_load(monkeypatch):
    # 用一个哨兵对象表示缓存的模型信息
    cached_model_info = object()
    loaded_hashes = []
​
    # 模拟缓存加载函数，记录传入的 module_hash
    def fake_load_cache(self, module_hash):
        loaded_hashes.append(module_hash)
        return cached_model_info
​
    monkeypatch.setattr(_LazyRegisteredModel, "_load_modelinfo_from_cache", fake_load_cache)
    # 确保不会走到子进程加载（若调用则测试失败）
    monkeypatch.setattr(
        "vllm.model_executor.models.registry._run_in_subprocess",
        lambda _: pytest.fail("Package-backed model should use the cache path"),
    )
​
    # 使用 transformers 包后端作为测试对象
    registered_model = _LazyRegisteredModel(
        module_name="vllm.model_executor.models.transformers",
        class_name="TransformersForCausalLM",
    )
​
    result = registered_model.inspect_model_cls()
​
    # 应返回缓存的对象，且只用了一次缓存读取
    assert result is cached_model_info
    assert len(loaded_hashes) == 1
    assert loaded_hashes[0]

评论区精华

review 中 hmellor 曾建议将模块路径解析提取为静态方法 _get_model_path，但作者经过讨论后采用了内联的简化实现，避免了命名空间污染。测试方面，作者将原先针对 helper 的测试改为行为测试，更贴合实际使用场景。

• 模块路径解析逻辑设计 (design): 作者采用了内联的 find_spec 回退实现，并通过测试验证。
• 测试策略调整 (testing): 测试更贴合实际使用场景，已验证缓存路径正确。

风险与影响

• 风险：主要风险在于 find_spec 回退逻辑对非标准模块布局（如硬件隔离的 vllm.models 布局）可能产生路径解析错误，但代码已做了 spec 为 None 或 origin 为空的防御处理。测试仅覆盖了包路径，未覆盖扁平文件路径的缓存命中场景，但现有测试可能已覆盖。
• 影响：对使用 Transformers 包后端的用户，启动时间将从约 49 秒降至 35 秒，尤其缓存命中时明显降低。对原生 vLLM 后端无影响。对系统而言，缓存逻辑的恢复减少了重复模型类检查，提升了启动效率。
• 风险标记：核心路径变更, 缺少性能基准测试

关联脉络

• PR #50128 [Performance] Measure Transformers backend startup time vs native: 该 PR 是 #50128 的准备工作之一，恢复缓存以改善 Transformers 后端启动时间。