执行摘要

• 一句话：修复图像编码器折叠建议被静默跳过，改用真实 PipelineConfig
• 推荐动作：值得精读。该 PR 是一个典型的小而关键的 bugfix：一行字段名错误导致整个特性静默失效，且测试 fixture 恰好掩盖了问题。值得学习的是将测试从 SimpleNamespace 迁移到真实配置的做法，以及针对策略矩阵和维度整除性的测试设计。

功能与动机

PR body 指出根因：runtime 和单元 fixture 都引用了不存在的 image_encoder_configs 字段，匹配的假 fixture 让测试保持绿色，而图像编码器折叠建议在服务中被静默跳过。该修复将图像编码器纳入编码器并行折叠，避免 GPU 闲置，并纠正测试与文档。

实现拆解

1. 修复运行时折叠提案：在 python/sglang/multimodal_gen/runtime/server_args/server_args.py 的 ServerArgs.adjust_pipeline_config 中，将 encoder_configs 的构建从 getattr(self.pipeline_config, "image_encoder_configs", ()) 改为直接引用 self.pipeline_config.image_encoder_config，并与 text_encoder_configs 拼接。此前由于字段名错误，图像编码器永远无法进入折叠提案；修改保证每个编码器（文本和图像）都会获得提案。
2. 重建回归测试：在 python/sglang/multimodal_gen/test/unit/test_encoder_world_folding.py 中，将 _run 辅助函数里的 pipeline_config=SimpleNamespace(...) 替换为真实的 PipelineConfig，并将 image 参数从可迭代对象改为单个 ImageEncoderConfig。同时新增两个测试：
   • test_image_encoder_gets_each_policy_proposal：验证 auto、fold、replicate 三种策略下 parallel_folding_mode 分别为 world、replica、world；
   • test_image_encoder_fold_requires_divisible_dims：monkeypatch get_folding_tp_group 后验证维度不可整除时折叠被回退（parallel_folding_mode 保持 None）。
3. 更新文档：docs/docs/sglang-diffusion/encoder_parallel.mdx 明确“folding applies to native text and image encoders”而“within-replica batch DP currently requires an explicitly supported native text encoder”；api/cli.mdx 同步调整 --encoder-parallel 的说明，区分原生编码器的折叠与文本编码器的批量 DP。

配置和部署配套：无；该 PR 仅涉及源码、测试与文档，不新增配置项。

关键文件：

• python/sglang/multimodal_gen/runtime/server_args/server_args.py（模块 参数配置；类别 source；类型 core-logic；符号 adjust_pipeline_config）: 核心修复：将图像编码器配置纳入折叠提案，修正字段名错误。
• python/sglang/multimodal_gen/test/unit/test_encoder_world_folding.py（模块 编码器折叠；类别 test；类型 test-coverage；符号 test_image_encoder_gets_each_policy_proposal, test_image_encoder_fold_requires_divisible_dims）: 测试从假 fixture 迁移到真实 PipelineConfig，并新增图像编码器策略与维度整除性测试。
• docs/docs/sglang-diffusion/encoder_parallel.mdx（模块 文档；类别 docs；类型 documentation）: 明确折叠覆盖原生文本/图像编码器，批量 DP 仅支持原生文本编码器。
• docs/docs/sglang-diffusion/api/cli.mdx（模块 文档；类别 docs；类型 documentation）: 更新 --encoder-parallel 帮助文本，与新的行为对齐。

关键符号：adjust_pipeline_config, test_image_encoder_gets_each_policy_proposal, test_image_encoder_fold_requires_divisible_dims

关键源码片段

python/sglang/multimodal_gen/runtime/server_args/server_args.py

核心修复：将图像编码器配置纳入折叠提案，修正字段名错误。

# 在 adjust_pipeline_config 内部，构建折叠提案的编码器列表
encoder_configs = [
    # 展开全部文本编码器配置
    *self.pipeline_config.text_encoder_configs,
    # 关键修复：改用单数 image_encoder_config，而非不存在的复数字段
    self.pipeline_config.image_encoder_config,
]
​
# 依次为每个编码器设置折叠模式
for encoder_config in encoder_configs:
    encoder_config.parallel_folding_mode = mode

python/sglang/multimodal_gen/test/unit/test_encoder_world_folding.py

测试从假 fixture 迁移到真实 PipelineConfig，并新增图像编码器策略与维度整除性测试。

def test_image_encoder_gets_each_policy_proposal():
    # 验证三种策略下图像编码器均获得预期折叠模式
    expected_modes = {"auto": "world", "fold": "replica", "replicate": "world"}
    for policy, expected_mode in expected_modes.items():
        image = ImageEncoderConfig()
        # 传入单个 ImageEncoderConfig，改用真实 PipelineConfig 构造
        _run([], tp=1, sp=2, cfg=1, image=image, policy=policy)
        assert image.parallel_folding_mode == expected_mode

评论区精华

该 PR 没有 review 评论或讨论线程。提交历史显示两步演进：第一提交修复折叠提案，第二提交使用声明的图像编码器配置，可能是自我审查后的修正。文档变更明确了此前未言明的行为边界。

• 暂无高价值评论线程

风险与影响

• 风险：主要风险是图像编码器此前从未参与折叠提案，修复后可能在现有部署中改变并行行为；如果 PipelineConfig 在部分路径下未设置 image_encoder_config，直接访问可能抛出 AttributeError（旧实现用 getattr 容错）。不过 PipelineConfig 的默认值通常保证该字段存在，且新增测试覆盖了主要策略路径。文档变更可能影响用户对 --encoder-parallel 的预期，需要留意。
• 影响：影响范围：使用 diffusion 服务、并希望通过 --encoder-parallel 折叠图像编码器的用户。修复后图像编码器会被纳入折叠提案，可能提高 GPU 利用率；行为变更可能带来性能变化。对团队而言，回归测试现在使用真实 PipelineConfig，避免假 fixture 掩盖字段名错误。影响程度中等，但仅涉及特定特性路径。
• 风险标记：核心路径变更, 字段引用风险

关联脉络

• 暂无明显关联 PR