# PR #39232 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Docs] Add Phi-4-reasoning-vision to supported models + examples 
- 合并时间：2026-04-08 10:02
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/39232

---

# 执行摘要
该 PR 为 Phi-4-reasoning-vision 模型（Phi4ForCausalLMV 类）添加了文档支持和离线推理示例，扩展了 vLLM 对多模态模型的支持。主要变更包括更新支持模型列表和新增单图 / 多图示例脚本，但多图示例中的 `max_model_len` 参数设置可能不足，存在使用风险。

# 功能与动机
根据 PR body，目的是将 Phi4ForCausalLMV 添加到支持的模型列表中，并补充示例脚本。作者提到该模型类已在模型注册表中注册，但缺少文档和示例，因此需要补充以提升用户体验。这符合 vLLM 持续扩展模型支持范围的趋势。

# 实现拆解
实现分为三个文件：
1. **docs/models/supported_models.md**：在表格中新增一行，记录模型类 `Phi4ForCausalLMV`、名称 `Phi-4-reasoning-vision`、模态 `T + I⁺` 和示例模型 `microsoft/Phi-4-reasoning-vision-15B`。
2. **examples/offline_inference/vision_language.py**：新增 `run_phi4siglip` 函数，用于单图推理。关键代码：
   ```python
   def run_phi4siglip(questions: list[str], modality: str) -> ModelRequestData:
       assert modality == "image"
       model_name = "microsoft/Phi-4-reasoning-vision-15B"
       prompts = [f"<|user|>\n<image>\n{question}<|end|>\n<|assistant|>\n" for question in questions]
       engine_args = EngineArgs(
           model=model_name,
           trust_remote_code=True,
           max_model_len=8192,
           max_num_seqs=2,
           limit_mm_per_prompt={modality: 1},
       )
   ```
3. **examples/offline_inference/vision_language_multi_image.py**：新增 `load_phi4siglip` 函数，用于多图推理。设置类似，但 `limit_mm_per_prompt={"image": len(image_urls)}`。

# 评论区精华
review 中仅有一条来自 gemini-code-assist[bot] 的评论，指出多图示例中的 `max_model_len` 设置问题：
> "The current `max_model_len=8192` is insufficient for the multi-image capabilities demonstrated in this script. Each image in Phi-4-reasoning-vision can consume up to 3600 tokens. With the current limit, the engine will fail to initialize or crash if 3 or more images are provided (3 * 3600 = 10800 > 8192), even though the script provides 12 sample URLs. Increasing this value to at least 16384 would allow for up to 4 images, though users should be aware of the increased KV cache memory requirements for a 15B model."

该评论未被回复或采纳，PR 最终以原代码合并。

# 风险与影响
- **风险**：多图示例中的 `max_model_len=8192` 可能不足，当用户提供 3 个或更多图像时，引擎可能因 token 数超限而崩溃。这属于示例脚本的使用风险，而非核心代码缺陷。
- **影响**：对用户正面，提供了新模型的文档和示例，降低了使用门槛；对系统无直接影响；对团队而言，延续了多模态模型支持扩展的趋势。

# 关联脉络
- 与近期 PR 如 #38755（迁移 Responses API 解析器）和 #38848（修复 Qwen3 工具解析器）相关，同属前端和模型支持改进。
- 这反映了 vLLM 在 v1 版本中持续丰富模型生态，特别是多模态和工具调用方向。