执行摘要

• 一句话：为 Minimax-M3 添加默认视频处理器
• 推荐动作：值得关注的设计：注册器支持 video_processor 名称检索模式，以及帧索引对齐 HF 的策略。但需特别注意导入依赖的隐性风险，建议在合并前验证模块的独立导入能力。此 PR 被回滚后仍需修复导入问题再重新提交。

功能与动机

PR body 提到：为 minimax-m3 添加 MiniMaxM3VLVideoProcessor，自动为 VLM 选择注册的视频加载器。关联的 #44126 已合并。

实现拆解

1. 注册 video_processor 名称：在 mm_preprocess.py 中将 @VIDEO_LOADER_REGISTRY.register("minimax_m3_vl") 扩展为带 name 和 video_processor 参数的调用，使后端可通过处理器名检索。
2. 新增 load_bytes 方法：在 MiniMaxM3VideoBackend 类中添加 load_bytes 类方法，直接调用父类 VideoBackend.load_bytes，透传所有参数，确保视频解码走标准路径。
3. 修正帧索引对齐 HF：修改 compute_frames_index_to_sample 中 last_frame_idx 从 total_frames - 1 改为 total_frames，使得最后一帧被包含，匹配 Hugging Face 的 sample_frames 行为；同时添加注释说明。
4. 补充测试用例：在 test_video.py 中导入 MiniMaxM3VideoBackend，并在参数化测试 test_video_processor_from_model_repo 中加入 MiniMaxAI/MiniMax-M3 的条目，验证注册与帧索引对齐是否正确。

关键文件：

• vllm/models/minimax_m3/common/mm_preprocess.py（模块 视频加载器；类别 source；类型 data-contract；符号 load_bytes, MiniMaxM3VideoBackend, compute_frames_index_to_sample）: 核心变更文件：注册 video_processor 名称，新增 load_bytes 方法，调整帧索引计算以对齐 HF 标准。
• tests/multimodal/test_video.py（模块 视频测试；类别 test；类型 test-coverage；符号 MiniMaxM3VideoBackend）: 测试配套：导入 MiniMaxM3VideoBackend 并在参数化测试中添加 MiniMax-M3 用例，验证注册和帧索引对齐。

关键符号：load_bytes, compute_frames_index_to_sample, MiniMaxM3VideoBackend

关键源码片段

vllm/models/minimax_m3/common/mm_preprocess.py

核心变更文件：注册 video_processor 名称，新增 load_bytes 方法，调整帧索引计算以对齐 HF 标准。

# 文件 : vllm/models/minimax_m3/common/mm_preprocess.py
# 修改点：注册装饰器增加 video_processor 参数，使后端可通过处理器名检索
@VIDEO_LOADER_REGISTRY.register(
    name="minimax_m3_vl",
    video_processor="MiniMaxM3VLVideoProcessor", # 新增参数，关联处理器类名
)
class MiniMaxM3VideoBackend(VideoBackend):
​
    @classmethod
    def load_bytes(
        cls,
        data: bytes,
        num_frames: int = -1,
        fps: int = 1,
        max_duration: int = 300,
        frame_recovery: bool = False,
        *,
        backend: Literal[
            "opencv",
            "pyav",
            "torchcodec",
            "pynvvideocodec",
            "deepstream",
        ] = "opencv",
        **kwargs,
    ) -> tuple[npt.NDArray, dict[str, Any]]:
        # 直接调用父类 VideoBackend.load_bytes，透传所有参数
        return super().load_bytes(
            data,
            num_frames=num_frames,
            fps=fps,
            max_duration=max_duration,
            frame_recovery=frame_recovery,
            backend=backend,
            **kwargs,
        )
​
    @classmethod
    def compute_frames_index_to_sample(
        cls,
        source: VideoSourceMetadata,
        target: VideoTargetMetadata,
        **kwargs,
    ) -> list[int]:
        total_frames = source.total_frames_num
        video_fps = source.original_fps
        fps = target.fps
        if total_frames <= 0 or video_fps <= 0 or fps <= 0:
            return [0] if total_frames > 0 else []
        # ... ( 中间的帧索引计算逻辑省略 ) ...
        # 关键修改：last_frame_idx 从 total_frames-1 改为 total_frames
        # 以匹配 Hugging Face 的 sample_frames 行为（包含最后一帧）
        last_frame_idx = total_frames # 原值为 total_frames - 1
        last_ts = last_frame_idx / video_fps
        if indices and indices[-1] != last_frame_idx and last_ts - prev_kept_ts > eps:
            indices.append(last_frame_idx)
        if not indices:
            indices = [0]
        return indices

评论区精华

Reviewer Isotr0py 建议不要新建独立的测试函数，而是直接扩展已有的参数化测试，作者采纳并在后续提交中修改。此外，Isotr0py 表示这两个 PR 同时提出，他漏掉了该注册。合并后 bbrowning 报告主分支出现导入错误，njhill 回滚了提交。

• 测试结构优化 (testing): 作者采纳建议，在后续提交中移除了独立测试函数，扩展了 test_video_processor_from_model_repo 的参数化列表。

风险与影响

• 风险：主要风险在于导入依赖：mm_preprocess.py 新增了 numpy.typing 导入，且注册逻辑依赖于 vllm.models.minimax_m3 包的 __init__.py，若该包未正确加载或存在循环依赖，会导致模块导入崩溃（实际合并后即出现此问题）。此外，帧索引计算变更（last_frame_idx 从 total_frames-1 改为 total_frames）可能影响视频帧序列长度，已通过测试对齐 HF，但仍需确认无旧版兼容问题。
• 影响：影响范围仅限于 Minimax-M3 模型：启用后模型自动使用注册的默认视频后端，用户无需手动指定 video_processor。框架层面，注册表新增一个绑定，不影响其他模型的视频处理流程。对团队的影响是增加了维护成本，需确保 vllm.models.minimax_m3 包的导入稳定性。
• 风险标记：隐式导入依赖, 回归风险, 被回滚

关联脉络

• PR #44126 Add MiniMaxM3VLVideoProcessor: 此 PR 基于该 PR 引入的处理器类，被 PR body 引用。
• PR #50313 Revert "[Misc][Minimax-M3]add default video_processor (#50092)": 回滚此 PR，因为合并后导致主分支导入错误。