执行摘要

• 一句话：支持客户端传递自定义视频元数据以保留时序信息
• 推荐动作：建议精读此 PR，特别是 load_base64 中的元数据传递模式，可作为多模态管道中客户端-服务器协作的参考。注意验证逻辑相对简单，生产使用前应补充更严格的校验和测试。

功能与动机

当用户客户端提取帧并发送为video/jpeg（base64拼接的JPEG帧）时，服务器之前丢失了原始视频上下文。此更改允许客户端传递帧索引、总帧数、时长、帧率等元数据，从而通过保留时序信息实现更准确的视频理解。

实现拆解

1. 参数提取与验证：在vllm/multimodal/media/video.py的load_base64方法中，新增从self.kwargs提取frames_indices、total_num_frames、duration、do_sample_frames的逻辑，并添加了基本类型和范围校验。

2. 元数据构造：使用提取的参数构造metadata字典，替代原来基于实际帧数硬编码的默认值。关键实现片段如下：

3. 文档更新：在docs/features/multimodal_inputs.md中新增“Pre-extracted Frame Sequences with media_io_kwargs”章节，说明每个参数的含义并提供完整示例代码。

关键文件：

• vllm/multimodal/media/video.py（模块 视频处理；类别 source；类型 core-logic；符号 load_base64）: 核心实现文件，修改了 load_base64 方法，增加了视频元数据参数提取、验证和元数据构造逻辑。
• docs/features/multimodal_inputs.md（模块 文档；类别 docs；类型 documentation）: 文档更新，新增 media_io_kwargs 的使用说明和示例，帮助用户理解如何传递视频元数据。

关键符号：load_base64

关键源码片段

vllm/multimodal/media/video.py

核心实现文件，修改了 load_base64 方法，增加了视频元数据参数提取、验证和元数据构造逻辑。

# 从 self.kwargs 中提取 frames_indices
frames_indices = self.kwargs.get("frames_indices")
if frames_indices is not None:
    # 验证 frames_indices 必须为整数列表且长度与实际帧数一致
    if not (isinstance(frames_indices, list) and all(isinstance(i, int) for i in frames_indices)):
        raise ValueError("frames_indices must be a list of integers")
    if len(frames_indices) != total:
        raise ValueError(f"frames_indices length ({len(frames_indices)}) must match number of frames sent ({total})")
else:
    frames_indices = list(range(total))
​
# 提取 total_num_frames，默认为实际帧数 total
total_num_frames = self.kwargs.get("total_num_frames", total)
if not isinstance(total_num_frames, int) or total_num_frames < 1:
    raise ValueError("total_num_frames must be a positive integer")
if total_num_frames < total:
    raise ValueError(f"total_num_frames ({total_num_frames}) must be >= number of frames sent ({total})")
​
# 提取 duration，若未提供则根据 total_num_frames 和 fps 计算
duration = self.kwargs.get("duration")
if duration is not None:
    if not isinstance(duration, (int, float)) or duration < 0:
        raise ValueError("duration must be a non-negative number")
else:
    duration = total_num_frames / fps if fps > 0 else 0.0
​
# 构造元数据字典，do_sample_frames 默认为 False
metadata = {
    "total_num_frames": total_num_frames,
    "fps": fps,
    "duration": duration,
    "video_backend": "jpeg_sequence",
    "frames_indices": frames_indices,
    "do_sample_frames": self.kwargs.get("do_sample_frames", False),
}

评论区精华

1. 参数验证必要性：gemini-code-assist 指出需要对 frames_indices 和 total_num_frames 进行验证，否则可能导致时序错误。作者随后添加了类型和长度校验。
2. do_sample_frames 默认值：gemini-code-assist 建议根据 frames_indices 是否覆盖全部帧动态决定默认值，但作者认为原默认值 False 适用于预提取序列场景，保持向后兼容。
3. frames_indices 语义：Isotr0py 询问 frames_indices 是否应仅加载目标帧，作者澄清其为输出元数据（记录已加载帧的位置），与 load_bytes 的 create_hf_metadata 行为一致。

• frames_indices 长度校验 (correctness): 作者添加了类型和长度校验，确保 frames_indices 为整数列表且长度等于 total。
• do_sample_frames 默认值设计 (design): 作者认为原默认值 False 适用于预提取场景，保持向后兼容，未采纳建议。
• frames_indices 是输入还是输出 (question): 作者澄清 frames_indices 为输出元数据，记录已加载帧的位置，与现有 load_bytes 行为一致。

风险与影响

• 风险：

  1. 输入验证风险：当前验证仅检查类型和基本范围（如 total_num_frames >= total），未验证 frames_indices 是否递增或非负，极端输入可能影响模型推理。
  2. 缺少测试覆盖：无新增单元测试或集成测试，变更仅通过人工审查，回归风险较高。
  3. 兼容性风险：新增参数均为可选，默认行为与之前相同（frames_indices 默认为 range(total)，do_sample_frames 默认为 False），但若客户端错误传递参数（如 frames_indices 长度不匹配），会抛出 ValueError，可能破坏现有工作流。
     - 影响：用户：允许在客户端提取帧时保留视频元数据，提升视频理解准确性；使用方式通过 extra_body.media_io_kwargs.video 传递，需要用户知晓 API。
     系统：仅增加少量参数提取和验证开销，对性能无显著影响。
     团队：需维护文档示例，未来若调整验证逻辑需确保向后兼容。

• 风险标记：缺少测试覆盖, 核心路径变更

关联脉络

• 暂无明显关联 PR