# PR #22431 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Fix Qwen3.5 video processing when passing video_data in "processor_output" format
- 合并时间：2026-04-19 00:04
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22431

---

# 执行摘要

- 一句话：修复 Qwen3.5 视频处理在 processor_output 格式下因返回值数量不匹配导致的解包错误。
- 推荐动作：该 PR 代码量极小，适合快速浏览以理解多模态处理器中视频数据格式的接口契约。值得关注的是 `preprocess_video` 函数对两种输入路径（原始视频对象 vs 预处理字典）的统一处理设计。

# 功能与动机

根据 PR body 描述，Qwen3.5 的视频预处理函数 `preprocess_video` 需要返回两个值（视频张量和元数据），但当输入是 `processor_output` 格式（即已处理好的字典）时，函数仅返回单个值 `vr`，导致上层调用 `process_mm_data_async` 在解包时抛出 `ValueError: too many values to unpack (expected 2)`。PR 提供了完整的错误栈和复现脚本，明确了问题场景。

# 实现拆解

1. **核心逻辑修复**：修改 `python/sglang/srt/multimodal/processors/qwen_vl.py` 中的 `preprocess_video` 函数，在 `is_video_obj` 为 `False` 时（即输入为非 `VideoDecoderWrapper` 对象，如 `processor_output` 字典），将返回值从单个 `vr` 改为 `(vr, None)`，确保返回元组长度与调用方期望一致。
2. **接口一致性保证**：此修改使函数在所有输入路径下都返回 `(video_tensor, metadata)` 二元组，其中 `metadata` 在非视频对象时为 `None`，保持了与视频对象处理分支相同的接口契约。
3. **测试配套**：PR body 中提供了手动测试脚本，验证了 `processor_output` 格式和原始视频路径两种场景，但未提交自动化单元测试。

关键文件：
- `python/sglang/srt/multimodal/processors/qwen_vl.py`（模块 多模态处理器；类别 source；类型 core-logic；符号 preprocess_video）: 唯一变更文件，包含视频预处理核心逻辑，修复了返回值不匹配的关键错误。

关键符号：preprocess_video

## 关键源码片段

### `python/sglang/srt/multimodal/processors/qwen_vl.py`

唯一变更文件，包含视频预处理核心逻辑，修复了返回值不匹配的关键错误。

```python
async def preprocess_video(
    vr,
    image_factor: int = IMAGE_FACTOR,
    video_config: dict = {},
) -> torch.Tensor:
    # 预处理视频
    is_video_obj = isinstance(vr, VideoDecoderWrapper)
    if not is_video_obj:
        # 当输入是 processor_output 格式（如字典）时，返回 (vr, None) 以确保与视频对象路径接口一致
        # 修复前：return vr
        return vr, None
    entry_time = time.perf_counter()
    # ... 后续视频解码和处理逻辑，始终返回 (video_tensor, metadata)

```

# 评论区精华

Review 讨论非常简短，仅包含一次批准（`mickqian` 的 `/tag-and-rerun-ci` 命令触发 CI），未出现技术争议。这表明修复方案直接明了，被核心维护者快速接受。

- 暂无高价值评论线程

# 风险与影响

- 风险：**低风险**。变更仅涉及单个条件分支的返回值，逻辑简单且范围极小。
- **回归风险**：极低，因为只影响 `processor_output` 格式路径，且修复后行为与原始视频路径一致。
- **兼容性**：无破坏性变更，接口从返回单值改为返回二元组，但调用方本就期望二元组，因此是正向修复。
- **测试覆盖**：PR 未包含自动化测试，依赖现有 CI 和手动验证，但鉴于变更简单，风险可控。
- 影响：**影响范围有限但关键**。
- **用户影响**：修复了使用 `processor_output` 格式传入视频数据时必然发生的崩溃，提升了 Qwen3.5 多模态功能的可用性。
- **系统影响**：仅影响 `qwen_vl.py` 处理器模块的视频预处理路径，不涉及其他模型或子系统。
- **团队影响**：作为边界条件修复，无需额外培训或文档更新。
- 风险标记：边界条件修复 , 缺少自动化测试

# 关联脉络

- 暂无明显关联 PR