# PR #20081 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[Diffusion] map each prompt to corresponding image in multi-prompt scenario
- 合并时间：2026-03-10 16:58
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/20081

---

# 执行摘要
本 PR 为 sglang 仓库的扩散模型添加了多提示与多图像的映射支持，扩展了图像编辑功能覆盖单提示单图像、单提示多图像、多提示多图像和多提示单图像四种场景。通过引入 `per_prompt_images` 字段并在编码和生成阶段路由图像，当前以 QwenImageEditPlus 模型为例实现，但设计为通用可扩展。变更涉及模型配置、生成器和编码核心逻辑，并添加了 CLI 测试验证。推荐关注其错误处理设计和兼容性指导。

# 功能与动机
PR 的动机源自增强扩散模型在复杂图像编辑任务中的灵活性。作者在 PR body 中明确列出了四种需支持的场景：
- 单提示 + 单图像：基础编辑。
- 单提示 + 多图像：图像合成（所有图像用于一个提示）。
- 多提示 + 多图像：每个提示处理对应图像（例如批量编辑）。
- 多提示 + 单图像：每个提示使用同一图像。
这解决了现有实现可能无法正确处理多提示与多图像映射的问题，提升用户体验和任务多样性。

# 实现拆解
实现分为三个层次：
1. **模型配置层（`qwen_image.py`）**：新增辅助函数规范化提示和图像列表，核心函数 `_resolve_qwen_edit_per_prompt_images` 根据输入长度计算 `per_prompt_images`，例如当多提示对应多图像时返回 `[[image1], [image2], ...]`。在 `prepare_image_processor_kwargs` 中集成该逻辑并返回字典。
2. **生成器层（`diffusion_generator.py`）**：添加 `_resolve_image_paths_per_prompt` 静态方法，在生成请求前解析图像路径，支持错误检查（如长度不匹配时抛出 `ValueError`）。代码片段：
   ```python
   if len(image_paths) != len(prompts):
       raise ValueError("When using multiple prompts with multiple input images, provide either one shared image or exactly one image per prompt.")
   ```
3. **编码阶段（`image_encoding.py`）**：修改 `forward` 方法，从 kwargs 提取 `per_prompt_images` 和 `text`，通过循环 `for idx, prompt_images in enumerate(per_prompt_images):` 处理每个提示的图像编码，兼容图像编码器和文本编码器路径。
此外，新增 `test_generate_i2i.py` 测试文件覆盖四种场景的 CLI 测试，确保功能正确性。

# 评论区精华
Review 讨论聚焦于两个关键点：
- **通用性**：mickqian 提问“does this logic works for other models as well?”，RuixiangMa 回复已验证 flux2-klein 模型无需修改，并解释“Only Text Encoder pipelines (e.g., QwenImageEdit) require adaptation. Other pipelines use the VAE path, carrying images independently per request.”结论是设计通用，但其他模型需按文档适配。
- **测试策略**：mickqian 建议“could we use unit test instead? the cli test should be kept as lightweight”，RuixiangMa 回应“Done, the test file is kept but removed from the CI suite. It can be run manually when needed”。这反映了团队在测试覆盖与 CI 效率间的权衡。

# 风险与影响
**技术风险**：
- 错误处理新增可能未充分集成到所有调用路径，导致服务异常。
- 循环编码在大量提示场景下增加计算和内存开销，需监控性能回归。
- 兼容性风险：其他模型若未正确实现 `prepare_image_processor_kwargs`，可能引入功能不一致。

**影响范围**：
- 用户受益于更灵活的编辑能力，但需注意输入格式要求。
- 系统扩展数据流，轻微增加复杂度，但通过向后兼容设计减少破坏性变更。
- 团队需跟进适配指南，测试策略调整可能影响自动化验证。

# 关联脉络
从近期历史 PR 看，本 PR 是扩散模块功能扩展的一部分。例如，PR #21387 “Optimize diffusion Triton rotary embedding” 侧重于性能优化，与本 PR 的功能增强形成互补，共同推动扩散模型能力的演进。本 PR 为其他模型提供了通用接口指导，未来可能引发更多模型适配的后续工作，延续仓库在扩散和多模态生成领域的投入趋势。