执行摘要

• 一句话：logits 处理器辅助函数移到底部并统一 FIXME 注释
• 推荐动作：本 PR 不值得精读实现细节，但可以作为「低风险代码整理」的样例：移动模块级函数、收敛重复注释、在 dataclass 中标注临时字段时，如何保持行为不变同时提升可维护性。对 logits 处理器模块感兴趣的人可以借此了解 mm_input_embeds 的已知设计债（FIXME 指向 GenerationBatchResult 迁移方向）。

功能与动机

作者在 PR body 中说明目标是「move LM-head quantization helper functions to the bottom of logits_processor.py」并「document mm_input_embeds as temporary LogitsProcessorOutput state」以及「remove duplicated FIXME comments」。这是典型的代码卫生整理：量化判定 helper 原本插在上方公共区域，与同文件底部的类逻辑割裂；mm_input_embeds 的 FIXME 在三处重复出现，信息冗余，需要收敛到唯一权威位置。

实现拆解

本 PR 只改动一个文件，实现拆解如下：

1. 移动 LM-head 量化辅助函数：将 _has_lm_head_runtime_attrs 和 should_apply_lm_head_quant_method 从 logits_processor.py 顶部（_UNQUANTIZED_LM_HEAD_METHODS 定义之后、_in_autotune_dummy_run 之前）整体移动到文件末尾（compute_logprobs_for_multi_item_scoring 方法之后）。这两个函数是模块级函数，调用方仍通过模块内名字引用，移动不改变任何调用语义。
2. 统一 mm_input_embeds 的临时状态说明：在 LogitsProcessorOutput dataclass 中为 mm_input_embeds 新增 ## Part 6: Temporary variables 小节，并将原本分散在 forward() 和 compute_logprobs_for_multi_item_scoring() 两处 output 构造位置的重复 FIXME 注释（共 6 行）收敛到字段定义处。这样字段的「非 logits 属性、因 ForwardBatch 局部性而临时透传」这一背景只记录一处，避免读者在多个构造点看到相同注释。
3. 删除重复注释：forward() 和 compute_logprobs_for_multi_item_scoring() 返回 LogitsProcessorOutput 时，仅保留 mm_input_embeds=logits_metadata.mm_input_embeds 的传参，不再附带重复 FIXME。
4. 无测试与配置改动：PR 未修改任何测试文件、配置或 schema。作者仅运行了 pre-commit 和 3 个 ModelOpt LM-head guard 相关测试，确认行为未变。

关键文件：

• python/sglang/srt/layers/logits_processor.py（模块 logits 层；类别 source；类型 refactor；符号 _has_lm_head_runtime_attrs, should_apply_lm_head_quant_method）: 唯一变更文件，包含 LM-head 量化判定 helper 的位置移动、LogitsProcessorOutput 字段注释整理和重复 FIXME 删除。

关键符号：_has_lm_head_runtime_attrs, should_apply_lm_head_quant_method

关键源码片段

python/sglang/srt/layers/logits_processor.py

唯一变更文件，包含 LM-head 量化判定 helper 的位置移动、LogitsProcessorOutput 字段注释整理和重复 FIXME 删除。

# 该 helper 从文件顶部被移动到了文件底部，专门用于判定
# 当前 lm_head 是否应套用对应的量化方法（ModelOpt 等）。
# 位置移动不影响调用方，调用点通过模块级函数名引用。
def should_apply_lm_head_quant_method(lm_head, quant_method) -> bool:
    # 基本前提：必须有量化方法、有 weight 属性、且 apply 可调用，
    # 否则根本不走量化路径。
    if (
        quant_method is None
        or not hasattr(lm_head, "weight")
        or not callable(getattr(quant_method, "apply", None))
    ):
        return False
​
    method_name = type(quant_method).__name__
    # 未量化方法（Embedding/Linear/PackWeight）直接排除。
    if method_name in _UNQUANTIZED_LM_HEAD_METHODS:
        return False
​
    # 部分 draft 模型共享目标模型未量化的 lm_head 张量，却仍携带
    # draft 模型过期的 ModelOpt quant_method。此时必须校验运行时
    # 量化状态是否与 quant_method 匹配，避免误用量化内核。
    if method_name == "ModelOptFp4LinearMethod":
        if lm_head.weight.dtype == torch.int32 and _has_lm_head_runtime_attrs(
            lm_head,
            (
                "weight_scale",
                "weight_global_scale",
                "workspace",
                "input_size_per_partition",
                "output_size_per_partition",
            ),
        ):
            return True
        return lm_head.weight.dtype == torch.uint8 and _has_lm_head_runtime_attrs(
            lm_head,
            (
                "weight_scale_interleaved",
                "alpha",
                "input_scale_inv",
                "input_size_per_partition",
                "output_size_per_partition",
            ),
        )
    if method_name == "ModelOptNvFp4A16LinearMethod":
        return lm_head.weight.dtype == torch.int32 and _has_lm_head_runtime_attrs(
            lm_head,
            (
                "weight_scale",
                "weight_global_scale",
                "workspace",
                "input_size_per_partition",
                "output_size_per_partition",
            ),
        )
    if method_name == "ModelOptFp8LinearMethod":
        return (
            lm_head.weight.dtype == torch.float8_e4m3fn
            and _has_lm_head_runtime_attrs(lm_head, ("weight_scale", "input_scale"))
        )
​
    return True

评论区精华

本 PR 没有 review 评论。唯一的 issue 评论是作者自己在合并前触发的 /tag-and-rerun-ci，用于重新调度 CI。因此不存在实质性的技术争议或设计讨论，可以认为这是一次低争议的代码整理。

• 暂无高价值评论线程

风险与影响

• 风险：本 PR 是纯代码移动和注释整理，风险极低：
  • 逻辑行为完全不变，should_apply_lm_head_quant_method 与 _has_lm_head_runtime_attrs 只是换了源码位置，调用方不受影响。
  • 唯一间接影响是代码可维护性：未来若继续在文件底部扩展 helper，需要留意与文件顶部 _UNQUANTIZED_LM_HEAD_METHODS 常量的距离；若有人按旧位置搜索函数可能短暂困惑，但函数名全局可搜索。
  • CI 的 PR Test (Extra) 显示失败（Run #31299014490），但与本 PR 的逻辑改动没有明显关系，可能是环境性或并发问题；由于没有 review 评论指出，无法进一步定位。
• 影响：影响面限定在 python/sglang/srt/layers/logits_processor.py 的源码组织方式：
  • 对运行时没有任何行为影响，不涉及性能、显存、精度或 API 变更。
  • 对团队的影响是阅读体验改善：量化判定逻辑从文件首屏移到最后，核心 LogitsProcessor 类的相关代码块在 diff 中更紧凑；mm_input_embeds 的临时属性定位更清晰，未来若迁往 GenerationBatchResult 时只需修改字段定义和引用处。
  • 由于是内部文件，外部用户无感知。
  • 风险标记：纯代码移动, 无行为变更, CI 附加任务失败

关联脉络

• 暂无明显关联 PR