执行摘要
- 一句话：修复 Gemma4 多分辨率图像并发批处理崩溃
- 推荐动作：此 PR 代码量小但设计精准，修复了一个实际的多模态并发崩溃，且审查中讨论的设计取舍（zip vs unbind）具有参考价值。建议精读
gemma4_mm.py 中 Gemma4ImagePixelInputs 的变更和 _process_image_input 的新迭代方式，其余文件可作为示例。
功能与动机
Issue #39681 报告了当不同分辨率的图像请求并发到达同一调度步骤时，Gemma4 图像编码器崩溃，错误信息为 pixel_values contains inconsistent shapes。根因是 MultiModalBatchedField._reduce_data 在图像张量形状不一致时返回 list[Tensor]，而 Gemma4 的输入 schema 仅接受统一 np 维度的 torch.Tensor，导致验证失败。
实现拆解
- 修改数据契约：在
vllm/model_executor/models/gemma4_mm.py 的 Gemma4ImagePixelInputs 类中，将 pixel_values 和 pixel_position_ids 的类型注解由 torch.Tensor 改为 torch.Tensor | list[torch.Tensor]，并在 TensorShape 中添加 dynamic_dims={"np"}，使得变长 patch 维度的输入不再被拒绝。
- 调整迭代逻辑：在同一文件的
_process_image_input 方法中，原本使用 for i in range(pixel_values.shape[0]) 按序号索引的方式已被替换为 for pv, pp in zip(pixel_values, pixel_position_ids, strict=True)，该模式天然兼容统一堆叠张量（按批维度迭代）和列表张量（直接迭代元素），无需显式类型判断。
- 补充回归测试：在
tests/models/multimodal/processing/test_gemma4.py 中新增两个测试用例 —— test_gemma4_image_schema_accepts_variable_patch_counts 验证 schema 构造时可以传入不同 patch 数的列表张量；test_gemma4_image_batching_keeps_variable_patch_counts_unstacked 验证 MultiModalFieldConfig.batched 的 reduce_data 在变长场景下正确返回列表而非强制堆叠，确保批处理降级行为与预期一致。
关键文件：
vllm/model_executor/models/gemma4_mm.py（模块 多模态处理；类别 source；类型 data-contract；符号 Gemma4ImagePixelInputs, _process_image_input）: 核心变更：修改输入 schema 支持列表张量，并调整迭代逻辑以兼容两种输入形式。tests/models/multimodal/processing/test_gemma4.py（模块 测试用例；类别 test；类型 test-coverage；符号 test_gemma4_image_schema_accepts_variable_patch_counts, test_gemma4_image_batching_keeps_variable_patch_counts_unstacked）: 测试覆盖变长 patch 输入的 schema 验证和批处理降级行为。
关键符号：_process_image_input, test_gemma4_image_schema_accepts_variable_patch_counts, test_gemma4_image_batching_keeps_variable_patch_counts_unstacked
评论区精华
审查中包含两个主要讨论线程：
- 输入列表转换方式的选择（
gemini-code-assist[bot]）：建议使用 torch.unbind(0) 将堆叠张量转换为列表，认为更符合 PyTorch 习惯且高效。作者最终选择直接使用 zip 迭代，未显式转换张量形式，从而避免额外的内存分配，同时保持代码简洁。
-
Schema 变更后的迭代逻辑改造必要性（Isotr0py）：质疑仅 schema 变更是否足够，为何需要修改迭代逻辑。作者解释 schema 变更使输入类型变为联合类型后，旧式基于 .shape[0] 的索引循环无法直接用于列表，必须改为迭代；采用 zip 既可保持对统一堆叠张量的向后兼容，又能自然扩展支持列表输入，避免了不必要的张量转换。
-
输入列表转换方式的选择 (design): 作者未采纳，选择直接使用 zip 迭代，无需转换张量形式，保持与列表张量的兼容。
- Schema 变更后的迭代逻辑改造必要性 (question): 作者解释 schema 变更使输入可能是列表，旧基于 shape 的索引循环失效，必须改为迭代；使用 zip 可同时兼容张量和列表。
风险与影响
- 风险：风险较低，但需注意以下几点：
- 数据契约变更：将字段类型从严格
torch.Tensor 放宽为联合类型，若下游其他处理逻辑（如自定义插件）仍假定为单一 Tensor，可能触发类型错误。但当前 Gamme4 内部使用已全部适配，测试覆盖了两种形式。
- 动态维度标记：
TensorShape 中新增 dynamic_dims={"np"} 会影响该 schema 的验证行为，可能让之前被拦截的形状不匹配错误变为静默通过，但本意正是需要这种宽松。
- 性能影响：列表迭代相比统一张量索引在极高频场景下可能存在微小的解释器开销，但混合分辨率并发本身就是低频偶发事件，且
zip 在 PyTorch 张量上的迭代性能与序身号循环基本持平，因此无实际风险。
- 测试局限性：回归测试仅验证了 schema 构造和批处理降级，未覆盖端到端推理流程，但 PR 描述中附有运行成功的手动验证结果（10 轮 × 16 并发，160/160 成功）。
- 影响：
- 用户：修复了 Gemma4 多模态模型在图像分辨率混合场景下的崩溃问题，用户现在可以可靠地并发提交不同尺寸的图像，无需手动分批。
- 系统：变更仅限 Gemma4 相关模块（
gemma4_mm.py 和 test_gemma4.py），不涉及模型运行器、调度器等核心组件，影响范围可控。
- 团队：提供了一个清晰的示例，说明如何通过
TensorSchema 的 dynamic_dims 和联合类型优雅地支持多模态输入的变长批处理，后续其他模型遇到类似问题时可直接复用此模式。
- 风险标记：多模态批处理核心路径, 数据契约类型扩展
关联脉络
参与讨论