执行摘要

• 一句话：新增 VidCom2 视频 token 剪枝方法
• 推荐动作：推荐关注该 PR 的设计模式，特别是统一参数接口 get_video_pruning_spec()、协议方法声明 supported_video_pruning_methods、配置 fail-fast 校验等，可作为后续功能扩展的模板。

功能与动机

VidCom2 (Video Compression Commander) 是一种训练无关视频 token 剪枝方法，相比 EVS 在相同压缩率下能更好保留关键帧信息，提升下游任务准确率。作者在 H100 上的 500 MCQ 测试显示 VidCom2 一致优于 EVS。参考论文《Video Compression Commander: Plug-and-Play Inference Acceleration for Video Large Language Models》(EMNLP 2025)。

实现拆解

1. 创建核心剪枝模块 (vllm/multimodal/video_prune/vidcom2.py，新增 124 行)：实现 compute_retained_tokens_count 和 compute_retention_mask。算法步骤：低方差通道选取 → 多尺度高斯相似性 → 动态每帧预算 (softmax) → 每帧保留最低相似性 token → 精确计数协调。

2. 配置层统一参数 (vllm/config/multimodal.py)：新增 VideoPruningMethod = Literal['evs', 'vidcom2']；MultiModalConfig 新增 video_pruning_method 字段；添加 get_video_pruning_spec() 返回 (method, rate) 元组。

3. 模型接口与校验：在 SupportsMultiModalPruning 协议中添加 supported_video_pruning_methods 类变量；ModelConfig.__post_init__ 中实现 fail-fast 校验。

4. 模型集成与导入迁移：qwen3_vl.py 根据 pruning_spec 选择 vidcom2 或 evs 函数；同时迁移 evs 导入路径至 video_prune 子目录，更新所有引用该路径的模型。

5. 引擎参数与测试文档：arg_utils.py 添加 --video-pruning-method；新增 tests/multimodal/test_vidcom2.py (7 个测试)；更新 docs/features/multimodal_inputs.md 和 docs/design/cuda_graphs_multimodal.md。

关键文件：

• vllm/multimodal/video_prune/vidcom2.py（模块 核心剪枝；类别 source；类型 core-logic；符号 compute_retained_tokens_count, compute_retention_mask, _multi_scale_gaussian）: 核心 VidCom2 剪枝算法实现，包含 compute_retained_tokens_count 和 compute_retention_mask
• tests/multimodal/test_vidcom2.py（模块 测试；类别 test；类型 test-coverage；符号 _fake_video_embeds, test_mask_shape_and_dtype, test_retained_count_floors_at_one_token_per_frame, test_total_retained_matches_target）: VidCom2 核心单元测试，覆盖掩码形状、计数匹配、动态预算、空输入等关键场景
• vllm/config/multimodal.py（模块 配置层；类别 source；类型 core-logic；符号 get_video_pruning_spec, VideoPruningMethod）: 配置层统一参数和 VideoPruningMethod 类型定义，提供 get_video_pruning_spec 接口
• vllm/model_executor/models/qwen3_vl.py（模块 模型集成；类别 source；类型 data-contract；符号 _init_video_pruning）: Qwen3-VL 模型集成：导入 vidcom2 并根据 pruning_spec 选择对应函数，同时迁移 evs 导入路径
• vllm/config/model.py（模块 配置层；类别 source；类型 data-contract）: 模型配置校验：在 post_init 中检查选中的剪枝方法是否被模型支持
• vllm/model_executor/models/interfaces.py（模块 接口协议；类别 source；类型 data-contract）: 协议接口添加 supported_video_pruning_methods 类变量，使模型声明支持的方法

关键符号：compute_retained_tokens_count, compute_retention_mask, _multi_scale_gaussian, get_video_pruning_spec, _init_video_pruning

评论区精华

• 命名争论：作者最初引入 video_retention_ratio，Isotr0py 认为易混淆，建议使用 video_pruning_method + 共享 video_pruning_rate，作者采纳。
• 验证时机：Isotr0py 建议在模型加载时校验而非 model runner 中 panic，最终在 ModelConfig.__post_init__ 实现 fail-fast。
• 目录结构：Isotr0py 提议创建 video_prune 子目录，作者实施并迁移 evs。

• 文档并发使用：2ez4bz 询问是否允许两种方法同时使用，确认互斥。

• 参数命名：video_retention_ratio vs pruning_method + pruning_rate (design): 作者采纳，移除 retention_ratio，统一为 pruning_method + pruning_rate

• 校验时机：模型加载时 vs model runner (design): 在 ModelConfig.post_init 中实现快速失败校验
• 目录结构：创建 video_prune 子目录 (other): 创建 vllm/multimodal/video_prune/ 并将 evs 和 vidcom2 均移入该目录
• 文档：是否允许两种方法并发使用 (documentation): 确认参数互斥，通过 --video-pruning-method 选择单一方法

风险与影响

• 风险：
  • 回归风险：evs 导入路径从 vllm.multimodal.evs 改为 vllm.multimodal.video_prune.evs，涉及至少 5 个模型文件，若遗漏更新会导致 ImportError。当前已全部更新，但需仔细审查。
  • 性能风险：VidCom2 的多尺度高斯计算开销略大，作者报告 TTFT 与 EVS 持平，但未在更长视频或更大模型上验证。
  • 兼容性：新参数 video_pruning_method 默认 "evs"，向后兼容；旧参数 video_retention_ratio 已移除。
  • 测试覆盖：单元测试使用伪造数据，未覆盖真实 ViT 输出；缺少端到端 GPU 正确性测试。
• 影响：
  • 用户：可通过 --video-pruning-method vidcom2 选用更高准确率的剪枝方法，但需注意模型支持情况。
  • 系统：视频剪枝框架扩展性增强，未来新增方法只需实现两个函数并在模型声明中添加即可。
  • 团队：维护成本略有增加，但模块化设计降低了长期风险。
  • 风险标记：evs 导入路径迁移, 缺少 GPU 测试覆盖, 配置参数新增

关联脉络

• PR #29752 Add EVS video token pruning: VidCom2 是 EVS 的扩展，共享相同的接口和配置机制；该 PR 引入了 EVS 基础框架