执行摘要

• 一句话：自动根据模型 VideoProcessor 选择视频加载后端
• 推荐动作：值得精读，了解多模态基础设施中的注册与自动发现模式。设计上保持了向后兼容（未指定 video_processor 时行为不变），是渐进式改进的范例。

功能与动机

引用 PR body：Currently, there're various VideoProcessor with different frames sampling algorithms. However, we always use the fixed frames sampling by default, and users have to specify the correct video loader by themselves through VLLM_VIDEO_LOADER_BACKEND by default, which causes a quite bad user experience. This PR enhances current video loader registration mechanism to tie the registry with VideoProcessor, which can resolve the correct video loader from model's VideoProcessor.

实现拆解

1. 在 vllm/multimodal/video.py 中创建 VideoLoaderRegistry 类继承 ExtensionManager，增加 processor2backend 字典用于维护视频处理器类名到后端名称的映射，并新增 register 方法支持传入 video_processor 参数，以及 get_backend_for_video_processor 查询方法。同时新增模块级函数 get_video_loader_backend_for_processor 作为便捷入口。
2. 将现有视频后端的注册装饰器调用都添加上对应的 video_processor 参数，例如 DynamicVideoBackend 关联 Glm4vVideoProcessor，GLMGAVideoBackend 关联 GlmgaVideoProcessor，Molmo2VideoBackend 关联 Molmo2VideoProcessor。
3. 在 vllm/transformers_utils/processor.py 中新增 get_video_processor_cls_name_from_config 函数，从 HuggingFace 的 video_preprocessor_config.json 或 preprocessor_config.json 中读取 video_processor_type 字段；并添加带 LRU 缓存的 get_video_processor_cls_name 函数，用于根据 ModelConfig 获取视频处理器类名，同时处理 GGUF 模型的特殊逻辑。
4. 在 vllm/entrypoints/chat_utils.py 的 ChatTracker 中添加 video_processor_name 属性，调用 get_video_processor_cls_name；修改 parse_video 和 _video_with_uuid_async 方法，将 video_processor_name 传递给 connector 的 fetch_video/fetch_video_async。
5. 在 vllm/multimodal/media/connector.py 的 fetch_video 和 fetch_video_async 中新增 video_processor 参数，内部通过 get_video_loader_backend_for_processor 获得后端名称，若 video_backend 未被显式指定且处理器有对应后端时，自动设置该后端，否则使用默认值。
6. 测试文件 tests/multimodal/test_video.py 增加端到端测试 test_video_processor_from_model_repo，验证 Molmo2 和 GLM-4.1V 模型能从 HuggingFace 配置正确解析出预期后端及加载器类。

关键文件：

• vllm/multimodal/video.py（模块 视频加载；类别 source；类型 core-logic；符号 VideoLoaderRegistry, init, _normalize_registered_video_processors, register）: 核心变更：将 ExtensionManager 替换为自定义 VideoLoaderRegistry，增加 processor2backend 映射和带 processor 参数的 register 方法；新增便捷查询函数；更新后端注册时绑定 processor 名称。
• vllm/transformers_utils/processor.py（模块 处理器工具；类别 source；类型 core-logic；符号 get_video_processor_cls_name_from_config, get_video_processor_cls_name）: 新增从 HuggingFace 配置解析视频处理器类名的函数，并处理 GGUF 模型特殊逻辑，为自动选择提供信息源。
• vllm/entrypoints/chat_utils.py（模块 请求入口；类别 source；类型 core-logic；符号 video_processor_name）: 在 ChatTracker 中添加 video_processor_name 属性，并在 parse_video 方法中传递该信息，连接自动选择逻辑与请求处理。
• vllm/multimodal/media/connector.py（模块 媒体连接；类别 source；类型 dependency-wiring；符号 fetch_video, fetch_video_async）: 在 fetch_video 和 fetch_video_async 中增加 video_processor 参数，并根据该参数自动设置 video_backend，实现后端的自动选择。
• tests/multimodal/test_video.py（模块 视频测试；类别 test；类型 test-coverage；符号 test_video_processor_from_model_repo）: 新增集成测试，验证 Molmo2 和 GLM-4.1V 模型能从 HuggingFace 配置正确解析出预期后端及加载器类。

关键符号：VideoLoaderRegistry.init, VideoLoaderRegistry.register, VideoLoaderRegistry.get_backend_for_video_processor, get_video_loader_backend_for_processor, get_video_processor_cls_name_from_config, get_video_processor_cls_name, ChatTracker.video_processor_name, MediaConnector.fetch_video, MediaConnector.fetch_video_async

关键源码片段

vllm/multimodal/video.py

核心变更：将 ExtensionManager 替换为自定义 VideoLoaderRegistry，增加 processor2backend 映射和带 processor 参数的 register 方法；新增便捷查询函数；更新后端注册时绑定 processor 名称。

class VideoLoaderRegistry(ExtensionManager):
    def __init__(self) -> None:
        super().__init__()
        # 维护视频处理器类名到后端名称的映射
        self.processor2backend: dict[str, str] = {}
​
    @staticmethod
    def _normalize_registered_video_processors(
        video_processor: str | tuple[str, ...] | None,
    ) -> tuple[str, ...]:
        if video_processor is None:
            return ()
        if isinstance(video_processor, str):
            return (video_processor,)
        if all(isinstance(processor, str) for processor in video_processor):
            return video_processor
        raise TypeError(
            "video_processor must be a class name or a tuple of class names"
        )
​
    def register(
        self,
        name: str,
        *,
        video_processor: str | tuple[str, ...] | None = None,
    ):
        # 标准化传入的处理器名称列表
        processors = self._normalize_registered_video_processors(video_processor)
        def wrap(cls_to_register):
            # 注册类到 name2class（继承自 ExtensionManager）
            self.name2class[name] = cls_to_register
            # 将每个处理器名称映射到当前后端名称
            for processor_name in processors:
                self.processor2backend[processor_name] = name
            return cls_to_register
        return wrap
​
    def get_backend_for_video_processor(
        self,
        video_processor: str | None,
    ) -> str | None:
        if video_processor is None:
            return None
        return self.processor2backend.get(video_processor)
​
​
# 模块级便捷函数，供外部直接调用
def get_video_loader_backend_for_processor(
    video_processor: str | None,
) -> str | None:
    return VIDEO_LOADER_REGISTRY.get_backend_for_video_processor(video_processor)

vllm/transformers_utils/processor.py

新增从 HuggingFace 配置解析视频处理器类名的函数，并处理 GGUF 模型特殊逻辑，为自动选择提供信息源。

def get_video_processor_cls_name_from_config(
    processor_name: str,
    revision: str | None = "main",
) -> str | None:
    """从 HuggingFace 配置中读取 video_processor_type 字段。"""
    processor_name = convert_model_repo_to_path(processor_name)
    config_file = [
        "video_preprocessor_config.json",
        "preprocessor_config.json",
    ]
    for file in config_file:
        config = get_hf_file_to_dict(file, processor_name, revision=revision)
        if config and "video_processor_type" in config:
            return config["video_processor_type"]
    return None
​
​
# 带 LRU 缓存的版本，避免重复网络请求
_cached_get_video_processor_cls_name = lru_cache(
    get_video_processor_cls_name_from_config
)
​
​
def get_video_processor_cls_name(
    model_config: "ModelConfig",
) -> str | None:
    """根据模型配置获取视频处理器类名，支持 GGUF 特殊处理。"""
    if is_gguf(model_config.model):
        # GGUF 模型使用 tokenizer 路径来获取 HuggingFace 配置
        assert not is_gguf(model_config.tokenizer), (
            "For multimodal GGUF models, the original tokenizer "
            "should be used to correctly load video processor metadata."
        )
        model = model_config.tokenizer
        revision = model_config.tokenizer_revision
    else:
        model = model_config.model
        revision = model_config.revision
    return _cached_get_video_processor_cls_name(model, revision=revision)

评论区精华

无实质讨论，PR 获得一次审批通过（DarkLight1337）。

• 暂无高价值评论线程

风险与影响

• 风险：
  1. 新增的 HuggingFace 配置读取依赖网络，若离线环境无法访问 Hub，get_video_processor_cls_name_from_config 可能失败，但函数内部已处理 None 返回，且连接器层在获取到 None 时不覆盖 video_backend，因此会回退到默认行为（opencv 等），不构成硬失败。
  2. 需要保证所有视频后端注册时都正确指定了 video_processor 参数，否则自动选择无法生效。当前仅三个后端完成绑定，后续新增的后端需要遵循此模式。
  3. 如果 HuggingFace 配置中的 video_processor_type 与注册时使用的名称不匹配，将导致自动选择失败，但仍是静默回退，不影响流程。
     - 影响：对用户：自动选择后端，消除了手动设置环境变量的需要，降低了视频模型推理的配置门槛。对系统：视频加载路径的决策点提前到 parse_video 阶段，但逻辑简单，性能影响可忽略。对团队：增加了新的注册约束，需要所有视频后端注册时指定 video_processor，有利于统一管理。
     - 风险标记：配置解析依赖 HuggingFace, 新注册模式需要推广

关联脉络

• 暂无明显关联 PR