执行摘要

本 PR 修复了多模态生成服务器在启动时使用 --warmup 参数时，多个工作秩并发读写图像文件导致的间歇性加载失败问题。通过引入共享 warmup 图像路径和广播同步机制，确保秩安全初始化，提升了系统启动的稳定性和可靠性。此变更聚焦于调度器模块，代码精简但设计巧妙，值得团队借鉴其分布式协调模式。

功能与动机

在服务器启动过程中，当配置 --warmup 和 --warmup-resolutions 时，warmup 请求会在每个工作秩上准备。对于图像条件任务（如 I2I、TI2I、I2V、TI2V），多个秩可能同时访问相同的 warmup 图像路径，引发 PIL.UnidentifiedImageError（例如 "cannot identify image file 'outputs/uploads/warmup_image.jpg.jpg'"），具体错误日志已在 PR body 中提供。此问题在硬件速度差异或时机巧合时出现，影响服务器启动成功率。本 PR 旨在使 warmup 图像准备具有确定性和秩安全性，消除并发读写风险。

实现拆解

主要改动集中在文件 python/sglang/multimodal_gen/runtime/managers/scheduler.py：

1. 重构 prepare_server_warmup_reqs 方法：

   • 使用 task_type.accepts_image_input() 动态判断是否需要图像输入，替代硬编码的任务类型列表，提升代码可维护性和一致性。
   • 对于需要图像的任务，调用新增的 _prepare_shared_warmup_image_path 方法获取共享路径。

2. 新增 _prepare_shared_warmup_image_path 私有方法：

   • 确定图像保存目录：优先使用 server_args.input_save_path（如配置），否则创建临时目录（前缀为 sglang_input_）。
   • 在主秩（rank 0）上生成 warmup 图像，通过 save_image_to_path 将 base64 编码图像保存到路径。
   • 使用 broadcast_pyobj 将路径或错误信息广播到所有秩，确保一致性。关键代码逻辑如下：
     python warmup_sync = broadcast_pyobj( warmup_sync, world_group.rank, world_group.cpu_group, src=src_rank, )
   • 错误处理：如果主秩准备失败，传播异常；否则返回共享路径供所有秩使用。

3. 目录处理优化：通过两个提交迭代，确保目录逻辑与服务器配置保持一致，避免路径冲突。

评论区精华

review 过程中，审阅者与作者就几个关键点进行了深入讨论：

• 正确性检查：mickqian 提问：“is it equivalent to accepts_image_input?”，IPostYellow 回应：“Good catch. Yes, this check should align with task-type semantics. I’ll replace the hard-coded task tuple with task_type.accepts_image_input()”。最终代码采用动态检查，避免了重复逻辑。

• 设计权衡：mickqian 建议：“extract a method from the endpoint file, to make sure the directory is consistent”，IPostYellow 解释：“I tested a shared helper, but for this PR I kept it inline to minimize scope/risk... Maybe helper extraction can be done in a separate cleanup PR.”。这体现了 PR 范围控制的决策，将目录统一工作推迟到未来优化。

• 命名语义：mickqian 进一步询问：“should we use accepts_warmup_image instead, what's the semantics here?”，IPostYellow 阐述：“The semantics here is: warmup should cover the image-conditioned path whenever the model has one... I think the two names are fairly close semantically.”。最终保留 requires_warmup_image，强调了 warmup 必须包含图像输入的场景。

风险与影响

技术风险：

• 分布式同步风险：新增的 broadcast_pyobj 调用若失败，可能导致秩间状态不一致，引发启动错误。
• 目录依赖：依赖 server_args.input_save_path 或临时目录，若权限不足或磁盘空间满，会影响 warmup 执行。
• 测试覆盖不足：变更未附带新测试，可能隐藏边缘情况，如网络延迟导致的广播超时。

影响分析：

• 用户影响：直接修复了服务器启动时的偶发性图像加载失败，提升用户体验和系统可用性。
• 系统影响：在多进程环境下，warmup 初始化更可靠，减少因并发问题导致的启动失败，尤其对图像条件任务至关重要。
• 团队影响：代码变更集中在单个文件，易于审查和维护；但提示了目录处理逻辑的碎片化，建议未来进行统一重构。

关联脉络

本 PR 与近期多个多模态生成相关的 PR 形成脉络：

• PR 22174（"UX: clean loggings"）：同样修改了多模态生成模块的文件，优化日志和参数命名，共享 diffusion 标签，体现了该模块的持续维护。
• PR 22284（"Add fast-fail to multimodal-gen CI"）：涉及多模态生成 CI 测试优化，标签包括 diffusion 和 multimodal，与本 PR 都旨在提升多模态生成系统的可靠性，共同强化测试和运行时稳定性。

整体上，这些 PR 显示团队正专注于多模态生成模块的健壮性改进，从日志清理、CI 效率到核心并发问题修复，逐步完善系统基础设施。