执行摘要

• 一句话：新增Ideogram4 NVFP4 原生支持
• 推荐动作：建议阅读此PR以了解如何在SGLang中集成新的扩散模型和量化方案。重点关注bitsandbytes适配器的设计、Comfy布局推断逻辑以及量化线性层的工厂模式。对于review中提出的两个正确性问题，建议在后续迭代中修复。

功能与动机

SGLang需要原生支持Comfy-Org/Ideogram-4 NVFP4混合精度检查点，以便用户可以直接加载和运行该扩散模型，无需外部转换步骤。

实现拆解

1. 新增量化配置与适配器：在bitsandbytes.py中定义BitsAndBytesConfig类和版本检查函数，在transformer_load_utils.py中添加_BitsAndBytes4BitAdapter，确保在bitsandbytes量化时禁用不兼容的CPU卸载和FSDP推理模式。
2. 改造DiT模型线性层：在ideogram.py中引入Ideogram4QuantizedLinear（继承自ReplicatedLinear），修改_linear工厂函数，根据quant_config参数选择使用原有权重FP8线性或新增的量化线性，同时为所有子模块传递前缀以支持权重挂载。
3. 新增NVFP4流水线：在pipelines/ideogram.py中创建Ideogram4Nvfp4Pipeline子类，实现自动解析NVFP4检查点路径：优先使用server_args.transformer_weights_path覆盖，否则从模型目录下载条件/无条件权重文件，并从基础FP8模型加载其余配置。
4. 增强量化工具：在quantization_utils.py中增加safetensors元数据读取函数_read_safetensors_tensor_metadata和NVFP4张量族识别函数_is_nvfp4_tensor_family，用于推断Comfy检查点的量化布局（swizzled scales等）。
5. 文本编码器量化加载：在encoders/ideogram.py中增加_load_bitsandbytes_4bit_weights方法，当检测到ideogram_bnb_4bit_weight_only配置时，将文本编码器的线性层替换为bitsandbytes 4-bit版本，并加载对应的量化状态。
6. 测试与验证：添加单元测试覆盖路径解析、量化配置推断，以及B200集成测试验证端到端生成一致性。

关键文件：

• python/sglang/multimodal_gen/runtime/layers/quantization/bitsandbytes.py（模块 量化配置；类别 source；类型 dependency-wiring；符号 _require_bitsandbytes, _calculate_quant_ratio, _is_layer_skipped, BitsAndBytesConfig）: 新增BitsAndBytes4Bit量化配置，定义加载逻辑与版本检查，是NVFP4量化支持的核心。
• python/sglang/multimodal_gen/runtime/models/dits/ideogram.py（模块 DiT模型；类别 source；类型 data-contract；符号 _linear, Ideogram4QuantizedLinear, forward, init）: 改造Ideogram4 DiT模型，使线性层支持NVFP4量化，通过_linear工厂函数选择量化类型。
• python/sglang/multimodal_gen/runtime/pipelines/ideogram.py（模块 流水线；类别 source；类型 dependency-wiring；符号 Ideogram4Nvfp4ModelResolution, _resolve_ideogram4_base_model_path, _resolve_ideogram4_unconditional_transformer_weights_path, _resolve_ideogram4_nvfp4_transformer_weights_paths）: 新增Ideogram4Nvfp4Pipeline子类，实现NVFP4检查点路径解析和模型加载。
• python/sglang/multimodal_gen/runtime/loader/transformer_load_utils.py（模块 加载器；类别 source；类型 core-logic；符号 _BitsAndBytes4BitAdapter, init, _maybe_disable_incompatible_offload_modes, prepare）: 添加_BitsAndBytes4BitAdapter，在加载时禁用不兼容的offload模式。
• python/sglang/multimodal_gen/runtime/utils/quantization_utils.py（模块 量化工具；类别 source；类型 core-logic；符号 _infer_nvfp4_group_size_from_shapes, _read_safetensors_tensor_metadata, _is_nvfp4_tensor_family）: 增强NVFP4张量推断，支持Comfy检查点布局的元数据解析。

关键符号：_require_bitsandbytes, BitsAndBytesConfig.init, _linear, Ideogram4QuantizedLinear.forward, resolve_ideogram4_nvfp4_model, _BitsAndBytes4BitAdapter.prepare, _build_nvfp4_config_from_safetensors_files, _load_bitsandbytes_4bit_weights

关键源码片段

python/sglang/multimodal_gen/runtime/layers/quantization/bitsandbytes.py

新增BitsAndBytes4Bit量化配置，定义加载逻辑与版本检查，是NVFP4量化支持的核心。

# SPDX-License-Identifier: Apache-2.0
# bitsandbytes.py — BitsAndBytes 4-bit 量化配置与辅助函数
​
from __future__ import annotations
import torch
from packaging import version
from sglang.multimodal_gen.runtime.layers.quantization.configs.base_config import (
    QuantizationConfig,
)
​
def _require_bitsandbytes() -> None:
    """
    检查 bitsandbytes 版本 >= 0.46.1，若不满足则抛出 ImportError。
    确保后续量化加载操作有正确的运行时环境。
    """
    try:
        import bitsandbytes
        if version.parse(bitsandbytes.__version__) < version.parse("0.46.1"):
            raise ImportError(
                "bitsandbytes version is wrong. Please install bitsandbytes>=0.46.1."
            )
    except ImportError as err:
        raise ImportError(
            "Please install bitsandbytes>=0.46.1 via "
            "`pip install bitsandbytes>=0.46.1` to use bitsandbytes quantizer."
        ) from err
​
class BitsAndBytesConfig(QuantizationConfig):
    """
    预量化 bitsandbytes 4-bit 检查点配置。
    仅支持 load_in_4bit = True 且 quant_type = 'fp4'，
    存储格式必须为 uint8。
    """
    def __init__(
        self,
        load_in_8bit: bool = False,
        load_in_4bit: bool = True,
        bnb_4bit_quant_type: str = "fp4",
        bnb_4bit_quant_storage: str = "uint8",
        bnb_4bit_compute_dtype: str = "float32",
        bnb_4bit_use_double_quant: bool = False,
        llm_int8_skip_modules: list[str] | None = None,
        llm_int8_threshold: float = 6.0,
    ) -> None:
        super().__init__()
        if load_in_8bit or not load_in_4bit:
            raise ValueError("SGLang diffusion only supports bitsandbytes 4-bit.")
        if bnb_4bit_quant_storage != "uint8":
            raise ValueError("Unsupported bnb_4bit_quant_storage.")
        self.load_in_4bit = load_in_4bit
        self.bnb_4bit_quant_type = bnb_4bit_quant_type
​
    @classmethod
    def get_name(cls) -> str:
        return "bitsandbytes"

python/sglang/multimodal_gen/runtime/models/dits/ideogram.py

改造Ideogram4 DiT模型，使线性层支持NVFP4量化，通过_linear工厂函数选择量化类型。

# ideogram.py — Ideogram4 DiT 模型，支持 NVFP4 量化线性层
​
from sglang.multimodal_gen.runtime.layers.linear import ReplicatedLinear
from sglang.multimodal_gen.runtime.layers.quantization.configs.base_config import (
    QuantizationConfig,
)
from sglang.multimodal_gen.runtime.layers.quantization.weight_only_fp8 import (
    WeightOnlyFP8Linear,
)
​
class Ideogram4QuantizedLinear(ReplicatedLinear):
    """包装 ReplicatedLinear，仅返回 output 而不返回 bias。"""
    def forward(self, x: torch.Tensor) -> torch.Tensor:
        # ReplicatedLinear.forward 返回 (output, bias) 元组，这里只取 output
        return super().forward(x)[0]
​
def _linear(
    in_features: int,
    out_features: int,
    bias: bool = True,
    quant_config: QuantizationConfig | None = None,
    prefix: str = "",
) -> nn.Module:
    """
    工厂函数：根据 quant_config 决定创建 WeightOnlyFP8Linear
    还是 Ideogram4QuantizedLinear。
    prefix 用于后续权重加载时从参数字典定位对应的层。
    """
    if quant_config is None:
        return WeightOnlyFP8Linear(in_features, out_features, bias=bias)
    return Ideogram4QuantizedLinear(
        in_features,
        out_features,
        bias=bias,
        quant_config=quant_config,
        prefix=prefix,
    )

评论区精华

评论1（正确性）：在model_specific_stages/ideogram.py第343行，gemini-code-assist[bot]指出如果batch.preset显式为None，getattr返回None会导致ValueError。建议使用getattr(batch, "preset", "V4_DEFAULT_20") or "V4_DEFAULT_20"回退。合并前未明确修复。
评论2（正确性）：在rotary_embedding/mrope.py第132行，评论指出qwen3_apply_rotary_pos_emb中position_ids形状检查不完善：当形状为[3, B, 3]时，由于最后维度长度为3会误触发permute。建议先检查第一维是否为3。同样未被证实已修复。

• batch.preset 为 None 时的 fallback 缺陷 (correctness): 作者未确认是否修复，PR 已合并但该问题可能仍存在。
• position_ids 形状检查误触发导致错误 permute (correctness): 建议未被采纳，PR 合并前未修复。

风险与影响

• 风险：
  1. 依赖风险：新增bitsandbytes>=0.46.1依赖，环境不满足时加载失败。
  2. 布局兼容性：Comfy检查点布局推断基于safetensors元数据键名和形状，若官方调整格式可能导致推断失效。
  3. 遗留缺陷：review中提出的两个边界问题（preset为None、position_ids形状）未经修复，可能在特定输入下触发错误。
  4. 文本编码器加载：bitsandbytes 4-bit权重加载路径可能遗漏某些量化状态，导致推理精度下降。
     - 影响：影响范围限于diffusion模块的Ideogram4模型，其他模型无影响。新增代码1.3k行，主要集中在量化配置和DiT模型改造。对B200 GPU有专门CI验证，无微基准性能退化预期。团队成员需要维护新的量化路径和适配器。
     - 风险标记：新依赖bitsandbytes版本要求, Comfy布局推断脆弱, 文本编码器量化可能遗漏权重, review中未修复的preset边界

关联脉络

• PR #27279 unknown （stacked PR）: 本PR基于此PR，可能包含前置的Ideogram支持。